Skip to content

Skills and subagents ship as a repository plugin, not vendored in the template

Status: accepted

The template previously vendored the entire skill set under skills/skills/ and the development subagents under .claude/agents/ (mirrored into .codex/ and .kilo/), then materialised per-tool dirs at bootstrap with link-skills.sh (see 0001). That made the template the integration point for skill content: every skill fix had to be copied into every downstream project, and the tracked file count was dominated by skill source that had nothing to do with the consuming project.

We extracted the skills and subagents into a separate, versioned repository — seed1207/tooling-skills-agents — structured as a Claude Code plugin with a marketplace entry (the same mechanism astral and postgres-best-practices already use). The template now declares the dependency and installs the plugin at bootstrap rather than carrying the skill bodies. This realises proposal P1 from docs/research/2026-06-10-harness-redesign-proposals.md.

Considered Options

  • Keep vendoring skills + link-skills.sh. No new install step. Rejected: skill fixes don't propagate (every project re-copies), the tracked tree is dominated by skill source, and cross-tool mirrors (.codex/, .kilo/) multiply the maintenance surface.
  • Git submodule for skills/. Single source of truth without a plugin. Rejected: submodules are awkward for agents and don't give the tool-native skill discovery a plugin install does; no versioned, semver-pinnable release surface.
  • Repository plugin (chosen). Skills and subagents live upstream, are versioned and released once, and arrive via /plugin install. Child repos pin a version and upgrade deliberately; fixes propagate by releasing the plugin.

Consequences

  • Bootstrap gains a first step: install the plugin (/plugin marketplace add seed1207/tooling-skills-agents → /plugin install) before running /setup-project. Documented in README.md, CONTRIBUTING.md, and docs/guides/operator-runbook.md.
  • skills/, .claude/agents/, plugin-managed .codex/ content, .kilo/, and scripts/link-skills.sh are removed from the repo. .claude/skills/, .claude/agents/, and plugin-managed .codex/ content are gitignored and populated by the plugin installer. Project-owned lifecycle configuration, such as .codex/hooks.json, remains repository code.
  • scripts/doctor.sh no longer enforces skill parity against a vendored skills/skills/; it now warns when no skills are present, pointing to the plugin install.
  • The slash commands referenced throughout the docs (/setup-project, /grill-with-docs, /to-prd, /to-issues, /tdd, /diagnose, etc.) continue to work — they are now provided by the plugin instead of the local tree.