| name | writing-skills |
| description | Use when creating, revising, validating, or deploying a reusable agent skill. |
Writing Skills
Build a skill only when reusable guidance adds value beyond project instructions,
automation, or a one-off note. A skill can be a minimal meaningful artifact:
frontmatter plus a focused SKILL.md, with extra files only when they improve use.
Anatomy and discovery
Use a directory named for the skill. Its SKILL.md frontmatter needs a stable
name and a concise description that names concrete triggers, symptoms, and
boundaries. The body explains the decision, semantic examples, and the smallest
safe workflow. Prefer progressive disclosure: keep first-use guidance short and
move heavy reference, scripts, or assets into linked files.
Map instructions to the active platform's tools and deployment surface rather
than assuming a namespace or runtime. Validate markdown syntax and links, then
resolve how the target harness discovers and loads the skill.
Evaluation and publication
Choose validation proportional to novelty and risk. A reference skill may need
static checks and semantic examples; a behavior/process skill may need a real
scenario and a counterfactual or no-guidance control when it could change the
conclusion. Preserve useful drafts and iterate from evidence rather than deleting
work as ritual.
Commit, publish, push, PR, and release behavior follow current repository policy
and explicit authority. Do not use announcements, todo compliance, authority,
scarcity, or commitment manipulation as substitutes for a clear skill.