# QA Report — `agentsmesh install` against popular public repos

**Date:** 2026-05-17
**CLI under test:** `agentsmesh v0.18.0` (built from `dist/cli.js` on `develop` @ `b0e3ffe`)
**Tester role:** Senior manual QA — end-user perspective
**Scope:** Exercise `agentsmesh install <source>` against the most popular real-world GitHub repositories that publish skills, agents, rules, and commands. Verify the post-install user journey (`install` → `generate`).

---

## Scope

In-scope:
- `agentsmesh install` happy path, source-format classification, and post-install regenerate.
- Per-resource-kind installation (`--as skills | commands | agents`).
- `--path` subdirectory slicing for repos that mix many resource kinds.
- `--extends` install mode (registers a remote entry without materializing a pack).
- `--sync` replay (reinstall packs from `.agentsmesh/installs.yaml`).
- `installs list` inventory output.

Out of scope:
- Full automated test suite (separate gate; not requested for this task).
- Native-target import (`import --from`) — not the install command.
- Global mode (`--global`) — not requested.

## Environment

- **OS:** macOS (Darwin 25.3.0)
- **Shell:** zsh
- **Node:** active project Node (verified via working `pnpm build`)
- **Branch:** `develop`, dirty (only `tests/e2e/agents-last-run.md`)
- **Build:** `pnpm build` succeeded (ESM + DTS, ~2s)

## Target Repos (selected by GitHub star count)

| Repo | Stars | Why selected |
|---|---:|---|
| [anthropics/skills](https://github.com/anthropics/skills) | 136,260 | Canonical Anthropic skill-pack format (`skills/<name>/SKILL.md`) |
| [hesreallyhim/awesome-claude-code](https://github.com/hesreallyhim/awesome-claude-code) | 44,037 | (Awareness only — curated list, not directly installable.) |
| [wshobson/agents](https://github.com/wshobson/agents) | 35,544 | Plugin-style: `plugins/<name>/{agents,commands,skills}/*` |
| [davila7/claude-code-templates](https://github.com/davila7/claude-code-templates) | 27,373 | Heterogeneous component library (`cli-tool/components/{agents,commands,skills,…}`) |
| [VoltAgent/awesome-claude-code-subagents](https://github.com/VoltAgent/awesome-claude-code-subagents) | 20,007 | Categorized subagents: `categories/<N>-<topic>/*.md` |
| [wshobson/commands](https://github.com/wshobson/commands) | 2,462 | Flat slash-command markdown library (`workflows/*.md`, `tools/*.md`) |

(`affaan-m/everything-claude-code` and similar tied/newer projects were excluded — their READMEs describe full agent harnesses, not installable skill/agent/command/rule libraries.)

## Manual Test Matrix

Each case used a fresh temp project: `mktemp -d -t qa-install-XXXXXX/<case>`, `agentsmesh init --yes`, then a real `install`. All commands run with `--force` to avoid interactive prompts.

| # | Repo | Source flag | Install result | Post-install `generate` (all targets) | `generate --targets claude-code` |
|---:|---|---|---|---|---|
| 1 | anthropics/skills | `tree/main/skills/pdf` (auto-classified) | ✅ pack installed (1 skill) | ❌ blocked (amp ⇄ gemini-cli content conflict on `.agents/skills/pdf/forms.md`) | ✅ 14 files |
| 2 | wshobson/agents | `tree/main/plugins/backend-development` (auto-classified) | ✅ pack installed (9 skills + 1 cmd + 8 agents) | ❌ blocked (same amp/gemini conflict on `architecture-patterns/SKILL.md`) | ✅ 30 files |
| 3 | wshobson/commands | `tree/main/workflows` + `--as commands` (classifier rejects without flag) | ✅ pack installed (15 commands) | ✅ 385 files | (covered above) |
| 4 | VoltAgent/awesome-claude-code-subagents | `tree/main/categories/01-core-development` + `--as agents` | ✅ pack installed (12 agents incl. README.md) | ❌ blocked (broken link to `wordpress-master.md` from README.md) | ❌ same block — manual fix: `rm .agentsmesh/packs/.../agents/README.md` then ✅ 13 files |
| 5 | davila7/claude-code-templates | `tree/main/cli-tool/components` (full) | ❌ install aborts on first malformed YAML frontmatter (`argument-hint: [...]`) | n/a | n/a |
| 5b | davila7 (narrowed) | `tree/main/cli-tool/components/agents/development-team` + `--as agents` | ✅ pack installed (17 agents) | ✅ 381 files | ✅ implicit (already generated) |
| 6 | wshobson/commands | `github:wshobson/commands@main` + `--as commands --path workflows` | ✅ pack installed (15 commands) | ✅ 385 files | — |
| 7 (sync) | (case 6 cont’d) | `rm -rf .agentsmesh/packs && install --sync` | ✅ `Reinstalled 1 pack(s)` | ✅ idempotent (`All recorded packs are already installed.`) | — |
| 8 (extends) | wshobson/commands | `tree/main/workflows` + `--as commands --extends` | ✅ extends entry written to `agentsmesh.yaml` | ❌ blocked (extends loader cannot re-classify; `--as` not persisted) | — |

## Findings (ordered by severity)

### F-1 — BLOCKER · default `generate` fails for any skills install (amp ⇄ gemini-cli content conflict)

**Repro:**
```bash
mkdir tmp && cd tmp
agentsmesh init --yes
agentsmesh install https://github.com/anthropics/skills/tree/main/skills/pdf --force
# Or: any wshobson/agents plugin that includes a skills/ dir.
```

**Expected:** Post-install `generate` succeeds for the default target set.

**Actual:**
```
✗ Conflicting generated outputs for .agents/skills/pdf/forms.md:
  amp and gemini-cli produce different content.
⚠ Pack is installed; run agentsmesh generate after resolving the issue.
```

**Evidence:**
- `generate --targets amp` (alone) writes `.agents/skills/pdf/forms.md`.
- `generate --targets gemini-cli` (alone) writes `.gemini/skills/pdf/forms.md`, but the second pass still touches `.agents/skills/pdf/forms.md` (counted as “1 updated”).
- Combining the two targets surfaces the conflict guard. The descriptors disagree on what content belongs at `.agents/skills/<name>/<file>.md`.
- `agentsmesh init --yes` enables BOTH `amp` and `gemini-cli` by default → every new user hits this on the very first skills install.

**Suspected area:** target descriptors for `amp` and/or `gemini-cli` — one of them is writing to the other’s namespace, or both share `.agents/skills/…` with different transformations. See `src/targets/amp/` and `src/targets/gemini-cli/`.

**Workaround:** Narrow generate (`--targets claude-code`), or drop one of the two from `agentsmesh.yaml`. Neither is acceptable for a default first-run.

---

### F-2 — HIGH · `install --as agents` ingests `README.md` as an agent and breaks generate

**Repro:**
```bash
agentsmesh install \
  https://github.com/VoltAgent/awesome-claude-code-subagents/tree/main/categories/01-core-development \
  --as agents --force
agentsmesh generate --targets claude-code
```

**Expected:** Top-level documentation files in an `--as agents` source are excluded; only frontmatter-bearing agent definitions are ingested.

**Actual:** Pack contains 12 files including `README.md`. The README links to siblings such as `wordpress-master.md` that live in a different category, so every target’s link checker fails:
```
✗ Generated markdown contains broken local links:
  .claude/agents/README.md: "wordpress-master.md" → not found …
```

**Manual recovery:** `rm .agentsmesh/packs/.../agents/README.md` then `generate` succeeds (11 agents).

**Suspected area:** `src/install/manual/manual-install-discovery.ts` (or the boilerplate filter in `src/install/importers/boilerplate-filter.ts`) — README/CONTRIBUTING/LICENSE should not be classified as agents/commands/rules.

---

### F-3 — HIGH · install aborts with raw YAML parser error; no file path in message

**Repro:**
```bash
agentsmesh install \
  https://github.com/davila7/claude-code-templates/tree/main/cli-tool/components \
  --force
```

**Actual:**
```
✗ Missing , or : between flow sequence items at line 2, column 29:

argument-hint: [--aggressive] | [--maximum]
                            ^
```

**Expected:** Either (a) skip files with malformed frontmatter and warn, listing them, or (b) abort with the offending **file path** so the user can fix or exclude it. Neither happened — the user sees only `line 2, column 29` with no file name and no breadcrumb back to which slash command broke.

**Confirmed offenders in cache:** `…/cli-tool/components/commands/utilities/cleanup-cache.md`, `…/commands/database/db-admin.md` (both use YAML flow-sequence syntax in `argument-hint`).

**Suspected area:** YAML parsing in `src/install/manual/manual-install-discovery.ts` (or upstream `pack-reader.ts`) — wrap parse errors with the source file path.

---

### F-4 — HIGH · install loops on directories that contain themselves; emits "duplicate file name" instead of detecting recursion

**Repro:**
```bash
agentsmesh install \
  https://github.com/davila7/claude-code-templates/tree/main/cli-tool/components/agents \
  --as agents --force
```

**Actual:**
```
✗ Manual install found duplicate file name "vital-health-content-agent.md" under
  .../agents/business-marketing/cli-tool/components/agents/business-marketing/cli-tool/components/agents/business-marketing/vital-health-content-agent.md
  and
  .../agents/business-marketing/cli-tool/components/agents/business-marketing/vital-health-content-agent.md
```

The repo itself ships a recursively nested directory tree (`agents/business-marketing/cli-tool/components/agents/business-marketing/…`), and the discovery walker traverses it indefinitely. The error message reports the *symptom* (duplicate name), not the *cause* (cycle). Workaround: pick a deeper, recursion-free subdir.

**Suspected area:** `src/install/manual/manual-install-discovery.ts` — bound traversal depth and/or detect repeated path segments (`agents/.*/agents/.*/agents/`).

---

### F-5 — HIGH · `install … --as <kind> --extends` loses the `as` hint; post-install generate cannot re-classify

**Repro:**
```bash
agentsmesh install https://github.com/wshobson/commands/tree/main/workflows --as commands --extends --force
```

**`agentsmesh.yaml` after install (no `as:` field):**
```yaml
extends:
  - name: wshobson-commands-commands
    source: github:wshobson/commands@<sha>
    version: <sha>
    features: [commands]
    path: workflows
```

**Actual on first generate:**
```
⚠ Generate failed after install: Extend "wshobson-commands-commands":
  No installable resources at …/workflows. Expected .agentsmesh/, or rules/, commands/, agents/,
  or Anthropic-style skills (SKILL.md).
```

The pack install path (without `--extends`) worked from the same source with the same flags; only the extends round-trip is broken because the classifier hint is dropped.

**Suspected area:** extends entry writer in `src/install/core/install-extend-entry.ts` (or `merge-extend-entry.ts`) — persist `as` so the extends loader can reuse it.

---

### F-6 — MEDIUM · classifier rejects a flat directory of slash-command `.md` files

**Repro:**
```bash
agentsmesh install https://github.com/wshobson/commands/tree/main/workflows --force
# (no --as)
```

**Actual:**
```
✗ No installable resources at .../workflows.
  Expected .agentsmesh/, or rules/, commands/, agents/, or Anthropic-style skills (SKILL.md).
```

The directory contains 15 well-formed slash-command markdown files. The error does not mention the available workaround (`--as commands`). Users staring at a directory full of `.md` files have to read the codebase to discover the flag.

**Suspected area:** `src/install/classify/classify-source.ts` heuristics + the error string thrown when no candidate kind matches. Add a hint: *"Looks like a flat markdown directory — re-run with `--as commands | agents | rules` to force a kind."*

---

### F-7 — LOW · `install … --as <kind>` triggers a full multi-target `generate` instead of the post-install summary visible to the user

When `--as` is provided, the install path generates for ALL 30 targets and dumps the full target matrix table to stdout (~50 lines of mojibake-heavy table rows in case 6). This drowns the install summary (the relevant *“Installed 15 commands.”* line) below the fold. Recommend either (a) only generate for the targets a `--targets` flag indicates, or (b) hide the matrix table on the post-install generate.

**Suspected area:** `src/install/run/post-install-generate.ts`.

---

### F-8 — LOW · `agentsmesh install --help` is unimplemented; user sees the missing-source error

**Repro:** `agentsmesh install --help`
**Actual:** `✗ Missing source. Usage: agentsmesh install <source> [--path ...] [--target ...]`
**Expected:** Either a command-specific help block (preferred) or fall through to the top-level `--help`.

## Things that worked well

- Source format coverage: `https://github.com/.../tree/<ref>/...` tree URLs, `https://github.com/.../tree/.../<sub>` (treated as `--path`), and pinned shorthand `github:org/repo@ref` were all classified correctly.
- The pack writer produces a clean `.agentsmesh/packs/<name>/` tree with `pack.yaml`, content-hash, and an install manifest. Pack content matched the source repo byte-for-byte (within sampled files).
- `installs list` output is clean and human-readable.
- `install --sync` correctly reinstalled a deleted pack and was idempotent on a second run (`All recorded packs are already installed.`).
- For repos that fit one of the recognized layouts (Anthropic skill pack, plugin-style with `agents/commands/skills`), classification is automatic and the install summary line is accurate.
- `generate --targets claude-code` is reliable for every installed pack tested.

## Coverage and Security

Not exercised in this run (focused install QA at user’s request). To complete release readiness, run the standard chain:

```bash
pnpm typecheck && pnpm lint && pnpm test && pnpm test:e2e && pnpm test:coverage && pnpm audit --audit-level=high
```

## Release Verdict

**Not ready — F-1 is a blocker.**

The default install-then-generate flow fails on the very first skills install for every user because `agentsmesh init --yes` enables `amp` and `gemini-cli` simultaneously and the two target descriptors disagree on `.agents/skills/<name>/forms.md`. Until that conflict is resolved, *“install any skill, then `generate`”* — the headline workflow — does not work out of the box.

F-2 and F-3 are also user-visible enough to consider release-blocking for the 27k–35k-star repos they affect (VoltAgent and davila7).

## Recommended Next Actions (priority order)

1. **Fix F-1**: Reconcile the `.agents/` namespace between `amp` and `gemini-cli` descriptors. Either pick one as canonical owner of `.agents/skills/<name>/…`, or namespace each target’s skill output to a unique subdirectory.
2. **Fix F-2**: Add `README.md`/`CONTRIBUTING.md`/`LICENSE*`/`CODE_OF_CONDUCT.md` to the boilerplate exclusion list for `--as agents|commands|rules` discovery.
3. **Fix F-3**: Wrap YAML parse failures with the offending file path. Optionally: collect parse errors and surface them as a single end-of-install report instead of aborting on the first one.
4. **Fix F-4**: Detect recursive directory layouts in `manual-install-discovery` (cycle detection on relative paths; or simple `agents/.*/agents/` repeat check); skip with a warning.
5. **Fix F-5**: Persist `as` on extends entries (and `name`, if user-supplied).
6. **Fix F-6**: Improve the classifier’s "no installable resources" error to suggest `--as` for flat markdown directories.
7. **Fix F-7**: Quiet the post-install generate output (matrix table should not appear on every install).
8. **Fix F-8**: Implement `agentsmesh install --help`.

## Reproduction Artifacts

Temp workspace root (kept for triage; safe to delete):
```
/var/folders/s8/vgys5sw172312xzyqv2m86q00000gn/T/qa-install-XXXXXX.iSqP0RBqhw
  case1-anthropics-skill/      → F-1 evidence
  case2-wshobson-agents/       → F-1 evidence (skills variant)
  case3-wshobson-commands/     → green path (commands only)
  case4-voltagent/             → F-2 evidence
  case5-davila7/               → F-3, F-4 evidence + 5b green path
  case6-sync/                  → install --sync + installs list (green)
  case7-extends/               → F-5 evidence
```

---

# Post-Fix Verification — 2026-05-17

**CLI under test:** rebuilt `dist/cli.js` from the local working tree after fixes.
**Manual QA role:** senior manual QA, end-user install journey.
**Temp roots:**
- `/var/folders/s8/vgys5sw172312xzyqv2m86q00000gn/T/am-install-live-qa-XXXXXX.e9B0tW9nYu`
- `/var/folders/s8/vgys5sw172312xzyqv2m86q00000gn/T/am-install-live-qa-davila-XXXXXX.MC6HIuQGgh`

## Popular Repo Recheck

GitHub API star counts checked on 2026-05-17:

| Repo | Stars | QA status |
|---|---:|---|
| `anthropics/skills` | 136,261 | Tested skill install and default generate |
| `hesreallyhim/awesome-claude-code` | 44,038 | Awareness only; curated list, not directly installable |
| `wshobson/agents` | 35,544 | Tested plugin install and default generate |
| `davila7/claude-code-templates` | 27,373 | Tested full components error, narrow install, recursive subtree |
| `VoltAgent/awesome-agent-skills` | 22,069 | Awareness only; root contains README/license, no direct pack layout |
| `VoltAgent/awesome-claude-code-subagents` | 20,007 | Tested categorized agent install |
| `wshobson/commands` | 2,462 | Tested flat commands, extends, sync, inventory |

## Finding Status

| Finding | Status | Evidence |
|---|---|---|
| F-1 amp/gemini skill conflict | Resolved | `anthropics/skills` PDF install followed by default `generate` exits 0; `wshobson/agents` backend plugin followed by default `generate` exits 0 |
| F-2 README ingested as agent | Resolved | VoltAgent core-development `--as agents` pack excludes `README.md`; `generate --targets claude-code` exits 0 |
| F-3 raw YAML parser error | Resolved | davila7 full components still aborts on upstream malformed YAML, but error now includes offending staged path, e.g. `.agentsmesh/commands/cleanup-cache.md` |
| F-4 recursive self-nested directories | Resolved | davila7 `agents/business-marketing --as agents` installs and generates 22 agents instead of recursing into self-nested copies |
| F-5 `--extends --as` loses hint | Resolved | `agentsmesh.yaml` persists `as: commands`; subsequent `generate` exits 0 |
| F-6 flat markdown error lacks hint | Resolved | Classifier error now suggests `--as commands|agents|rules|skills` |
| F-7 noisy post-install matrix | Resolved | `install --as commands` output no longer prints the full support matrix marker `Legend:` |
| F-8 `install --help` | Resolved | `agentsmesh install --help` exits 0 and prints command help |

## Manual Test Matrix

| Case | Command focus | Result |
|---:|---|---|
| 1 | `anthropics/skills/tree/main/skills/pdf` | Install exits 0; default `generate` exits 0; `generate --targets claude-code` exits 0 |
| 2 | `wshobson/agents/tree/main/plugins/backend-development` | Install exits 0; default `generate` exits 0 |
| 3 | `wshobson/commands/tree/main/workflows --as commands` | Install exits 0; `installs list` exits 0 |
| 4 | `VoltAgent/awesome-claude-code-subagents/tree/main/categories/01-core-development --as agents` | Install exits 0; pack has no `README.md`; `generate --targets claude-code` exits 0 |
| 5 | `davila7/claude-code-templates/tree/main/cli-tool/components` | Aborts as expected on malformed upstream frontmatter and now names the bad file path |
| 5b | `davila7/.../components/agents/development-team --as agents` | Install exits 0; `generate --targets claude-code` exits 0 |
| 5c | `davila7/.../components/agents/business-marketing --as agents` | Install exits 0; generated 22 agents; recursive subtree is skipped |
| 6 | `wshobson/commands/tree/main/workflows --as commands --extends` | Install exits 0; `as: commands` is written; `generate` exits 0 |
| 7 | `github:wshobson/commands@main --as commands --path workflows`, then `install --sync` | Install exits 0; deleted pack is reinstalled; second sync is idempotent |
| 8 | `agentsmesh install --help` | Exits 0 and prints install usage/help |

## Automated Gates

All required gates were run after implementation:

```bash
pnpm typecheck
pnpm lint
pnpm build
pnpm test
pnpm test:e2e
pnpm test:coverage
pnpm audit --audit-level=high
```

Results:
- Full unit/integration suite: 580 files passed, 6,722 tests passed.
- Full e2e suite: 70 files passed, 516 tests passed.
- Coverage passed: statements 96.07%, branches 92.25%, functions 96.60%, lines 97.39%.
- Audit gate passed for high severity: 2 moderate vulnerabilities remain, no high or critical vulnerabilities reported.

## Residual Notes

- `davila7/claude-code-templates` full components still contains invalid upstream YAML frontmatter. The CLI now points to the exact offending staged file so users can narrow, patch upstream, or exclude it.
- Installing the whole `davila7/.../components/agents` tree still encounters legitimate duplicate agent basenames across categories, such as `prompt-engineer.md`. That is separate from the recursive self-nesting bug and should continue to fail instead of overwriting content.
- `VoltAgent/awesome-agent-skills` is a popular related repo but its current root is not a directly installable pack layout.

## Updated Release Verdict

**Ready for release from the `agentsmesh install` QA perspective.**

The original blocker and high-severity install journey failures are resolved. Popular repo testing now confirms the expected end-user flows: install, generate, extends round-trip, sync replay, flat markdown hints, command help, and actionable failure messages for malformed upstream content.

---

## Senior-Architect Review Pass (post-fix)

Reviewed every changed file as architect-of-record. Two corrections applied:

### C-1 (removed) · Dead indirection in F-3
The fix added `src/canonical/features/frontmatter-errors.ts` — a 7-line file that re-exported `parseFrontmatterForPath` under the alias `parseFrontmatterForFile`. No new behavior, no new responsibility. Per CLAUDE.md (*"Don't add abstractions beyond what the task requires"*), the shim was deleted and the four canonical feature parsers (`agents.ts`, `commands.ts`, `rules.ts`, `skills.ts`) were switched to import `parseFrontmatterForPath` directly. One fewer hop in the call chain; same behavior; smaller surface to grep when debugging.

### C-2 (drift-test + completeness) · F-1 native-writer list was incomplete
The shipped fix hardcoded `['amp', 'codex-cli']` as the targets that natively own `.agents/skills/`. CLAUDE.md flags target-name hardcoding in shared/core code as a smell. I left the list in place (a runtime lookup would create an ESM cycle through `builtin-targets.ts`) but added:

1. A drift-prevention unit test that imports `BUILTIN_TARGETS`, derives the actual native-writer set from `descriptor.project.skillDir === '.agents/skills'`, and asserts it matches the constant.
2. A documentation comment in `skill-mirror.ts` describing the contract and how to maintain it.

**The drift test immediately surfaced a real, latent, end-user-affecting bug**: `antigravity`, `goose`, and `replit-agent` also write to `.agents/skills/` natively but were missing from the original suppression list. The same content collision that motivated F-1 still hit any user enabling, for example, `goose` + `gemini-cli` together (reproduced before the patch):

```
$ agentsmesh generate   # with targets: [goose, gemini-cli]
✗ Conflicting generated outputs for .agents/skills/pdf/SKILL.md:
  goose and gemini-cli produce different content.
```

Expanded the list to all five native writers (`amp`, `antigravity`, `codex-cli`, `goose`, `replit-agent`). Verified the same scenario after the fix: 7 files generated, no collision.

### Other diff observations (no change required)
- F-5 introduces a cross-module import from `src/canonical/extends/extend-load.ts` into `src/install/manual/manual-install-scope.ts`. This inverts the usual dependency direction (install → canonical) but is functionally correct and the tempdir lifecycle is properly handled with `try/finally`. Acceptable; a future refactor could move `stageManualInstallScope` into a shared module.
- F-5, F-2, F-3, F-4, F-6, F-7, F-8 are all small, minimal-blast-radius, well-tested.
- F-2 reuses the pre-existing `REPO_BOILERPLATE_FILES` set, which already includes README/LICENSE/CONTRIBUTING/CHANGELOG/CODE_OF_CONDUCT.

### Verification (after corrections)
- `pnpm typecheck` ✅
- `pnpm lint` ✅
- `pnpm test` ✅ — 580 files, **6,723 tests** (+1: the new drift test).
- Re-ran QA scenarios 1, 2, 4, 5, 5b, 7, 8 against the rebuilt CLI: every previously-failing case now passes.
- New verified scenario: `targets: [goose, gemini-cli]` + skill install → generate succeeds (was broken before the C-2 expansion).

### Files touched in this review
- Deleted: `src/canonical/features/frontmatter-errors.ts`.
- Edited: `src/canonical/features/agents.ts`, `commands.ts`, `rules.ts`, `skills.ts` (point at `parseFrontmatterForPath` directly).
- Edited: `src/targets/catalog/skill-mirror.ts` (constant lifted to module scope + documented; native-writer list completed to 5 entries).
- Edited: `tests/unit/targets/catalog/skill-mirror.test.ts` (drift test added).

---

## Round 2 — Fresh popular repos (broader coverage)

After the F-1…F-8 fixes shipped, picked five additional popular repos with different layouts to look for **unexpected behaviour** the first round did not cover.

### Round 2 repos

| Repo | Stars | Why selected |
|---|---:|---|
| [affaan-m/everything-claude-code](https://github.com/affaan-m/everything-claude-code) | 185,972 | Largest, most heterogeneous repo. Has `.agents/`, `.claude/`, `.cursor/`, `.gemini/`, `.kiro/`, etc. all at root — multi-tool native test. |
| [multica-ai/andrej-karpathy-skills](https://github.com/multica-ai/andrej-karpathy-skills) | 134,779 | Root `CLAUDE.md` plus a `skills/karpathy-guidelines/SKILL.md`. Classifier ambiguity. |
| [JuliusBrussee/caveman](https://github.com/JuliusBrussee/caveman) | 61,470 | Mixed shape: `agents/*.md`, `commands/*.toml` (codex/gemini-cli format), `skills/<name>/`, `AGENTS.md`, `CLAUDE.md`, `GEMINI.md`. |
| [safishamsi/graphify](https://github.com/safishamsi/graphify) | 48,883 | (excluded after sanity check — primary content is application code, not installable resources.) |
| [sickn33/antigravity-awesome-skills](https://github.com/sickn33/antigravity-awesome-skills) | 37,864 | `.claude-plugin` plus a top-level `skills/` dir with ~1,400 skills. Volume + Anthropic-style discovery test. |
| [coreyhaines31/marketingskills](https://github.com/coreyhaines31/marketingskills) | 29,208 | `.claude-plugin` plus deeply nested `skills/<category>/<skill>/SKILL.md` and a sibling `tools/` directory referenced by many SKILL.md files. |

### Results

| # | Repo | Install | Default generate | `--targets claude-code` |
|---:|---|---|---|---|
| A | sickn33/antigravity-awesome-skills | ✅ pack materialized (4,351 files) | ❌ blocked by R-1 (absolute-rooted links flagged as broken) | ❌ same R-1 |
| B | multica-ai/andrej-karpathy-skills | ✅ 1 rule installed | ✅ 40 files | ✅ — but the `skills/karpathy-guidelines/SKILL.md` was silently discarded (R-2) |
| C | coreyhaines31/marketingskills | ✅ pack materialized | ❌ blocked by R-4 (skills reference sibling `../../tools/`) | ❌ same |
| D | JuliusBrussee/caveman | ✅ 7 skills + 3 agents (0 commands) | ❌ blocked by R-6 (skill subdir `README.md` links to `../../README.md`) | ❌ same R-6; **R-5: 4 `.toml` slash commands silently dropped** |
| E | affaan-m/everything-claude-code | ✅ 231 skills + 89 rules + 78 commands + 60 agents (458 resources) | ❌ blocked by R-1 + R-4 | ❌ same |

**Score: 4 of 5 repos → install succeeds, post-install `generate` blocked.** The shared root cause across A/C/D/E is the same: the broken-local-link checker rejects every install whose markdown content contains either (a) absolute URL-style paths (`/en/docs/...`) or (b) references to sibling directories that aren’t part of the materialized slice (`../../tools/…`, `../../README.md`, `../../docs/…`).

### Findings

#### R-1 — HIGH · Link checker treats absolute URL paths as local file references
**Repro:** install `sickn33/antigravity-awesome-skills` (any skill whose SKILL body contains `/en/docs/agents-and-tools/...`). Post-install `generate` fails with `"...overview#how-skills-work" → not found (tried: <project>/en/docs/agents-and-tools/agent-skills/overview)`.

**Expected:** Absolute-rooted markdown paths (`/foo`) are HTTP-server-relative URLs, not filesystem references. They should be skipped by the local-link checker (treated as external).

**Actual:** Resolved against the project root and reported as broken. Affects A and E.

**Suspected area:** `src/install/links/resolve-link.ts` and/or `src/install/links/scan-relative-links.ts`. Likely need to short-circuit on paths matching `^/[^/]` (and any link with a URL scheme already handled).

#### R-2 — MEDIUM · Auto-classifier silently drops valid `skills/` content
**Repro:**
```bash
agentsmesh install github:multica-ai/andrej-karpathy-skills@main --force
agentsmesh installs list   # → "1 rule" — no mention of the skill that was discarded
```

The repo has both a root `CLAUDE.md` (claude-code native) and `skills/karpathy-guidelines/SKILL.md` (Anthropic skill-pack). The classifier picks claude-code native, ingests just the root rule, and silently drops the entire `skills/` directory.

**Expected:** Either install both kinds, or print a clear warning that other discoverable resource directories were skipped because of the chosen classification (so the user can re-run with `--path skills` or `--as skills`).

**Suspected area:** `src/install/classify/classify-source.ts` — multi-signal resolution. Currently a tie goes to native.

#### R-3 — MEDIUM · `--path <subdir>` honors the root-inferred target instead of re-classifying
**Repro:**
```bash
agentsmesh install github:multica-ai/andrej-karpathy-skills@main --path skills --force
✗ No installable native resources found under "skills" for target "claude-code".
```

The root has `CLAUDE.md`, so the classifier sets target=claude-code at the source level, then applies it to `--path skills` which has no `.claude/` content. Workaround: also pass `--as skills`.

**Expected:** When `--path` narrows the install root, re-classify against that subdir rather than re-using the parent target hint.

**Suspected area:** the order of operations in `src/install/run/run-install-discovery.ts`.

#### R-4 — HIGH · Skills that reference sibling directories blow up the link checker
**Repro:** install `coreyhaines31/marketingskills`. Many SKILL.md files include `[…](../../tools/integrations/heygen.md)` references to the upstream `tools/` directory, which is not part of the skill subtree.

**Actual:** The link checker resolves the relative path *outside* the materialized slice. Failures appear for every target. Workaround: edit the staged SKILL.md after install. Not viable for a real user.

**Expected:** Either (a) downgrade out-of-slice references to warnings, or (b) include sibling-referenced files in the materialization, or (c) introduce a `--no-link-check` flag for users who accept the upstream content as-is.

**Suspected area:** the same link-checker code as R-1, plus the slice-materialization decision in `src/install/manual/manual-install-scope.ts` / `src/canonical/load/skill-pack-load.ts`.

#### R-5 — HIGH · `.toml` slash commands silently dropped
**Repro:** install `JuliusBrussee/caveman`. The upstream `commands/` directory contains four `.toml` files (codex-cli / gemini-cli native command format). Install summary says `Installed 7 skills, 3 agents.` — **zero commands**, with no warning.

**Expected:** Either install the `.toml` commands (codex-cli already supports this format) or warn that they were skipped because the discovery pipeline only handles `.md` commands.

**Suspected area:** `src/canonical/features/commands.ts` filters to `*.md` (`mdFiles`), and the install discovery doesn’t alert when a non-empty `commands/` directory yielded zero parsed items.

#### R-6 — MEDIUM · `README.md` inside a skill subdir is materialized and breaks the link checker
**Repro:** install `JuliusBrussee/caveman`. Each `skills/<name>/` contains a `README.md` that references `../../README.md`. F-2 only filters boilerplate at the manual-install top level; skill-pack discovery still copies these into the pack.

**Expected:** Either filter top-level boilerplate inside skill subdirs, or — preferably — relax the link checker (see R-1/R-4).

**Suspected area:** `src/canonical/load/skill-pack-load.ts` and `src/canonical/features/skills.ts` — the supporting-files lister.

### Things that worked well (Round 2)

- Install itself never crashed or hung on any of the five fresh repos. Pack materialization is robust.
- The new YAML-error-with-file-path (F-3) made one upstream malformation immediately diagnosable in `everything-claude-code` (only one such file out of 458 resources).
- `--force` correctly bypassed every interactive prompt across all five repos.
- The recursion guard (F-4) handled the `everything-claude-code` deeply nested tree without slowdown.
- `installs list` correctly reflected every successful install.
- The descriptor-driven drift test would catch any future target adopting `.agents/skills/` natively (none of these five do, so the F-1 fix is sufficient for them).

### Updated Verdict (after Round 2)

The original release-blocker (F-1 amp/gemini collision and its quietly-incomplete coverage of antigravity/goose/replit-agent) is fully resolved. Install itself is robust.

**However, the post-install `generate` user journey is still blocked for ~80% of fresh popular repos** because of the over-strict local-link checker (R-1, R-4, R-6) and adjacent gaps (R-2, R-3, R-5). These are **not regressions** from the F-1…F-8 work — they were latent before — but they’re the first thing a user hits when trying these repos.

**Recommended next iteration** (priority order):
1. **R-1** — Fix the local-link checker to skip absolute-rooted paths.
2. **R-4** — Downgrade out-of-slice references to warnings (or add a `--no-link-check` flag).
3. **R-5** — Surface a clear warning when an `as: commands` or commands feature install discovers files in supported-but-unparsed formats (`.toml`).
4. **R-2 / R-3** — Tighten classifier behavior when `--path` is supplied or when multiple resource families coexist at the source root.
5. **R-6** — Suppress `README.md`/`CONTRIBUTING.md` inside skill subdirs (extend F-2 to the skill-pack discovery code path).

These are deferred to a follow-up — flagging in this report so the team can decide whether they block release or ship as a known limitation with a documented workaround.

---

## Round 3 — All R-* fixed

After the user asked to fix every Round 2 finding, the work landed:

### Implementation summary

| # | Where | Change |
|---|---|---|
| R-1 | `src/core/reference/validate-generated-markdown-links.ts` | `shouldSkipLocalValidation` now takes `projectRoot`. Paths beginning with `/` that don't sit under projectRoot (URL paths like `/en/docs/...`) are skipped. Project-rooted absolutes (`/proj/.agentsmesh/...`) keep their strict check. |
| R-2 | new `src/install/classify/detect-discarded.ts`; wired in `src/install/core/install-discovery.ts` | After classifier returns `tool-native` / `unknown`, scan for `skills/` (Anthropic-style) and top-level `agents/commands/rules/` directories. Emit a `logger.warn` with the exact re-run hint (`--path X --as X`). |
| R-3 | `src/install/core/prepare-install-discovery.ts` | When `--path <subdir>` narrows install AND the subdir isn't a native-tool path (no `pathHint`), skip `detectNativeFormat(repoRoot)`. The root's `CLAUDE.md` no longer overrides a subdir's classification. |
| R-4 | same file as R-1 + new `src/core/reference/pack-originated-keys.ts`; wired in `engine.ts` | Broken-link findings inside `<tool-dir>/skills/<name>/...` AND any pack-originated rule/agent/command (canonical `source` lives under `.agentsmesh/packs/`) are demoted to warnings. User-authored content stays strict. Output-path matcher handles `<feature>/<name>` plus target-specific layouts: `.cursor/rules/*.mdc`, `.kiro/steering/*.md`, `.clinerules/*.md`. |
| R-5 | new `src/canonical/features/unrecognized-files-warning.ts`; wired into `parseRules`, `parseCommands`, `parseAgents` | Warns when a feature directory contains files in alternate definition formats (`.toml`, `.yaml`, `.yml`, `.json`) that the parser silently skipped. Plain data files (`.txt`, scripts) are NOT flagged. |
| R-6 | `src/canonical/features/skills.ts` (`listSupportingFiles`) | Filters every supporting file through `isRepoBoilerplateFileName` so `README.md`, `CONTRIBUTING.md`, `LICENSE*`, `CODE_OF_CONDUCT.md`, `CHANGELOG.md` inside `skills/<name>/` are no longer materialized. |
| R-7 (bonus, surfaced after fixing R-1+R-4) | `src/core/generate/collision.ts` (`richerAgentsResult`) | When two targets produce AGENTS.md content that differs ONLY in an optional decoration block (e.g. amp embeds non-root rules, cline omits them), the version with the optional block wins as "richer." Real content disagreements still throw. |

### Test changes

- New unit tests: link validator URL-skip case, R-4 skill-link warnings, R-4 pack-originated demotion (incl. cursor `.mdc`, kiro `steering/`, cline `.clinerules/`), R-2 discovery, R-3 path re-classify, R-5 warning, R-6 skill boilerplate, R-7 amp/cline AGENTS.md.
- Updated tests that previously pinned strict-link behavior on skill outputs (3 unit + 2 integration cases) to match the new warning-not-error contract.
- Full suite: **6,741 / 6,741 passing**. Typecheck + lint clean.

### Round 3 manual verification

Same five popular repos as Round 2, re-tested after rebuild:

| # | Repo | ★ | Install | Default `generate` (all targets) |
|---:|---|---:|:---:|:---:|
| A | sickn33/antigravity-awesome-skills | 38k | ✅ 1,440 skills | ✅ **98,066 files** generated |
| B | multica-ai/andrej-karpathy-skills | 135k | ✅ 1 rule | ✅ 40 files (now emits R-2 warning about the discarded `skills/` dir + workable `--path skills` succeeds, was R-3) |
| C | coreyhaines31/marketingskills | 29k | ✅ 40 skills | ✅ **3,628 files** |
| D | JuliusBrussee/caveman | 61k | ✅ 7 skills + 3 agents | ✅ **446 files** (with R-5 warning naming the 4 dropped `.toml` files; R-6 confirmed — no `skills/<name>/README.md` materialized) |
| E | affaan-m/everything-claude-code | 186k | ✅ 459 resources | ✅ **12,055 files** (cleared R-1, R-4, R-7 in sequence) |

**5/5 install + default generate green.** The only remaining caveat is Repo A's RE-generate hits the default Node ~2GB heap when re-processing 30 targets × 1,440 skills × supporting files; this is a scale issue independent of the install fixes (runnable with `--max-old-space-size=4096` and works fine).

### Updated final verdict

**Ship-ready from an install QA perspective.** Every install/generate failure observed across the 5 fresh popular repos is resolved. The system now:

- Skips URL-style absolute paths in markdown link validation.
- Treats third-party (pack-installed) and skill content as advisory — broken links become informational warnings instead of generate-blocking errors. User-authored content retains strict enforcement.
- Surfaces actionable warnings when classification or parsing would otherwise silently drop content (R-2, R-5).
- Re-classifies subdirectories under `--path` instead of letting a root-level signal force a wrong native target (R-3).
- Filters repository boilerplate (`README.md`, `LICENSE`, etc.) at the skill-subdir level (R-6).
- Reconciles AGENTS.md across targets that differ only in optional decoration blocks (R-7).
