2.2 KiB
Skill Lifecycle and Selection
When to Use a Skill
Use a skill when its description matches the task and it provides a repeatable workflow, validation sequence, or domain context. Repository AGENTS.md files should name skills conditionally for work that needs them. Do not require unrelated skills or load every reference by default.
When to Recommend a Skill
Recommend adding or updating reusable guidance when a task or review reveals a recurring multi-step procedure, repeated agent/user friction, a stable validation sequence, or a lasting policy gap. Prefer a focused skill over a broad catch-all. Keep always-applicable policy in the owning AGENTS.md; keep stable explanatory material in docs/instructions/; keep task workflows in a skill.
When to Raise It in a Conversation
Check for a worthwhile library improvement at natural handoff points: when requested work is complete, a change is ready for PR review, or a PR review/merge discussion is wrapping up. Raise it briefly in the completion summary or handoff, with the proposed file and reason. Do not interrupt implementation for a speculative candidate, and do not suggest an update for a one-off fix or routine minor change. If the improvement is clearly in scope, make it and summarize it; otherwise recommend it for a follow-up.
The goal is a useful, low-noise library, not a checklist item in every conversation. A high-impact policy gap can justify one recommendation even before a pattern repeats; ordinary workflow skills should be based on demonstrated reuse.
When to Add or Update a Skill
Create a repo-local directory at .agents/skills/<skill-name>/ with a SKILL.md containing front matter name and a concise description that says both what the workflow does and when it applies. Keep the main workflow short. Put optional supporting material in references/, executable helpers in scripts/, and reusable examples/templates in assets/.
Update a skill when its selection conditions, required steps, validation commands, or referenced policy change. Check all links and ensure the skill does not duplicate or contradict AGENTS.md or an owned design record. Record significant library changes in the Common topic tracker and index.