22 lines
2.2 KiB
Markdown
22 lines
2.2 KiB
Markdown
# 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.
|