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

---
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.