scaffold: `skills add --all` writes the bundle three times (~1.6 MB, byte-identical) and the template `_gitignore` excludes none of it, so every new project's FIRST commit vendors it in triplicate

[os-sam]

domain:* / type / priority are triage's.

Found while building a real app on the published scaffold (objectstack-ai/ats) — the duplication reached that repository's initial commit before anyone noticed it.

Measured (origin/main 3e270d4e)

• packages/create-objectstack/src/index.ts:533:

  execSync('npx -y skills add objectstack-ai/objectstack/skills --all', { … })

  --all is documented by the skills CLI as shorthand for --skill '*' --agent '*' -y. The --agent '*' half fans the catalog out to every agent runtime the CLI knows, and src/index.ts:524 already records this as an assumption ("assumed: skills add --all fans the catalog out to every agent").
• packages/create-objectstack/src/created-summary.ts:17 measured the result on published create-objectstack@17.1.0:

  .agents/  49    agent/  49    .claude/  11
  

  .claude/skills/* are symlinks into .agents/skills/; agent/skills/ is a full second copy for a different runtime.
• packages/create-objectstack/src/templates/blank/_gitignore — complete contents:

  node_modules
  dist
  .objectstack/
  *.log
  .DS_Store
  .env
  .env.*
  

  Neither .agents/ nor agent/ is excluded.

Reproduced on a real project: the initial commit of objectstack-ai/ats carried 133 files, of which 46 were .agents/skills/**, 46 a byte-identical agent/skills/**, and 11 symlinks — about 804 KB of duplication. Removing the duplicate copy and reinstalling with --skill '*' --agent claude-code -y took the repository to 76 files and produced a clean 13,361-line deletion; skills-lock.json was unchanged, because it records source and hash, not paths.

What is and is not the defect

Installing for several runtimes is defensible — a project may be opened in Claude Code, Cursor and Codex. The defect is that all copies are committed. Three byte-identical trees in git review as noise forever: they bloat the first diff anyone reads, they re-appear in every skills add update as a three-way churn, and nothing tells the author which copy is canonical. The scaffolder's own summary comment already calls the phase-3 output "two ~968 KB trees of agent instructions … landed on the user's disk unnamed".

The ask

Pick one canonical committed location and keep the rest out of git. Either route is acceptable; state the choice in the changeset.

• Route A (minimal, recommended). Keep --all, and add to the template _gitignore:

  .agents/
  agent/
  

  .claude/skills/ symlinks resolve into .agents/, so if .agents/ is ignored the symlinks dangle for a fresh cloner — therefore Route A must also make .claude/skills/ the committed real copy, or ignore all three and treat skills-lock.json as the source of truth with a one-line README instruction to run skills add. Decide and encode it; do not leave dangling symlinks in a fresh clone.
• Route B. Install for one agent by default (--skill '*' --agent claude-code -y), print the one-line command for other runtimes in the closing summary. Smallest checkout; costs the multi-runtime default.

Whichever route: a fresh create-objectstack run followed by git add -A && git status must show the skills bundle once, and a fresh clone of that commit must have working skill files (no dangling symlink).

Acceptance

• A scaffolded project's first git add -A stages the bundle exactly once.
• Cloning that commit into a clean directory yields readable SKILL.md files at whatever path the project committed.
• create-objectstack's scaffold test asserts the staged-once property (count the staged SKILL.md paths).
• Changeset: create-objectstack patch for Route A, minor for Route B (behaviour change in what gets installed).

Not in this card

The missing CI workflow (separate card). The accuracy of the printed "Created files" summary — created-summary.ts already documents that problem and its reasoning; this card only changes what lands in git.

[os-sam]

Triage: lands in objectstack-ai/objectstack, domain:cli (packages/create-objectstack per the lane table); type Task. Routed by this session under the maintainer direct-dispatch channel, on the instruction quoted verbatim:

在 objectstack 提两个 issue，objectstack这些问题你都接手直接派发

Held behind #16330 — deliberately not dispatched in parallel. Both cards edit packages/create-objectstack, and both add an assertion to the same scaffold test, so batch independence forbids the pair in one batch. The five folding gates fail at gate ① (different defect shape, different fix), so this is serialisation rather than a fold. #16330 is in flight now; this card returns to selection when its PR lands.

Two notes for whoever takes it, so the round does not rediscover them:

1. The route choice in "The ask" is an in-card decision, not a needs_decision. Pick A or B, record which in the changeset, and say why in the PR body. Escalate only if both routes turn out to be wrong.
2. Route A's trap is the symlinks. .claude/skills/* are symlinks into .agents/skills/; ignoring .agents/ while committing .claude/ leaves a fresh cloner with dangling links. The acceptance criterion "cloning that commit yields readable SKILL.md files" is the one that catches it, and it is not satisfiable by a _gitignore edit alone.

Measured evidence for the duplication is in the body; it was reproduced end to end on objectstack-ai/ats, whose initial commit carried the bundle three times before it was cleaned up.

domain:cli seat #6024 is not being taken over by this session — see the routing note on #16330.

---

Generated by Claude Code

[os-sam]

Claim: PM loop round 2
Session: session_01PbJ5Cy9KDAzeQHo8bsMadG
Branch: claude/issue-16331-skills-single-copy
Worktree: objectstack-issue-16331
Domain: domain:cli
File surface: packages/create-objectstack/ (stop on breach; explain in the report)
Container & model: S, mode:subagent, model: opus (no path-derived mandate — dispatch-gates --tier returned "no path-derived mandate" for this package's surface; PM judgement, raised from the floor because the route choice has a fresh-clone failure mode that a mechanical tier would not weigh)
Clause-②: no
Serial constraints cleared: the block is lifted. #16330 landed as 4998efa7 on origin/main at 2026-09-06T17:21Z (PR #16364, squash), so packages/create-objectstack is free and the shared scaffold test is no longer being edited by another card. Verified on the tree, not from the notification: git cat-file -e origin/main:packages/create-objectstack/src/templates/blank/.github/workflows/ci.yml succeeds and the template's scripts.lint reads objectstack lint. No other in-flight domain:cli card touches this package.

Routing and dispatch continue under the maintainer direct-dispatch channel quoted on #16330; domain:cli seat #6024 is still not taken over.

---

Generated by Claude Code

[claude]

Claim: os-dev subagent (dispatched by the PM loop, round 2)
Session: session_01PbJ5Cy9KDAzeQHo8bsMadG (subagent inside the dispatching PM session)
Branch: claude/issue-16331-skills-single-copy — pushed empty at 4998efa7 as the landing marker
Worktree: ../objectstack-issue-16331 (dedicated; the shared checkout is untouched)
File surface: packages/create-objectstack/ plus one changeset
Inherited: assignee and the PM Claim: above; this session writes neither the assignee nor a second card claim beyond this comment.

Route decision (A vs B) is taken in-card per the triage note; the choice and the fresh-clone verification result will be recorded in the changeset, the PR body and the os-dev-report comment on this card.

---

Generated by Claude Code

[claude]

os-dev-report

{
  "issue": 16331,
  "status": "done",
  "branch": "claude/issue-16331-skills-single-copy",
  "pr": "https://github.com/objectstack-ai/objectstack/pull/16401",
  "premise_still_valid": true,
  "summary": "Route B. The scaffolder now runs `npx skills add objectstack-ai/objectstack/skills --skill '*' --agent claude-code -y` instead of `--all`, from one shared builder in the new `src/skills-install.ts` that also produces the per-runtime hint the closing summary prints. `_gitignore` is unchanged on purpose: with one destination there is nothing to exclude. A new test asserts the staged-once property end to end through the real CLI under a stubbed PATH, and the template's own AGENTS.md and README now name the per-agent form so a project cannot re-acquire the second copy by following its own docs. Card premise holds; three measured corrections, none of which change the defect: the three trees are not byte-identical (35 of 46 files are; the 11 SKILL.md files differ by re-serialised frontmatter plus one blank line), the on-disk total is 1,210,118 B not ~1.6 MB, and `created-summary.ts:17`'s `.agents/ 49 · agent/ 49 · .claude/ 11` re-measures today as 46 · 46 · 11 (that comment is explicitly a published-17.1.0 measurement, so it was left as history and only its phase-3 line, which describes current behaviour, was updated).",
  "route": "B (minor changeset) — chosen on measurement, not preference",
  "gates": {
    "derived_families": 55,
    "run": 55,
    "not_measured": 0,
    "unrun": 0,
    "reconciliation": "node scripts/pm/dispatch-gates.mjs --repo objectstack-ai/objectstack --ran RANFILE -> '55 derived famil(ies) accounted for — 55 run, 0 NOT-MEASURED'",
    "template_families_pulled_in": [
      "pnpm --filter @objectstack/spec run check:template-manifests -> exit 0",
      "pnpm check:template-version-sync -> exit 0",
      "pnpm check:published-files -> exit 0"
    ],
    "package_tests": "pnpm --filter create-objectstack test -> Test Files 16 passed (16), Tests 203 passed (203)",
    "package_typecheck": "pnpm --filter create-objectstack typecheck -> exit 0; tsc --listFiles confirms src/skills-install.ts and src/scaffold-skills-single-copy.test.ts are both in the program",
    "affected_packages": "TURBO_SCM_BASE=4998efa7 turbo ls --affected -> 8 packages; packages/cli built + `vitest run --project unit` green (181 files, 2438 passed, 6 expected fail, 15 skipped). The other six reach this diff only through create-objectstack/created-summary, whose built dist/created-summary.js and .d.ts are byte-identical sha256 when the source is reverted to origin/main and rebuilt.",
    "lint": "pnpm lint (full repo-wide `eslint . --no-inline-config`) -> exit 0 in 100s at 604dc4d2. Full scan, not a narrowing.",
    "nul_bytes": "pnpm check:nul-bytes -> exit 0; plus a manual grep -naP over every touched file, no control bytes",
    "prerequisite_notes": [
      "check:dual-build-cjs-loads and check:type-check-debt first answered PREREQUISITE NOT MET (exit 3) on an unbuilt workspace closure — NOT MEASURED, not red. Both exit 0 after building the closure.",
      "check:type-check-debt then OOM'd under the container default NODE_OPTIONS=--max-old-space-size=4096, which is tighter than the 6144 ceiling the gate pins for itself; exit 0 at the gate's own ceiling.",
      "check-plugin-teardown-shape --self-test exited 1 on a shallow checkout that could not reach its pinned fixture commit; exit 0 after `git fetch origin 621a487607881c66b2899b7e3477115229a156b4`."
    ],
    "ablation": "From a committed implementation: reverted SKILLS_INSTALL_COMMAND to `--all`. On-disk landing proved before running (injected marker grep -c = 1, removed anchor grep -c = 0, blob hash 6d504595 != HEAD f10ff5de). Direction: TURNED RED, 9 of 14 cases, with the defect's own signature — staged roots ['.agents','agent'], 6 staged SKILL.md instead of 3, 3 symlinks. Restore leg: `git checkout HEAD -- PATH`, `git diff HEAD` empty, blob hash back to f10ff5de. Subject resolves through a relative src import, not through dist/exports, so the dist-preflight hazard class does not apply; the red itself proves the mutation reached the subject."
  },
  "clone_verification": {
    "method": "real scaffolder + REAL skills CLI (only the package manager stubbed; an install is irrelevant to the skills bundle), then git init, git add -A, commit, git clone into a clean directory",
    "staged_total": 62,
    "staged_skill_md_paths": 11,
    "staged_symlinks": 0,
    "untracked_after_add": 0,
    "clone_readable_skill_md": 11,
    "clone_dangling_symlinks": 0,
    "clone_bundle_bytes": 604102,
    "no_agents_dir": true,
    "pre_fix_control": "the same steps on the `--all` shape stage 22 SKILL.md paths + 11 symlinks",
    "route_a_naive_control": "ignoring .agents/ and agent/ while committing .claude/ was built and cloned: 0 staged SKILL.md, 11 staged symlinks, and the clone has 11 dangling symlinks with 0 readable SKILL.md — the triage note's trap, reproduced"
  },
  "line_budget": "N/A — no skills/** path in the diff (governed slice of the diff is empty), so no SKILL.md line or token ratchet applies",
  "files_changed": [
    ".changeset/scaffold-skills-single-committed-copy.md",
    "packages/create-objectstack/README.md",
    "packages/create-objectstack/src/created-summary.ts",
    "packages/create-objectstack/src/index.ts",
    "packages/create-objectstack/src/scaffold-skills-single-copy.test.ts",
    "packages/create-objectstack/src/skills-install.ts",
    "packages/create-objectstack/src/template-consistency.test.ts",
    "packages/create-objectstack/src/templates/AGENTS.md",
    "packages/create-objectstack/src/templates/blank/README.md"
  ],
  "tests": "pnpm --filter create-objectstack test -> 16/16 files, 203/203 tests. New file src/scaffold-skills-single-copy.test.ts, 14 cases across three blocks: the command's shape, an end-to-end scaffold staged and cloned, and a vacuity block that replays the `--all` row and requires the same assertions to fail. The stubbed skills CLI refuses an argv it has no measured row for (exit 3), so a command nobody measured fails loudly instead of passing against an invented layout. Ablation and gate evidence under `gates`.",
  "mcp_calls": "0 — every GitHub read and write went through the repo-scoped REST channel (probe: GET /repos/objectstack-ai/objectstack -> 200). /search/issues is 403 by proxy design, so duplicate search used the REST list endpoint plus local grep, with control words (16330, 16350, 16373, 16331) confirming the read was real.",
  "deviations": [
    "Route B taken (minor changeset), per the in-card ruling. Route A was not merely declined: both of its shapes were built, committed and cloned, and `--all --copy` was measured at 56 destination directories / 33.8 MB. Two rejection reasons: a `core.symlinks=false` clone turns Route A's 11 committed symlinks into ordinary files holding the link target, and a `_gitignore` deny-list must chase a destination set this package does not own.",
    "File surface respected: everything is under packages/create-objectstack/ plus the one changeset. The two template markdown files were edited in surface and deliberately — they told the scaffolded project's readers to run the bare interactive form, and choosing 'all' there re-creates the triplicate inside the user's own repository. They widened the derived gate list by exactly the two template families the dispatch predicted; both run green.",
    "The existing pin `template-consistency.test.ts` -> 'scaffolder installs from the curated skills/ subpath' asserted `toContain('… --all')` against index.ts source TEXT. Changing the command would have made that half vacuous, so it now asserts the VALUE the scaffolder runs, and a second case keeps a hand-written duplicate invocation out of both modules. The /skills subpath boundary itself is unchanged and still enforced.",
    "`_gitignore` is deliberately NOT edited. With one destination there is nothing to exclude, and ignore entries for directories we no longer create are dead text.",
    "No `pnpm lint` narrowing was needed or claimed: the full repo-wide scan ran, exit 0 at 604dc4d2.",
    "Zone 2 assumption 2 verified against skills@1.5.23 rather than inherited: `--all` is documented as `--skill '*' --agent '*' -y`, confirmed. Refinement — in the default symlink mode `--all` writes three top-level directories, not one per known runtime; the 56-directory fan-out only appears with `--copy`.",
    "Zone 2 assumption 3 re-measured: 46 · 46 · 11 today, not the 49 · 49 · 11 recorded from published 17.1.0. That comment labels itself a 17.1.0 measurement, so it stays as history; only its phase-3 line, which describes current behaviour, was rewritten."
  ],
  "open_questions": [],
  "out_of_scope_findings": [
    "filed as #16400: five documentation surfaces still instruct `skills add … --all` (content/docs/getting-started/your-first-project.mdx:45,283 · build-with-claude-code.mdx:57,381 · content/docs/ai/skills-reference.mdx:27 · content/docs/ai/skills.mdx:35 · skills/README.md:9). Two of them describe what the scaffolder does and go stale with this PR; all five reproduce the triplication independently for any reader who follows them inside a git repository. Outside this card's file surface, and skills/** is a governed surface. Unassigned, no label — a concrete defect for triage, not an observation."
  ]
}

---

Generated by Claude Code