docs/advanced-per-agent-configuration.md calls itself the canonical
reference for keeping SKILL.md frontmatter portable, yet nothing in the
repository links to it. Add the frontmatter rule it states to the anatomy
doc's Frontmatter section, and point at it from the README contributing
paragraph and CONTRIBUTING's frontmatter step, so contributors meet the
rule where they read the format.
A step that exists because one model gets a specific call wrong
constrains agents that would have solved the task directly and spends
turns stronger models need for the actual work — cross-model transfer
measurements (WikiSkill, arXiv:2608.27454) show such skills can leave
a stronger model worse off than no skill at all.
Add 'Write the Procedure, Not the Workaround' to skill-anatomy: the
rule (no step justified only by naming a model, version, or one
agent's private tool name), the two smells (over-specified mechanics,
fragmented diagnostics), a model-neutral writing principle, and a
matching pre-flight line in CONTRIBUTING.
Addresses the clarity nit in #236 review: a single supporting doc stays a
loose file, and the skill-local references/ subdir is for grouping several
related docs that travel with the skill. Ties the new bullet back to the
existing Supporting files entry so the framings read as one.
Issue addyosmani#329 asked why shared checklists live in repo-root
references/ instead of being colocated per skill directory as the
Agent Skills spec suggests. The rationale existed only in a comment:
several skills point at the same checklists, and colocating means
either duplication or a single "owner" skill, both of which drift.
Fold that rationale into skill-anatomy.md as a Shared References
section, including the per-skill install portability tradeoff
(addyosmani#361) and a rule of thumb for supporting file vs shared
reference. Cross-link from Naming Conventions.
Co-authored-by: Cursor <cursoragent@cursor.com>
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.
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.
Update all SKILL.md descriptions to lead with what the skill does
(third person) followed by trigger conditions, per Anthropic's
skill authoring docs. All original trigger conditions preserved.
Update description max chars to match Anthropic spec (1024).
Retain workflow-summary warning in skill-anatomy.md to prevent
agents from following descriptions instead of reading full skills.
Add Table of Contents to reference files longer than 100 lines so
Claude can see the full scope of available information even when
previewing with partial reads.
The repository was renamed from swe-skills to agent-skills but
internal references were never updated. This caused:
- session-start.sh to silently fail (path using-swe-skills/ did
not exist; the directory is using-agent-skills/)
- slash commands to invoke non-existent swe-skills: namespace
- docs and setup guides to point at the old clone URL
Rename all occurrences across 14 files: commands, CLAUDE.md,
README tree, docs/, and hooks/.
ayobamiseun