The /plan command specifies saving the plan to tasks/plan.md and
tasks/todo.md, but the planning-and-task-breakdown skill (the canonical
source) had no file path instructions. When spec-driven-development
transitions to Plan phase, it references the skill directly, bypassing
the /plan command, causing plans to be written to the wrong location.
- Add Output Files section to planning-and-task-breakdown with explicit
tasks/plan.md and tasks/todo.md paths
- Add path instruction to Step 1 (Enter Plan Mode)
- Add Output convention note to spec-driven-development Phase 2
Resolve AGENTS.md conflict: keep this PR's pointer to docs/skill-anatomy.md
(the section main patched via #307 is the one this PR removes, so the
line-level fix is moot once the section is gone).
Also fix a stale path the port reintroduced: skill-anatomy.md referenced
/mnt/skills/user/... for scripts; correct it to the repo-relative
skills/<skill-name>/scripts/<script>.sh, matching #307.
git-workflow-and-versioning had versioning in its name but no versioning content.
Adds a Release & Versioning section: semver as a consumer contract, tag-as-source-
of-truth, and human-readable changelogs written with the change. Cross-links
api-and-interface-design, deprecation-and-migration, and shipping-and-launch.
Add a Pull Requests section and a Boundaries bullet to CLAUDE.md: before
opening a PR, search the upstream repo's open PRs and issues for overlapping
work and coordinate instead of opening a conflicting PR. Wording is generic
about remote names so it applies regardless of fork setup.
The validator claims to check skills "against the rules in
docs/skill-anatomy.md", but two rules that doc marks as Required were
never enforced:
- Directory names must be lowercase-hyphen-separated (Naming Conventions).
Previously only `name === dirName` was checked, so `My_Skill/` passed.
- Descriptions must say *when* to use the skill, not just what it does
(Required vs Recommended). Formalized in #167 but the validator was
never updated to match.
Adds both as blocking checks. All 24 existing skills pass, so this is a
non-breaking guardrail. Closes the remaining gap in #233 (frontmatter,
name-match, and section checks already shipped in the original validator).
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Address review feedback on #317:
- Wire the Definition of Done into incremental-implementation as a final
per-task gate, so the doc's intro list and the See Also links agree.
- Cross-link the Quality and Ship-readiness items to the skills that own
their depth (code-review-and-quality, code-simplification,
security-and-hardening, observability-and-instrumentation,
shipping-and-launch).
Addy flagged that the AGENTS.md cleanup in #313 dropped two still-accurate subsections with no home elsewhere. Port them into docs/skill-anatomy.md, the canonical home for skill structure, so the dedup cleanup keeps the real guidance it was never meant to remove.
Introduce a project-wide Definition of Done as a standing bar every change clears before it counts as done, distinct from the per-task acceptance criteria the project already covers.
The concept existed implicitly across the project (per-task acceptance criteria, per-skill Verification sections, the pre-launch checklist) but was never named or unified. This adds a single reusable checklist and wires it in without duplicating existing content:
- references/definition-of-done.md: the standing checklist, grouped into Correctness, Quality, Integration, Documentation, and Ship-readiness, plus a table contrasting Definition of Done with acceptance criteria.
- using-agent-skills: linked from Core Operating Behavior #6 (Verify, Don't Assume), the bar that applies across all skills.
- planning-and-task-breakdown: See Also note clarifying acceptance criteria sit on top of the standing bar.
- shipping-and-launch: See Also pointer as the floor beneath the deploy-specific gates.
- README: entry in the Reference Checklists table.
Add anti-duplication guardrails so agents working in this repo follow the CONTRIBUTING.md pre-flight checklist before adding a skill, keeping CONTRIBUTING.md as the single source of truth instead of duplicating it.
- CLAUDE.md: add a Contributing pointer plus a pre-flight Boundaries rule
- AGENTS.md: replace the stale "Creating a New Skill" section (the repo has no per-skill zips and scripts are optional) with a pointer to CONTRIBUTING.md and docs/skill-anatomy.md
- .claude/rules/skills-contributing.md: path-scoped rule (skills/**) that loads the dedup guardrail only when editing skills
Address review feedback on the Plan and Tasks delegation pointers. Both
pointers now state that planning-and-task-breakdown takes precedence if
the inline summaries ever diverge, removing the drift ambiguity. Unify
both pointers to the blockquote form for consistency.
The file-size paragraph used "1000 total lines" adjacent to the "~1000
lines changed" diff threshold, which let readers conflate "diff too
large" with "file too large". Spell out the distinction inline and
reframe total file length as an inspection signal rather than a hard cap.
Addresses @federicobartoli's review feedback on #304.
The /mnt/skills/user/ prefix was an artefact of the Anthropic workbench
environment where skills were originally developed. These paths do not
exist in a standard git clone.
Replace all three occurrences with the correct repo-relative path:
/mnt/skills/user/{name}/scripts/{script}.sh -> skills/{name}/scripts/{script}.sh
The script referenced in idea-refine/SKILL.md (idea-refine.sh) already
exists at skills/idea-refine/scripts/idea-refine.sh.
Fixes#136
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
The /ship command referenced .gemini/agents/ as the subagent directory on two
occasions, but this directory does not exist in the repository. The agent
definitions (code-reviewer.md, security-auditor.md, test-engineer.md) live at
the repo root under agents/. As a result Gemini CLI could not resolve the
subagents and the parallel fan-out in Phase A would silently fail.
Fixes#259
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
When agent-skills is installed as a Claude Code plugin, the plugin loader emits
a cosmetic warning about the root commands/ folder being ignored in favour of
.claude/commands/. The root commands/ directory is intentional (Antigravity CLI),
so the warning confuses installers into thinking something is broken.
Add a Note callout under 'Using Commands' in getting-started.md clarifying that
the warning is expected and all Claude Code commands load correctly.
Fixes#298
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
Per review: the paragraph said both "Required-by-default" and "flag and
suggest by default", which are opposite stances. Collapse to a single
stance — propose the simpler design for each signal, escalate to Required
only when the change actively makes structure worse.
Our five-axis review is broad but treats structural maintainability passively
("could this be fewer lines?"). This adds the depth a great reviewer brings to
structure, folded into the existing axes/process rather than a separate mode:
- Architecture axis: "reduce, don't relocate" (does the refactor delete
complexity or just move it?), canonical-layer/helper-reuse discipline, and
explicit type-boundary checks.
- Readability axis: treat new conditionals bolted onto unrelated flows and
repeated same-shape conditionals as missing-abstraction signals, not nits.
- New "Structural Remedies" section: name the restructuring move, not just the
problem (typed dispatcher, collapse duplicate branches, separate orchestration
from logic, reuse canonical helper, etc.).
- Change Sizing: gate total file size, not just diff size (~1000-line smell).
- Step 4: "lead with what matters" finding-prioritization rule.
- Verification: presumptive blockers, calibrated to our approval philosophy
(surface and propose the simpler design; block only when structure gets worse).
- Matching Common Rationalizations and Red Flags.
Purely additive; validator passes (24 skills, 0 errors).
The Plan and Tasks phases of spec-driven-development restated planning
mechanics that the dedicated planning-and-task-breakdown skill already owns.
Add a one-line delegation pointer to each phase naming that skill as the
canonical source for dependency-graph mapping, vertical slicing, task sizing,
and ordering, mirroring how the Implement phase already delegates to
incremental-implementation and test-driven-development. The inline bullets and
task template stay as a lightweight quick reference.
The "Categorize Findings" table defines Critical, Required (no prefix),
Optional/Consider, Nit, and FYI. Two other spots used labels outside that
set: the Multi-Model Review prompt said "Critical, Important, or Suggestion"
and the Verification checklist referenced "All Important issues". "Important"
and "Suggestion" are never defined, so an agent following the skill can't map
them to a severity. Align both to the taxonomy.
Add a "Before proposing a new skill" subsection to CONTRIBUTING.md that
defines a checklist contributors run before opening a new-skill PR: search
the existing catalog, check open PRs for overlapping proposals, confirm the
idea fits the skill anatomy, and justify in the PR description why it isn't
already covered.
The goal is to set clear rules/guidelines that curb duplication, since the
open-PR backlog has accumulated clusters of near-duplicate skill proposals.
Reorganize the section into "Before proposing a new skill" and "Creating the
skill" so the decision step comes before the how-to.
Per review feedback: clarify that cherry-picking individual skills works,
but running two frameworks as active routers at once causes command-name
conflicts, competing routing, and clashing TDD philosophies. Recommend
one primary router + à la carte borrowing.
Resolve README.md Reference Checklists table conflict by keeping both new
rows: observability-checklist (this PR) and orchestration-patterns (#290,
already on main).
The Stop-the-Line Rule and Triage Checklist each have exactly 6 steps
(1-6). "Steps 4-10" referenced steps that never existed — this was an
original error present since the file's first commit, not a leftover
from a previous 10-step structure. Correct the range to match the
actual 6-step content.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
