---
name: skill-authoring
description: "How to create or restructure a skill so the .ai/skills/ system stays consistent, operational, and trustworthy. A skill is a short, repeatable playbook — not an essay."
generated: true
source: .ai/skills/skill-authoring.md
---

<!--
This file is generated by tools/skills.
Do not edit this file directly.
Edit .ai/skills/skill-authoring.md and run `make generate-ai`.
-->

# Skill: Skill Authoring

## Purpose

Define how to create new skill files so the `.ai/skills/` system stays
consistent, operational, and trustworthy. A skill is a short, repeatable
playbook — not an essay.

## When to Use This Skill

- Creating a new skill file in `.ai/skills/`.
- Substantially restructuring an existing skill.
- Reviewing a proposed skill for quality and consistency.

## Files to Read First

- `AGENTS.md` (skills system + architecture rules a skill must not contradict).
- `.ai/README.md` (the index a new skill must be added to).
- An existing high-quality skill as a model (e.g.
  `.ai/skills/code-review.md`).
- Any `docs/`/ADR the new skill will reference.

## Core Principles

- **Operational, not academic.** A skill tells an agent what to do, step by
  step. No long prose.
- **Task-oriented and repeatable.** Focus on behavior an agent will repeat.
- **Consistent structure.** Every skill uses the standard section set (below).
- **Must include** when to use it, files to read first, rules, process,
  checklist, and common mistakes.
- **Never contradicts** `AGENTS.md`, the docs, or ADRs. If it would, you need an
  ADR/doc change first, not a skill that diverges.
- **References, not duplicates.** Link to the authoritative doc/ADR rather than
  copying its content (which will drift). This is also why skills live only in
  `.ai/` — never copy them into tool-specific folders.
- **Short enough to be used.** If it's too long to read before a task, trim it.
- **Includes validation commands** (e.g. `make check`).

## Process

1. **Confirm the gap.** Ensure no existing skill already covers the area; prefer
   improving one over adding a near-duplicate.
2. **Copy the template** below into `.ai/skills/<name>.md`.
3. **Fill every section** with concrete, project-specific instructions (mention
   real layers, files, and commands — not generic advice).
4. **Cross-check** against `AGENTS.md`/ADRs for contradictions.
5. **Add it to `.ai/README.md`** index and, if it maps to a task type, to the
   `AGENTS.md` skills mapping.
6. **Validate** formatting with `make check` (Markdown only → still run it).

## Template for a new skill file

```markdown
---
name: <skill-name>
description: <one-sentence summary of when and why to use this skill>
---

# Skill: <Skill Name>

## Purpose
<one short paragraph: what this skill is for>

## When to Use This Skill
- <situation 1>
- <situation 2>

## Files to Read First
- <file 1>
- <file 2>

## Core Principles
- <non-negotiable principle 1>
- <non-negotiable principle 2>

## Process
1. <step 1>
2. <step 2>

## Checklist Before Finishing
- [ ] <check 1>
- [ ] `make check` passes.

## Common Mistakes to Avoid
- <mistake 1>

## Expected Final Report
<what the agent should report after applying this skill>
```

## Checklist Before Finishing

- [ ] File named `.ai/skills/<name>.md` and uses the standard sections.
- [ ] Content is operational, concrete, and project-specific.
- [ ] No contradiction with `AGENTS.md`, docs, or ADRs.
- [ ] References authoritative docs instead of duplicating them.
- [ ] Includes validation commands.
- [ ] Added to `.ai/README.md` (and `AGENTS.md` mapping if applicable).
- [ ] `make check` passes.

## Common Mistakes to Avoid

- Writing a long essay instead of a playbook.
- Vague, generic advice that isn't tied to this project.
- Duplicating doc/ADR content that will drift out of sync.
- Forgetting to register the skill in the README/mapping.
- Contradicting an existing rule without first updating the ADR/doc.

## Expected Final Report

State: the new skill's name and path; the gap it fills; which docs/ADRs it
references; where it was registered (README/AGENTS mapping); and confirmation
that it matches the standard structure and contradicts nothing.