Notre avis

Guide la création d'une Agent Skill structurée dans .claude/skills/, avec un SKILL.md au format imposé et des fichiers de référence chargés à la demande.

Points forts

Fournit un squelette complet et copiable : frontmatter YAML, sections obligatoires, arborescence de dossiers
Explique le principe de divulgation progressive en limitant SKILL.md à 500 lignes et en déportant les détails dans references/
Rappelle l'importance d'une description contenant les mots-clés de déclenchement pour que l'agent active la skill au bon moment
Renvoie à des skills existantes du dépôt (linear-ticket, write-test) comme modèles concrets

Limites

Suppose que le dépôt utilise déjà la convention .claude/skills/ et ne couvre pas d'autres mécanismes d'extension
Ne fournit pas de méthode de validation ou de test automatisé du déclenchement de la skill créée
L'étape d'exploration du codebase est décrite en une ligne, sans heuristique sur quoi chercher

Quand l'utiliser

À utiliser lorsqu'on veut ajouter une nouvelle capacité réutilisable, avec documentation de référence, pour les agents qui travaillent sur ce dépôt.

Quand l'éviter

À éviter pour une simple commande slash ou un prompt ponctuel, qui ne justifie pas la structure d'une skill complète.

Exemples

New deploy-check skill

Create a new Agent Skill called deploy-check that verifies our staging deployment is healthy before we promote to production.

Skill with reference files

Write a skill for reviewing database migrations in this repo, and add reference files covering our schema naming conventions and rollback rules.

Quick invocation

/write-skill linear-ticket

description: Create a new Agent Skill for this codebase argument-hint: [skill-name] [description]

Write an Agent Skill

You are creating an Agent Skill - a structured capability that coding agents can discover and use to perform tasks more accurately and efficiently.

What is an Agent Skill?

A skill is a folder of instructions, scripts, and resources that agents load on-demand. Unlike slash commands (single prompts), skills provide comprehensive, structured guidance for complex workflows.

Key insight: Skills are consumed by coding agents, not humans. Structure them so an agent can:

Quickly understand what the skill does (from description)
Load core instructions (from SKILL.md)
Access detailed references only when needed (from references/)

Directory Structure

Create in .claude/skills/<skill-name>/:

skill-name/
├── SKILL.md              # Required - core instructions
└── references/           # Optional - detailed docs loaded on-demand
    ├── REFERENCE.md
    └── ...

SKILL.md Format

Frontmatter (Required)

---
name: skill-name          # Lowercase, hyphens only, matches folder name
description: What this skill does and WHEN to use it. Include trigger keywords.
license: Proprietary      # Optional
metadata:                 # Optional
  author: autumn
  version: "1.0"
---

Critical: The description must tell the agent WHEN to activate this skill. Include specific keywords and scenarios.

Body Structure

Write for an agent, not a human. Be direct and actionable.

## What I do

[One sentence - what capability this provides]

## Before Starting

[Prerequisites, files to read first, setup requirements]

## Critical Rules

**DO:**
- [Concrete actions]

**DON'T:**
- [Common mistakes to avoid]

## Process / Template

[Step-by-step instructions or code templates]

## References

Load these on-demand for detailed information:

- [references/TOPIC.md](references/TOPIC.md) - Brief description

Design Principles

Progressive disclosure: Keep SKILL.md under 500 lines. Move details to references/.
Agent-first writing: No fluff. Every line should help the agent do the task correctly.
Include templates: Agents work better with concrete examples and copy-paste templates.
Trigger keywords: The description should include words users might say that should activate this skill.
Reference files: Keep them focused and small. Agents load them on-demand, so smaller = less context used.

Examples in This Codebase

Study these existing skills:

.claude/skills/linear-ticket/SKILL.md - Simple skill, single file, uses MCP tools
.claude/skills/write-test/SKILL.md - Complex skill with multiple reference files

Your Task

Ask what the skill should do if $ARGUMENTS is empty or unclear
Search the codebase for patterns, existing implementations, and conventions
Create the skill directory and SKILL.md
Add references if the skill needs detailed documentation (keep SKILL.md focused)
Verify the skill follows the patterns in existing skills

Naming Convention

Folder: .claude/skills/<skill-name>/
Name must be lowercase with hyphens only
Name must match the folder name
Keep names short but descriptive: write-test, linear-ticket, code-review

Créer une Agent Skill

Recommandé pour