Repository navigation
feat(aidd-context): align skill-generate with Anthropic's skill authoring guidance #1016
Closed as not planned
Description
Problem
aidd-context:04-skill-generate writes every new skill in the framework. Today it produces skills that miss several points of Anthropic's official guidance. Each gap repeats in every skill it generates.
| Anthropic guidance | What the generator does today |
|---|---|
| "Keep references one level deep from SKILL.md. All reference files should link directly from SKILL.md." [1] | The router table names actions by bare slug, with no link. References are linked only from actions, two levels from SKILL.md. |
| "Always write in third person." [2] | Its own contract asks for third person, but the template yields "Generate…", and so does its own description. |
| "Create evaluations BEFORE writing extensive documentation." [3] Run prompts with and without the skill [9]. | No test prompts, no baseline without the skill. |
| "Match the level of specificity to the task's fragility and variability." [4] | No guidance on how strict a risky step must be (push, delete, publish). |
disable-model-invocation and hooks frontmatter [8]. "Claude skipped a rule that must hold every time: move the rule into a hook." [10] |
Neither field is ever chosen. None of the 51 shipped skills uses them. |
| Copyable checklist, and "Run validator → fix errors → repeat" [5][6] | Steps have no completion check and no "return to step N". The review runs in the context that wrote the files. |
| After compaction only the start of a skill is kept, "so put the most important instructions near the top of SKILL.md" [10][11] | The router's rules sit at the bottom. |
| "For reference files longer than 100 lines, include a table of contents at the top." [7] | No such rule. |
| "Don't instruct Claude to reproduce its reasoning in the response." [12] | No such rule. |
Scope
- Authoring contract: add the points above, and amend the router, action and description rules.
- Router template: rules first, every action linked, a
## Referencestable linking each reference. - Action template: each step ends on "Done when", with a "return to step N" on failure.
- New evals template: 3 prompts that trigger, 1 that must not, each with a baseline.
- Scope step records the risk (stays in the workspace, or reaches outside) and the baseline. The write step adds
disable-model-invocationand hooks when the risk is outside. The validate step reviews in a fresh context and re-runs the evals. - Apply all of it to the generator's own SKILL.md.
Acceptance criteria
- The generator's SKILL.md links every action, reference and asset directly
- Its description opens on a third-person verb
- A generated skill holds 3+1 eval prompts, each with a baseline
- A generated skill that pushes, publishes or deletes sets
disable-model-invocation: true - Each generated step ends on "Done when", and each check has a return line
- Repository pre-commit and
scripts/__tests__pass
Prior art in this repo
- refactor(framework): replace skill test sections with scoped rules #985 removes
## Testsections and renamesTransversal rulestoRules. It touches the same contract. Order to agree. - PR docs(aidd-context): keep skill instructions readable and coherent #981 (open) edits the same authoring contract file.
- docs(framework): fiabiliser les descriptions des skills sous troncature Codex #794 covers description length under Codex truncation.
Out of scope
- Migrating the 50 other skills to the new contract. A follow-up issue.
- Evals for the generator itself: it asks the user to confirm, and the headless eval harness runs a single turn (same limit as
01-brainstorm).
References
- https://platform.claude.com/docs/en/agents-and-tools/agent-skills/best-practices#avoid-deeply-nested-references
- https://platform.claude.com/docs/en/agents-and-tools/agent-skills/best-practices#writing-effective-descriptions
- https://platform.claude.com/docs/en/agents-and-tools/agent-skills/best-practices#build-evaluations-first
- https://platform.claude.com/docs/en/agents-and-tools/agent-skills/best-practices#set-appropriate-degrees-of-freedom
- https://platform.claude.com/docs/en/agents-and-tools/agent-skills/best-practices#use-workflows-for-complex-tasks
- https://platform.claude.com/docs/en/agents-and-tools/agent-skills/best-practices#implement-feedback-loops
- https://platform.claude.com/docs/en/agents-and-tools/agent-skills/best-practices#structure-longer-reference-files-with-table-of-contents
- https://code.claude.com/docs/en/skills#frontmatter-reference
- https://code.claude.com/docs/en/skills#evaluate-and-iterate-on-a-skill
- https://code.claude.com/docs/en/skills#claude-stops-following-a-skill
- https://code.claude.com/docs/en/skills#skill-content-lifecycle
- https://platform.claude.com/docs/en/build-with-claude/prompt-engineering/prompting-claude-fable-5#recommended-scaffolding-changes
Activity
cdialloTK8 commentedon Oct 13, 2026
Duplicate of #1017, reopened under the author's personal account.