Plugin de base pour Claude Code avec skills essentiels pour l'amélioration et la documentation
- GitHub stars
- 9
Install
/plugin install claude@atournayre-claude-plugin-marketplaceRun it inside Claude Code after adding the marketplace with /plugin marketplace add atournayre/claude-marketplace.
Contents
Discovered from sourceSkills 7
Générateur d'Alias de Slash Commands
Instructions à Exécuter
IMPORTANT : Exécute ce workflow étape par étape :
Créer un alias de slash command qui délègue l'exécution à une autre commande existante via l'outil Skill.
Purpose
Permettre de créer des raccourcis (alias) vers des commandes existantes pour simplifier l'utilisation et éviter la duplication de code.
Variables
- ALIAS: Nom de l'alias (format slash-command, ex:
/mon-alias) - TARGET_COMMAND: Commande cible à exécuter (format slash-command, ex:
/git:status)
Relevant Files
commands/- Répertoire des commandes existantesREADME.md- Documentation du projet pour mise à jour
Workflow
Étape 1: Validation des Arguments
- Vérifier que 2 arguments ont été fournis (alias et commande cible)
- Valider le format de l'alias (doit commencer par
/, format kebab-case) - Valider le format de la commande cible (doit commencer par
/) - Vérifier que l'alias n'existe pas déjà (chercher dans
commands/) - Vérifier que la commande cible existe
Étape 2: Création du Fichier d'Alias
- Créer le répertoire
commands/alias/s'il n'existe pas - Générer le fichier avec la structure suivante :
--- allowed-tools: - Skill description: Alias vers [TARGET_COMMAND] argument-hint: [arguments de la commande cible] model: haiku --- # [ALIAS] Alias vers `[TARGET_COMMAND]`. ## Usage Cette commande délègue directement à `[TARGET_COMMAND]`. ## Workflow - Exécuter la commande cible via Skill
Étape 3: Exécution de la Commande Cible
- Utiliser l'outil Skill pour exécuter TARGET_COMMAND
- Transmettre tous les arguments supplémentaires à la commande cible
Étape 4: Mise à Jour de la Documentation
- Ajouter l'alias dans la section "Commandes personnalisées" du README.md
- Inclure :
- Nom de l'alias
- Description
- Commande cible
- Usage
Étape 5: Rapport Final
- Confirmer la création de l'alias
- Afficher le chemin du fichier créé
- Rappeler la commande cible
- Calculer et afficher la durée totale
Report
✅ Alias créé avec succès
📁 Fichier : commands/alias/[nom-alias].md
🎯 Cible : [TARGET_COMMAND]
📝 Usage : /[alias] [arguments]
Examples
Créer un alias pour git:status
/alias:add status /git:status
Créer un alias pour doc:update
/alias:add doc /doc:update
Best Practices
- Noms d'alias courts et mémorisables
- Éviter les conflits avec les commandes existantes
- Documenter clairement la commande cible
- Utiliser Haiku pour les alias (simple délégation)
- Transmettre tous les arguments à la commande cible
Challenge - Auto-évaluation des réponses Claude
Instructions à Exécuter
IMPORTANT : Exécute ce workflow étape par étape :
Analyse critique de ma dernière réponse fournie et proposition d'une version améliorée.
Purpose
Permettre à Claude d'évaluer objectivement la qualité de sa dernière réponse et d'identifier les axes d'amélioration concrets.
Variables
- LAST_RESPONSE: Ma dernière réponse dans la conversation
- ORIGINAL_QUESTION: La question ou demande initiale de l'utilisateur
- EVALUATION_CRITERIA: Critères d'évaluation (clarté, pertinence, complétude, précision, format)
Relevant Files
- Historique de conversation (contexte automatique)
Workflow
1. Identification du contexte
- Identifie la dernière question/demande de l'utilisateur
- Récupère ma dernière réponse complète
- Note les objectifs explicites et implicites de la demande
2. Évaluation structurée
Évalue ma réponse selon ces critères (note /10 pour chaque) :
Pertinence (/10)
- La réponse répond-elle directement à la question ?
- Y a-t-il des éléments hors sujet ou manquants ?
Clarté (/10)
- Le message est-il facile à comprendre ?
- Le format est-il adapté (listes vs paragraphes) ?
- Les termes techniques sont-ils expliqués si nécessaire ?
Complétude (/10)
- Tous les aspects de la demande sont-ils couverts ?
- Y a-t-il des informations importantes omises ?
Précision (/10)
- Les informations sont-elles exactes ?
- Y a-t-il des approximations ou suppositions ?
Format et style (/10)
- Le ton est-il approprié (casual, pas trop formel) ?
- Le format respecte-t-il les préférences (listes à puces) ?
- Y a-t-il des phrases trop enthousiastes à éviter ?
3. Calcul de la note globale
- Note finale = moyenne des 5 critères
- Identification du critère le plus faible
- Identification des points forts
4. Proposition d'amélioration
- Liste concrète de ce qui pourrait être amélioré
- Proposition d'une version améliorée si la note < 8/10
- Focus sur les critères les plus faibles
Report
Structure du rapport d'évaluation
📊 Évaluation de ma dernière réponse
Question initiale : [Rappel de la question]
Ma réponse : [Résumé bref de ce que j'ai fourni]
Scores détaillés :
- 🎯 Pertinence : X/10 - [justification courte]
- 💡 Clarté : X/10 - [justification courte]
- ✅ Complétude : X/10 - [justification courte]
- 🔍 Précision : X/10 - [justification courte]
- 📝 Format/Style : X/10 - [justification courte]
Note globale : X/10
Points forts :
- [Point fort 1]
- [Point fort 2]
Axes d'amélioration :
- [Amélioration 1]
- [Amélioration 2]
- [Amélioration 3]
Version améliorée (si note < 8/10) : [Nouvelle version de la réponse intégrant les améliorations]
Best Practices
- Être honnête et autocritique sans tomber dans l'auto-flagellation
- Identifier des améliorations concrètes et actionnables
- Ne pas hésiter à reconnaître quand la réponse initiale était déjà bonne
- Expliquer le raisonnement derrière chaque note
- Proposer une version améliorée uniquement si pertinent
- Garder le rapport concis et structuré en listes à puces
You must use the Skill tool to invoke the "doc-loader" skill with "claude" as argument.
Interrogation de la Documentation Claude Code
Instructions à Exécuter
IMPORTANT : Exécute ce workflow étape par étape :
Répondre à une question technique sur Claude Code en utilisant la documentation locale présente dans docs/claude/.
Purpose
Fournir des réponses précises et contextualisées aux questions Claude Code en s'appuyant sur la documentation officielle stockée localement, sans nécessiter d'accès web.
Variables
- QUESTION: La question technique posée par l'utilisateur
- DOCS_PATH:
docs/claude/- Chemin vers la documentation locale - SEARCH_KEYWORDS: Mots-clés extraits de la question pour la recherche
Relevant Files
docs/claude/- Documentation Claude Code localedocs/claude/README.md- Index de la documentation chargée
Workflow
Étape 1: Vérification de la documentation locale
- Vérifier l'existence de
docs/claude/ - Si le répertoire n'existe pas ou est vide :
- Informer l'utilisateur
- Suggérer d'exécuter
/claude:doc:loadpour charger la documentation - Arrêter l'exécution avec message explicite
- Si la documentation existe :
- Lire
docs/claude/README.mdpour connaître le contenu disponible - Continuer vers l'étape 2
- Lire
Étape 2: Analyse de la question
- Extraire les mots-clés principaux de QUESTION
- Identifier le contexte technique (composant, feature, concept)
- Exemples de mots-clés :
- "slash command" → chercher dans commands.md, custom-commands.md
- "agent" → chercher dans agents.md, subagents.md
- "hook" → chercher dans hooks.md, lifecycle.md
- "tool" → chercher dans tools.md, permissions.md
Étape 3: Recherche dans la documentation
- Utiliser Grep pour rechercher les mots-clés dans
docs/claude/ - Paramètres de recherche :
- Case insensitive (
-i) - Afficher le contexte (3 lignes avant/après avec
-C 3) - Limiter les résultats pertinents
- Case insensitive (
- Lire les fichiers markdown pertinents identifiés
- Si aucun résultat :
- Élargir la recherche avec des termes associés
- Suggérer des termes de recherche alternatifs
Étape 4: Analyse et synthèse
- Extraire les sections pertinentes de la documentation
- Organiser les informations par ordre de pertinence
- Identifier :
- Concept principal
- Exemples de code
- Bonnes pratiques
- Warnings et notes importantes
- Liens vers documentation connexe
Étape 5: Construction de la réponse
- Réponse structurée en format bullet points
- Inclure :
- Explication concise du concept
- Exemples de code si disponibles
- Références aux fichiers de documentation sources
- Liens internes vers sections connexes
- Format markdown enrichi avec :
- Blocs de code Markdown/Python/Shell selon contexte
- Sections info/warning si pertinent
- Liste hiérarchique pour les étapes
Étape 6: Rapport final avec timing
- Présenter la réponse formatée
- Calculer et afficher la durée totale
- Afficher le timestamp de fin
Report Format
## 📚 Réponse : [Sujet principal]
### Concept
- Explication principale
- Points clés
### Exemple de Code
[Bloc de code si disponible]
### Documentation de Référence
- 📄 `docs/claude/[fichier].md` - [Section]
- 📄 Autres fichiers pertinents
### Voir Aussi
- Concepts connexes
- Autres commandes utiles
Error Handling
- Documentation manquante : Message clair + suggestion
/claude:doc:load - Aucun résultat trouvé : Suggérer termes alternatifs ou reformulation
- Question trop vague : Demander précisions avec exemples
- Fichiers corrompus : Signaler et suggérer rechargement
Examples
Exemple 1 - Question simple
/claude:doc:question "Comment créer une slash command ?"
Résultat attendu :
- Recherche dans commands.md, custom-commands.md
- Format de fichier de commande
- Exemples de frontmatter YAML
- Références aux fichiers sources
Exemple 2 - Question sur composant
/claude:doc:question "Comment utiliser les hooks ?"
Résultat attendu :
- Recherche hooks.md, lifecycle.md
- Types de hooks disponibles
- Exemples Python
- Cas d'usage
Exemple 3 - Question avancée
/claude:doc:question "Comment créer un agent personnalisé ?"
Résultat attendu :
- Recherche agents.md, custom-agents.md
- Configuration d'agent
- Cas d'usage appropriés
- Exemples complets
Best Practices
- Toujours vérifier la présence de la documentation avant recherche
- Privilégier la précision sur l'exhaustivité
- Citer les sources (fichiers markdown consultés)
- Fournir des exemples de code concrets
- Suggérer des commandes connexes si pertinent
- Garder les réponses concises mais complètes
- Afficher le timing au début et à la fin
- Calculer précisément la durée d'exécution
Notes
- Cette commande fonctionne 100% offline une fois la documentation chargée
- La documentation doit être rafraîchie périodiquement avec
/claude:doc:load - Supporte toutes les versions de Claude Code présentes dans
docs/claude/ - Peut être étendue pour supporter d'autres frameworks avec le même pattern
Subagents enable delegation of complex tasks to specialized agents that operate autonomously without user interaction, returning their final output to the main conversation.
<quick_start>
- Run
/agentscommand - Select "Create New Agent"
- Choose project-level (
.claude/agents/) or user-level (~/.claude/agents/) - Define the subagent:
- name: lowercase-with-hyphens
- description: When should this subagent be used?
- tools: Optional comma-separated list (inherits all if omitted)
- model: Optional (
sonnet,opus,haiku, orinherit)
- Write the system prompt (the subagent's instructions)
<focus_areas>
- Code quality and maintainability
- Security vulnerabilities
- Performance issues
- Best practices adherence </focus_areas>
<output_format> Provide specific, actionable feedback with file:line references. </output_format>
</example>
</quick_start>
<file_structure>
| Type | Location | Scope | Priority |
|------|----------|-------|----------|
| **Project** | `.claude/agents/` | Current project only | Highest |
| **User** | `~/.claude/agents/` | All projects | Lower |
| **Plugin** | Plugin's `agents/` dir | All projects | Lowest |
Project-level subagents override user-level when names conflict.
</file_structure>
<configuration>
<field name="name">
- Lowercase letters and hyphens only
- Must be unique
</field>
<field name="description">
- Natural language description of purpose
- Include when Claude should invoke this subagent
- Used for automatic subagent selection
</field>
<field name="tools">
- Comma-separated list: `Read, Write, Edit, Bash, Grep`
- If omitted: inherits all tools from main thread
- Use `/agents` interface to see all available tools
</field>
<field name="model">
- `sonnet`, `opus`, `haiku`, or `inherit`
- `inherit`: uses same model as main conversation
- If omitted: defaults to configured subagent model (usually sonnet)
</field>
</configuration>
<execution_model>
<critical_constraint>
**Subagents are black boxes that cannot interact with users.**
Subagents run in isolated contexts and return their final output to the main conversation. They:
- ✅ Can use tools like Read, Write, Edit, Bash, Grep, Glob
- ✅ Can access MCP servers and other non-interactive tools
- ❌ **Cannot use AskUserQuestion** or any tool requiring user interaction
- ❌ **Cannot present options or wait for user input**
- ❌ **User never sees subagent's intermediate steps**
The main conversation sees only the subagent's final report/output.
</critical_constraint>
<workflow_design>
**Designing workflows with subagents:**
Use **main chat** for:
- Gathering requirements from user (AskUserQuestion)
- Presenting options or decisions to user
- Any task requiring user confirmation/input
- Work where user needs visibility into progress
Use **subagents** for:
- Research tasks (API documentation lookup, code analysis)
- Code generation based on pre-defined requirements
- Analysis and reporting (security review, test coverage)
- Context-heavy operations that don't need user interaction
**Example workflow pattern:**
Main Chat: Ask user for requirements (AskUserQuestion) ↓ Subagent: Research API and create documentation (no user interaction) ↓ Main Chat: Review research with user, confirm approach ↓ Subagent: Generate code based on confirmed plan ↓ Main Chat: Present results, handle testing/deployment
</workflow_design>
</execution_model>
<system_prompt_guidelines>
<principle name="be_specific">
Clearly define the subagent's role, capabilities, and constraints.
</principle>
<principle name="use_pure_xml_structure">
Structure the system prompt with pure XML tags. Remove ALL markdown headings from the body.
```markdown
---
name: security-reviewer
description: Reviews code for security vulnerabilities
tools: Read, Grep, Glob, Bash
model: sonnet
---
<role>
You are a senior code reviewer specializing in security.
</role>
<focus_areas>
- SQL injection vulnerabilities
- XSS attack vectors
- Authentication/authorization issues
- Sensitive data exposure
</focus_areas>
<workflow>
1. Read the modified files
2. Identify security risks
3. Provide specific remediation steps
4. Rate severity (Critical/High/Medium/Low)
</workflow>
Tailor instructions to the specific task domain. Don't create generic "helper" subagents.
❌ Bad: "You are a helpful assistant that helps with code" ✅ Good: "You are a React component refactoring specialist. Analyze components for hooks best practices, performance anti-patterns, and accessibility issues." </system_prompt_guidelines>
<subagent_xml_structure> Subagent.md files are system prompts consumed only by Claude. Like skills and slash commands, they should use pure XML structure for optimal parsing and token efficiency.
<recommended_tags> Common tags for subagent structure:
<role>- Who the subagent is and what it does<constraints>- Hard rules (NEVER/MUST/ALWAYS)<focus_areas>- What to prioritize<workflow>- Step-by-step process<output_format>- How to structure deliverables<success_criteria>- Completion criteria<validation>- How to verify work </recommended_tags>
<intelligence_rules> Simple subagents (single focused task):
- Use role + constraints + workflow minimum
- Example: code-reviewer, test-runner
Medium subagents (multi-step process):
- Add workflow steps, output_format, success_criteria
- Example: api-researcher, documentation-generator
Complex subagents (research + generation + validation):
- Add all tags as appropriate including validation, examples
- Example: mcp-api-researcher, comprehensive-auditor </intelligence_rules>
<critical_rule> Remove ALL markdown headings (##, ###) from subagent body. Use semantic XML tags instead.
Keep markdown formatting WITHIN content (bold, italic, lists, code blocks, links).
For XML structure principles and token efficiency details, see @skills/create-agent-skills/references/use-xml-tags.md - the same principles apply to subagents. </critical_rule> </subagent_xml_structure>
Claude automatically selects subagents based on the `description` field when it matches the current task. You can explicitly invoke a subagent:> Use the code-reviewer subagent to check my recent changes
> Have the test-writer subagent create tests for the new API endpoints
<background_execution>
Subagents can run in the background using the run_in_background parameter, allowing parallel execution while the main conversation continues.
<how_it_works>
Starting a background subagent:
The Task tool accepts run_in_background: true to launch agents asynchronously:
Task tool call:
- description: "Analyze security vulnerabilities"
- prompt: "Review all authentication code for security issues..."
- subagent_type: "security-reviewer"
- run_in_background: true
The agent starts immediately and returns an agent_id for tracking.
</how_it_works>
<retrieving_results>
Getting results with TaskOutput:
Use the TaskOutput tool to retrieve results from background agents:
TaskOutput tool call:
- task_id: "agent-12345" # The agent_id from the Task call
- block: true # Wait for completion (default)
- timeout: 30000 # Max wait time in ms
Parameters:
| Parameter | Default | Description |
|---|---|---|
task_id | Required | The agent ID returned from Task tool |
block | true | Wait for completion or check current status |
timeout | 30000 | Max wait time in milliseconds (up to 600000) |
Non-blocking check:
Set block: false to check status without waiting:
TaskOutput tool call:
- task_id: "agent-12345"
- block: false
Returns current status: running, completed, or the final result. </retrieving_results>
<parallel_agents> Launching multiple agents in parallel:
To maximize performance, launch multiple independent agents simultaneously:
Single message with multiple Task tool calls:
Task 1:
- description: "Review code quality"
- prompt: "Check code quality..."
- subagent_type: "code-reviewer"
- run_in_background: true
Task 2:
- description: "Run security scan"
- prompt: "Scan for vulnerabilities..."
- subagent_type: "security-scanner"
- run_in_background: true
Task 3:
- description: "Check test coverage"
- prompt: "Analyze test coverage..."
- subagent_type: "test-analyzer"
- run_in_background: true
Then retrieve all results:
TaskOutput calls for each agent_id
</parallel_agents>
<when_to_use_background> Use background agents for:
- Long-running analysis (security review, comprehensive code analysis)
- Multiple independent tasks that can run in parallel
- Tasks where you want to continue working while waiting
- Research tasks that may take significant time
Don't use background for:
- Quick operations (< 10 seconds)
- Tasks that depend on each other sequentially
- Tasks where immediate results are needed for next step
- Simple single-file operations
Pattern: Parallel Analysis Pipeline
1. Launch multiple analysis agents in background
2. Continue with other work or wait
3. Collect all results
4. Synthesize findings in main conversation
</when_to_use_background>
<resuming_agents>
Resuming agents:
Agents can be resumed using the resume parameter with their agent ID:
Task tool call:
- description: "Continue security review"
- prompt: "Please continue with the remaining files..."
- subagent_type: "security-reviewer"
- resume: "agent-12345" # Previous agent ID
The agent continues with its full previous context preserved. </resuming_agents> </background_execution>
Run `/agents` for an interactive interface to: - View all available subagents - Create new subagents - Edit existing subagents - Delete custom subagents<manual_editing> You can also edit subagent files directly:
- Project:
.claude/agents/subagent-name.md - User:
~/.claude/agents/subagent-name.md</manual_editing>
Subagent usage and configuration: references/subagents.md
- File format and configuration
- Model selection (Sonnet 4.5 + Haiku 4.5 orchestration)
- Tool security and least privilege
- Prompt caching optimization
- Background execution (run_in_background, TaskOutput, parallel agents)
- Complete examples
Writing effective prompts: references/writing-subagent-prompts.md
- Core principles and XML structure
- Description field optimization for routing
- Extended thinking for complex reasoning
- Security constraints and strong modal verbs
- Success criteria definition
Advanced topics:
Evaluation and testing: references/evaluation-and-testing.md
- Evaluation metrics (task completion, tool correctness, robustness)
- Testing strategies (offline, simulation, online monitoring)
- Evaluation-driven development
- G-Eval for custom criteria
Error handling and recovery: references/error-handling-and-recovery.md
- Common failure modes and causes
- Recovery strategies (graceful degradation, retry, circuit breakers)
- Structured communication and observability
- Anti-patterns to avoid
Context management: references/context-management.md
- Memory architecture (STM, LTM, working memory)
- Context strategies (summarization, sliding window, scratchpads)
- Managing long-running tasks
- Prompt caching interaction
Orchestration patterns: references/orchestration-patterns.md
- Sequential, parallel, hierarchical, coordinator patterns
- Sonnet + Haiku orchestration for cost/performance
- Multi-agent coordination
- Pattern selection guidance
Debugging and troubleshooting: references/debugging-agents.md
- Logging, tracing, and correlation IDs
- Common failure types (hallucinations, format errors, tool misuse)
- Diagnostic procedures
- Continuous monitoring
<success_criteria> A well-configured subagent has:
- Valid YAML frontmatter (name matches file, description includes triggers)
- Clear role definition in system prompt
- Appropriate tool restrictions (least privilege)
- XML-structured system prompt with role, approach, and constraints
- Description field optimized for automatic routing
- Successfully tested on representative tasks
- Model selection appropriate for task complexity (Sonnet for reasoning, Haiku for simple tasks) </success_criteria>
Memory files are automatically loaded at session startup, consuming tokens from your 200k context window. Every instruction competes with Claude Code's ~50 built-in instructions, leaving ~100-150 effective instruction slots for your customizations.
Two approaches available:
- CLAUDE.md - Single file, simpler, best for small projects
- .claude/rules/ - Modular files with optional path-scoping, best for large projects
<quick_start>
<bootstrap_new_project>
Run /init in Claude Code to auto-generate a CLAUDE.md with project structure.
Or create manually at project root:
# Project Name
## Tech Stack
- [Primary language/framework]
- [Key libraries]
## Commands
- `npm run dev` - Start development
- `npm test` - Run tests
- `npm run build` - Build for production
## Code Conventions
- [2-3 critical conventions]
## Important Context
- [1-2 architectural decisions worth knowing]
</bootstrap_new_project>
<quick_add_memory>
Press # during a Claude Code session to quickly add new memory items without editing the file directly.
</quick_add_memory>
<edit_memory>
Use /memory command to open CLAUDE.md in your system editor.
</edit_memory>
</quick_start>
<file_hierarchy> Claude Code loads CLAUDE.md files in a specific order. Higher priority files are loaded first and take precedence.
<loading_order>
| Priority | Location | Purpose | Scope |
|---|---|---|---|
| 1 (Highest) | /Library/Application Support/ClaudeCode/CLAUDE.md (macOS) | Enterprise policy (managed by IT) | All org users |
| 2 | ./CLAUDE.md or ./.claude/CLAUDE.md | Project memory (git-tracked) | Team via git |
| 2 | ./.claude/rules/*.md | Modular rules (git-tracked) | Team via git |
| 3 | ~/.claude/CLAUDE.md | User preferences (global) | All your projects |
| 3 | ~/.claude/rules/*.md | Personal modular rules (global) | All your projects |
| 4 (Lowest) | ./CLAUDE.local.md | Personal project prefs (auto-gitignored) | Just you |
| </loading_order> |
<recursive_loading> Claude recurses UP from current directory to root, loading all CLAUDE.md files found.
Running Claude in foo/bar/ loads:
foo/bar/CLAUDE.mdfoo/CLAUDE.md- Root-level files
Claude also discovers CLAUDE.md in SUBTREES when reading files in those directories. </recursive_loading>
<monorepo_strategy> For monorepos, use layered approach:
root/
├── CLAUDE.md # Universal: tech stack, git workflow
├── apps/
│ ├── web/CLAUDE.md # Frontend-specific patterns
│ └── api/CLAUDE.md # Backend-specific patterns
└── packages/
└── shared/CLAUDE.md # Shared library conventions
Root file defines WHEN to use patterns; subtree files define HOW. </monorepo_strategy> </file_hierarchy>
<rules_directory>
The .claude/rules/ directory provides a modular alternative to monolithic CLAUDE.md files. Instead of one large file, you organize instructions into multiple focused markdown files.
<when_to_use_rules>
Use .claude/rules/ when:
- Project has many distinct concerns (testing, security, API, frontend)
- Different rules apply to different file types
- Team members maintain different areas
- You want to update one concern without touching others
Use CLAUDE.md when:
- Project is small/simple
- All rules are universal
- You prefer a single source of truth </when_to_use_rules>
<rules_structure>
.claude/rules/
├── code-style.md # Formatting and conventions
├── testing.md # Test requirements
├── security.md # Security checklist
├── frontend/
│ ├── react.md # React-specific patterns
│ └── styles.md # CSS conventions
└── backend/
├── api.md # API development rules
└── database.md # Database conventions
Key points:
- All
.mdfiles are discovered recursively - No imports or configuration needed
- Same priority as CLAUDE.md
- Supports symlinks for sharing rules across projects </rules_structure>
<path_scoped_rules> Rules can be scoped to specific files using YAML frontmatter:
---
paths:
- "src/api/**/*.ts"
---
# API Development Rules
- All API endpoints must include input validation
- Use the standard error response format
Path patterns supported:
| Pattern | Matches |
|---|---|
**/*.ts | All TypeScript files in any directory |
src/**/* | All files under src/ directory |
src/components/*.tsx | React components in specific directory |
src/**/*.{ts,tsx} | TypeScript and TSX files (brace expansion) |
{src,lib}/**/*.ts | Files in multiple directories |
Syntax note: The paths field must be a YAML array (list format with - prefix and quoted strings).
Rules without paths frontmatter load unconditionally for all files.
</path_scoped_rules>
<user_level_rules> Create personal rules that apply to all your projects:
~/.claude/rules/
├── preferences.md # Your coding preferences
├── workflows.md # Your preferred workflows
└── git.md # Your git conventions
User-level rules load before project rules, giving project rules higher priority for overrides. </user_level_rules>
<symlinks_support> Share common rules across multiple projects using symlinks:
# Symlink a shared rules directory
ln -s ~/shared-claude-rules .claude/rules/shared
# Symlink individual rule files
ln -s ~/company-standards/security.md .claude/rules/security.md
Circular symlinks are detected and handled gracefully. </symlinks_support> </rules_directory>
<content_framework> Structure your CLAUDE.md using the WHAT-WHY-HOW framework:
WHAT - Project Context: Tech stack, directory structure, architecture WHY - Purpose: Architectural decisions, why patterns exist HOW - Workflow: Commands, testing, git workflow, verification steps
## Tech Stack
- Next.js 15 with App Router
- PostgreSQL via Prisma ORM
## Architecture Decisions
- Server Components for data fetching
- All forms use TanStack Form
## Commands
- `pnpm dev` - Start dev server
- `pnpm test:ci` - Run tests
- `pnpm build` - Production build
## Git Workflow
- Branch: `feature/name` or `fix/name`
- Run tests before committing
See references/section-templates.md for complete templates. </content_framework>
<emphasis_techniques> Claude follows emphasized instructions more reliably. Use these techniques strategically for critical rules.
<keyword_hierarchy> Use emphasis keywords in order of severity:
| Keyword | Use For | Example |
|---|---|---|
| CRITICAL | Non-negotiable rules | **CRITICAL**: Never commit secrets |
| NEVER | Absolute prohibitions | NEVER: Push directly to main |
| ALWAYS | Mandatory behaviors | ALWAYS: Run tests before pushing |
| IMPORTANT | Significant guidance | IMPORTANT: Keep components under 300 lines |
| YOU MUST | Explicit requirements | YOU MUST: Use TanStack Form for forms |
</keyword_hierarchy>
<formatting_patterns> Bold + CRITICAL keyword:
**CRITICAL**: Always run tests before pushing code
Capitalized emphasis:
IMPORTANT: Do not commit environment variables
YOU MUST: Follow the git workflow outlined below
NEVER: Include API keys in code
ALWAYS: Use TypeScript strict mode
Strikethrough for forbidden options:
- `pnpm test:ci` - Run tests (use this)
- ~~`pnpm test`~~ - NEVER use (interactive mode)
Visual markers (use sparingly):
⚠️ WARNING: This affects production data
🔒 SECURITY: Never commit secrets to git
</formatting_patterns>
<placement_strategy> Order matters. Claude pays more attention to:
- First items in each section (put critical rules first)
- Repeated items across sections (repeat critical rules in context)
- Emphasized items with CRITICAL/NEVER/ALWAYS keywords
Structure your file with critical rules first:
## Code Conventions
### Critical Rules
- **NEVER** commit .env files
- **ALWAYS** run tests before pushing
- **CRITICAL**: Use TanStack Form for ALL forms
### General Guidelines
- Prefer Server Components
- Keep components under 300 lines
</placement_strategy>
<repetition_for_emphasis> For extremely important rules, repeat in multiple relevant contexts:
## Forms
**CRITICAL**: Use TanStack Form for ALL forms
## Before Editing
- **CRITICAL**: Use TanStack Form for forms
## Code Review Checklist
- [ ] Forms use TanStack Form (**CRITICAL**)
</repetition_for_emphasis> </emphasis_techniques>
<writing_effective_instructions> <golden_rule> Show your CLAUDE.md to someone with minimal project context. If they're confused, Claude will be too. </golden_rule>
<be_specific> Vague instructions cause inconsistent behavior:
❌ VAGUE:
- Format code properly
- Write good tests
- Follow best practices
✅ SPECIFIC:
- Run `pnpm lint` before committing (Prettier configured)
- Write tests in `__tests__/` using Vitest
- Use TanStack Form for all forms (see `src/features/form/`)
</be_specific>
<show_dont_tell> When format matters, show examples:
❌ TELLING:
Use conventional commits with type and description.
✅ SHOWING:
## Commit Format
feat(auth): implement JWT authentication
Add login endpoint and token validation
Types: feat, fix, refactor, docs, test, chore
</show_dont_tell>
<eliminate_ambiguity> Replace vague phrases with clear directives:
| Ambiguous | Clear Alternative |
|---|---|
| "Try to..." | "Always..." or "Never..." |
| "Should probably..." | "Must..." or "May optionally..." |
| "Generally..." | "Always... except when [condition]" |
| "Consider..." | "If [condition], then [action]" |
</eliminate_ambiguity>
<define_edge_cases> Anticipate questions and answer them:
❌ INCOMPLETE:
Run tests before pushing.
✅ COMPLETE:
## Testing
- Run `pnpm test:ci` before pushing
- If tests fail, fix before committing
- New features require tests in `__tests__/`
- Minimum 80% coverage for new code
</define_edge_cases>
<provide_decision_criteria> When Claude must make choices, give criteria:
## Component Choice
**Use Server Component when:**
- Data fetching only
- No user interaction needed
**Use Client Component when:**
- User interaction required
- Browser APIs needed (localStorage, window)
</provide_decision_criteria>
<separate_obligation_levels> Clearly distinguish requirements from suggestions:
## API Development
### Must Have
- Input validation with Zod
- Error handling for all endpoints
### Nice to Have
- Pagination for list endpoints
- Caching headers
### Must Not
- Expose internal errors to clients
- Log sensitive data
</separate_obligation_levels> </writing_effective_instructions>
<size_constraints>
- Ideal: 100-200 lines maximum
- Practical max: 300 lines before splitting
- Universal items: Under 60 lines
Why these limits matter:
- Claude reliably follows ~150-200 total instructions
- Claude Code's system prompt uses ~50 instructions
- Leaves ~100-150 slots for YOUR instructions
- Irrelevant content degrades instruction-following
<scaling_strategy> When exceeding limits:
- Move task-specific details to separate files
- Link from CLAUDE.md with descriptions
- Use progressive disclosure pattern
## Detailed Guides
- **API Routes**: See [docs/api-patterns.md](docs/api-patterns.md)
- **Testing**: See [docs/testing-guide.md](docs/testing-guide.md)
- **Deployment**: See [docs/deployment.md](docs/deployment.md)
</scaling_strategy> </size_constraints>
<imports_feature> CLAUDE.md supports importing other markdown files:
## External References
@docs/coding-standards.md
@~/.claude/my-global-preferences.md
@./team-conventions.md
<import_rules>
- Supports relative and absolute paths
- Home directory expansion with
~ - Recursive imports up to 5 levels deep
- NOT evaluated inside code blocks or backticks </import_rules> </imports_feature>
<anti_patterns> <never_include> Code Style Rules - Use linters instead (LLMs are expensive, linters are free)
Secrets - NEVER include API keys, database URLs, tokens, credentials
Too Much Content - Link to docs instead of embedding 500+ lines
Extensive Code - Reference files instead (code examples become outdated)
Vague Instructions - Be specific (see <writing_effective_instructions>)
</never_include>
<examples_what_to_avoid>
❌ BAD:
- Use 2-space indentation (use Prettier instead)
- DATABASE_URL=postgresql://... (never include secrets)
- [500 lines of API docs] (link to external file)
- Format code properly (too vague)
✅ GOOD:
- ESLint/Prettier configured (see .eslintrc)
- Credentials in `.env` (never committed)
- API guide: See [docs/api.md](docs/api.md)
- Run `pnpm lint` before committing
</examples_what_to_avoid> </anti_patterns>
For complete examples, see reference files:- Minimal example: references/section-templates.md (templates section)
- Comprehensive SaaS: references/comprehensive-example.md
- Project-specific: references/project-patterns.md (Next.js, Express, Python, Monorepo)
Before creating or updating memory files, ask the user:
Do you want to use a single CLAUDE.md file or split into separate
.claude/rules/files?Option 1: Single CLAUDE.md - All instructions in one file (simpler, best for small projects) Option 2: Modular .claude/rules/ - Split by concern with optional path-scoping (better for large projects)
Use AskUserQuestion to present these options before proceeding.
Decision guide:
- Choose CLAUDE.md if: < 100 lines of instructions, simple project, universal rules
- Choose .claude/rules/ if: 100+ lines, multiple file types with different rules, team maintains different areas </decision_point>
<creating_new> Creating New Memory (CLAUDE.md approach)
- Start with
/initor minimal template - Add tech stack and commands first
- Add conventions as you encounter friction
- Test with real tasks
- Iterate based on Claude's behavior </creating_new>
<creating_rules> Creating New Memory (.claude/rules/ approach)
- Create
.claude/rules/directory - Start with one file per major concern:
general.md- Universal project rulestesting.md- Testing conventionscode-style.md- Code conventions
- Add path-scoped rules as needed:
--- paths: - "src/api/**/*.ts" --- # API rules here - Test with real tasks in different file contexts
- Split or merge files based on usage patterns </creating_rules>
- Review quarterly (or when project changes significantly)
- Remove outdated instructions
- Add patterns that required repeated explanation
- Keep CLAUDE.md under 200 lines (or split to .claude/rules/)
- Use
#for quick additions during work
<migrating_to_rules> Migrating from CLAUDE.md to .claude/rules/
When CLAUDE.md exceeds 200 lines:
- Identify distinct sections (testing, API, frontend, etc.)
- Create
.claude/rules/directory - Move each section to its own file
- Add
pathsfrontmatter where rules are file-type specific - Keep only universal essentials in CLAUDE.md (or delete it)
- Test to ensure rules load correctly </migrating_to_rules>
| Problem | Solution |
|---|---|
| Claude ignores instructions | Reduce file size, add emphasis (CRITICAL, NEVER) |
| Context overflow | Use /clear, split into .claude/rules/ files |
| Outdated information | Review quarterly, remove stale content |
| Instructions conflict | Consolidate, use hierarchy (root vs subtree) |
| Rules not loading | Check file is .md, in correct directory |
| Path rules not applying | Verify glob pattern matches target files |
<advanced_features>
<local_overrides>
Use CLAUDE.local.md for personal preferences (auto-gitignored):
- Personal shortcuts and aliases
- Editor-specific settings
- Local testing commands </local_overrides>
<settings_integration>
CLAUDE.md works alongside settings.json:
settings.json: Permissions, allowed tools, environment variablesCLAUDE.md: Context, conventions, workflow instructions </settings_integration>
<progressive_disclosure> For complex projects, link to detailed docs. Claude only loads when relevant:
## References
- **Database**: See [docs/database.md](docs/database.md)
- **API**: See [docs/api.md](docs/api.md)
</progressive_disclosure> </advanced_features>
<success_criteria> A well-crafted Claude memory system:
For CLAUDE.md approach:
- Loads in under 200 lines
- Contains only project-specific context (not general knowledge)
- Uses emphasis for critical rules (CRITICAL, NEVER, ALWAYS)
- Avoids code style rules (use linters)
- Contains NO secrets or credentials
- Provides clear commands for common tasks
- Follows WHAT-WHY-HOW structure
For .claude/rules/ approach:
- Each file focused on one concern (testing, API, security, etc.)
- Path-scoped rules use accurate glob patterns
- No duplicate rules across files
- Files organized in logical subdirectories
- Symlinks used for shared rules across projects
Both approaches:
- Gets updated as project evolves
- Improves Claude's first-try accuracy on tasks
- User was asked which approach they prefer before implementation </success_criteria>
<reference_guides> For deeper topics:
- Rules directory guide: references/rules-directory-guide.md - Complete guide to .claude/rules/ with official documentation, path-scoping, YAML syntax, and examples
- Prompting techniques: references/prompting-techniques.md - Master guide for writing effective instructions, emphasis strategies, clarity techniques
- Comprehensive example: references/comprehensive-example.md - Full production SaaS CLAUDE.md
- Section templates: references/section-templates.md - Copy-paste templates for each section
- Common patterns by project type: references/project-patterns.md - Next.js, Express, Python, Monorepo patterns </reference_guides>
Skill Creator
This skill provides guidance for creating effective skills.
Official Documentation: https://code.claude.com/docs/llms.txt Fetch the complete documentation index to discover all available pages.
About Skills
Skills are modular, self-contained packages that extend Claude's capabilities by providing specialized knowledge, workflows, and tools. Think of them as "onboarding guides" for specific domains or tasks—they transform Claude from a general-purpose agent into a specialized agent equipped with procedural knowledge that no model can fully possess.
What Skills Provide
- Specialized workflows - Multi-step procedures for specific domains
- Tool integrations - Instructions for working with specific file formats or APIs
- Domain expertise - Company-specific knowledge, schemas, business logic
- Bundled resources - Scripts, references, and assets for complex and repetitive tasks
Core Principles
Concise is Key
The context window is a public good. Skills share the context window with everything else Claude needs: system prompt, conversation history, other Skills' metadata, and the actual user request.
Default assumption: Claude is already very smart. Only add context Claude doesn't already have. Challenge each piece of information: "Does Claude really need this explanation?" and "Does this paragraph justify its token cost?"
Prefer concise examples over verbose explanations.
Set Appropriate Degrees of Freedom
Match the level of specificity to the task's fragility and variability:
High freedom (text-based instructions): Use when multiple approaches are valid, decisions depend on context, or heuristics guide the approach.
Medium freedom (pseudocode or scripts with parameters): Use when a preferred pattern exists, some variation is acceptable, or configuration affects behavior.
Low freedom (specific scripts, few parameters): Use when operations are fragile and error-prone, consistency is critical, or a specific sequence must be followed.
Think of Claude as exploring a path: a narrow bridge with cliffs needs specific guardrails (low freedom), while an open field allows many routes (high freedom).
Where Skills Live
| Location | Path | Applies to |
|---|---|---|
| Enterprise | Managed settings | All users in organization |
| Personal | ~/.claude/skills/<skill-name>/SKILL.md | All your projects |
| Project | .claude/skills/<skill-name>/SKILL.md | This project only |
| Plugin | <plugin>/skills/<skill-name>/SKILL.md | Where plugin is enabled |
Higher-priority locations win when skills share the same name: enterprise > personal > project.
Nested discovery: When working with files in subdirectories, Claude Code automatically discovers skills from nested .claude/skills/ directories (supports monorepos).
Anatomy of a Skill
Every skill consists of a required SKILL.md file and optional bundled resources:
skill-name/
├── SKILL.md (required)
│ ├── YAML frontmatter metadata
│ │ ├── name: (optional, defaults to directory name)
│ │ └── description: (recommended)
│ └── Markdown instructions (required)
└── Bundled Resources (optional)
├── scripts/ - Executable code (Python/Bash/etc.)
├── references/ - Documentation intended to be loaded into context as needed
└── assets/ - Files used in output (templates, icons, fonts, etc.)
SKILL.md (required)
Every SKILL.md consists of:
- Frontmatter (YAML): Configuration fields like
name,description,context,agent,allowed-tools, etc. Thedescriptionfield is most important - Claude uses it to decide when to load the skill automatically. - Body (Markdown): Instructions and guidance for using the skill. Only loaded AFTER the skill triggers (if at all).
Bundled Resources (optional)
Scripts (scripts/)
Executable code (Python/Bash/etc.) for tasks that require deterministic reliability or are repeatedly rewritten.
- When to include: When the same code is being rewritten repeatedly or deterministic reliability is needed
- Example:
scripts/rotate_pdf.pyfor PDF rotation tasks - Benefits: Token efficient, deterministic, may be executed without loading into context
- Note: Scripts may still need to be read by Claude for patching or environment-specific adjustments
References (references/)
Documentation and reference material intended to be loaded as needed into context to inform Claude's process and thinking.
- When to include: For documentation that Claude should reference while working
- Examples:
references/finance.mdfor financial schemas,references/mnda.mdfor company NDA template,references/policies.mdfor company policies,references/api_docs.mdfor API specifications - Use cases: Database schemas, API documentation, domain knowledge, company policies, detailed workflow guides
- Benefits: Keeps SKILL.md lean, loaded only when Claude determines it's needed
- Best practice: If files are large (>10k words), include grep search patterns in SKILL.md
- Avoid duplication: Information should live in either SKILL.md or references files, not both. Prefer references files for detailed information unless it's truly core to the skill—this keeps SKILL.md lean while making information discoverable without hogging the context window. Keep only essential procedural instructions and workflow guidance in SKILL.md; move detailed reference material, schemas, and examples to references files.
Assets (assets/)
Files not intended to be loaded into context, but rather used within the output Claude produces.
- When to include: When the skill needs files that will be used in the final output
- Examples:
assets/logo.pngfor brand assets,assets/slides.pptxfor PowerPoint templates,assets/frontend-template/for HTML/React boilerplate,assets/font.ttffor typography - Use cases: Templates, images, icons, boilerplate code, fonts, sample documents that get copied or modified
- Benefits: Separates output resources from documentation, enables Claude to use files without loading them into context
What to Not Include in a Skill
A skill should only contain essential files that directly support its functionality. Do NOT create extraneous documentation or auxiliary files, including:
- README.md
- INSTALLATION_GUIDE.md
- QUICK_REFERENCE.md
- CHANGELOG.md
- etc.
The skill should only contain the information needed for an AI agent to do the job at hand. It should not contain auxilary context about the process that went into creating it, setup and testing procedures, user-facing documentation, etc. Creating additional documentation files just adds clutter and confusion.
Progressive Disclosure Design Principle
Skills use a three-level loading system to manage context efficiently:
- Metadata (name + description) - Always in context (~100 words)
- SKILL.md body - When skill triggers (<5k words)
- Bundled resources - As needed by Claude (Unlimited because scripts can be executed without reading into context window)
Progressive Disclosure Patterns
Keep SKILL.md body to the essentials and under 500 lines to minimize context bloat. Split content into separate files when approaching this limit. When splitting out content into other files, it is very important to reference them from SKILL.md and describe clearly when to read them, to ensure the reader of the skill knows they exist and when to use them.
Key principle: When a skill supports multiple variations, frameworks, or options, keep only the core workflow and selection guidance in SKILL.md. Move variant-specific details (patterns, examples, configuration) into separate reference files.
Pattern 1: High-level guide with references
# PDF Processing
## Quick start
Extract text with pdfplumber:
[code example]
## Advanced features
- **Form filling**: See [FORMS.md](FORMS.md) for complete guide
- **API reference**: See [REFERENCE.md](REFERENCE.md) for all methods
- **Examples**: See [EXAMPLES.md](EXAMPLES.md) for common patterns
Claude loads FORMS.md, REFERENCE.md, or EXAMPLES.md only when needed.
Pattern 2: Domain-specific organization
For Skills with multiple domains, organize content by domain to avoid loading irrelevant context:
bigquery-skill/
├── SKILL.md (overview and navigation)
└── reference/
├── finance.md (revenue, billing metrics)
├── sales.md (opportunities, pipeline)
├── product.md (API usage, features)
└── marketing.md (campaigns, attribution)
When a user asks about sales metrics, Claude only reads sales.md.
Similarly, for skills supporting multiple frameworks or variants, organize by variant:
cloud-deploy/
├── SKILL.md (workflow + provider selection)
└── references/
├── aws.md (AWS deployment patterns)
├── gcp.md (GCP deployment patterns)
└── azure.md (Azure deployment patterns)
When the user chooses AWS, Claude only reads aws.md.
Pattern 3: Conditional details
Show basic content, link to advanced content:
# DOCX Processing
## Creating documents
Use docx-js for new documents. See [DOCX-JS.md](DOCX-JS.md).
## Editing documents
For simple edits, modify the XML directly.
**For tracked changes**: See [REDLINING.md](REDLINING.md)
**For OOXML details**: See [OOXML.md](OOXML.md)
Claude reads REDLINING.md or OOXML.md only when the user needs those features.
Important guidelines:
- Avoid deeply nested references - Keep references one level deep from SKILL.md. All reference files should link directly from SKILL.md.
- Structure longer reference files - For files longer than 100 lines, include a table of contents at the top so Claude can see the full scope when previewing.
Skill Creation Process
Skill creation involves these steps:
- Understand the skill with concrete examples
- Plan reusable skill contents (scripts, references, assets)
- Initialize the skill (run init-skill.ts)
- Edit the skill (implement resources and write SKILL.md)
- Package the skill (run package-skill.ts)
- Iterate based on real usage
Follow these steps in order, skipping only if there is a clear reason why they are not applicable.
Step 1: Understanding the Skill with Concrete Examples
Skip this step only when the skill's usage patterns are already clearly understood. It remains valuable even when working with an existing skill.
To create an effective skill, clearly understand concrete examples of how the skill will be used. This understanding can come from either direct user examples or generated examples that are validated with user feedback.
For example, when building an image-editor skill, relevant questions include:
- "What functionality should the image-editor skill support? Editing, rotating, anything else?"
- "Can you give some examples of how this skill would be used?"
- "I can imagine users asking for things like 'Remove the red-eye from this image' or 'Rotate this image'. Are there other ways you imagine this skill being used?"
- "What would a user say that should trigger this skill?"
To avoid overwhelming users, avoid asking too many questions in a single message. Start with the most important questions and follow up as needed for better effectiveness.
Conclude this step when there is a clear sense of the functionality the skill should support.
Step 2: Planning the Reusable Skill Contents
To turn concrete examples into an effective skill, analyze each example by:
- Considering how to execute on the example from scratch
- Identifying what scripts, references, and assets would be helpful when executing these workflows repeatedly
Example: When building a pdf-editor skill to handle queries like "Help me rotate this PDF," the analysis shows:
- Rotating a PDF requires re-writing the same code each time
- A
scripts/rotate_pdf.pyscript would be helpful to store in the skill
Example: When designing a frontend-webapp-builder skill for queries like "Build me a todo app" or "Build me a dashboard to track my steps," the analysis shows:
- Writing a frontend webapp requires the same boilerplate HTML/React each time
- An
assets/hello-world/template containing the boilerplate HTML/React project files would be helpful to store in the skill
Example: When building a big-query skill to handle queries like "How many users have logged in today?" the analysis shows:
- Querying BigQuery requires re-discovering the table schemas and relationships each time
- A
references/schema.mdfile documenting the table schemas would be helpful to store in the skill
To establish the skill's contents, analyze each concrete example to create a list of the reusable resources to include: scripts, references, and assets.
Step 3: Initializing the Skill
At this point, it is time to actually create the skill.
Skip this step only if the skill being developed already exists, and iteration or packaging is needed. In this case, continue to the next step.
When creating a new skill from scratch, always run the init-skill.ts script. The script conveniently generates a new template skill directory that automatically includes everything a skill requires, making the skill creation process much more efficient and reliable.
Usage:
bun scripts/init-skill.ts <skill-name> --path <output-directory>
The script:
- Creates the skill directory at the specified path
- Generates a SKILL.md template with proper frontmatter and TODO placeholders
- Creates example resource directories:
scripts/,references/, andassets/ - Adds example files in each directory that can be customized or deleted
After initialization, customize or remove the generated SKILL.md and example files as needed.
Step 4: Edit the Skill
When editing the (newly-generated or existing) skill, remember that the skill is being created for another instance of Claude to use. Include information that would be beneficial and non-obvious to Claude. Consider what procedural knowledge, domain-specific details, or reusable assets would help another Claude instance execute these tasks more effectively.
Learn Proven Design Patterns
Consult these helpful guides based on your skill's needs:
- Multi-step processes: See references/workflows.md for sequential workflows and conditional logic
- Specific output formats or quality standards: See references/output-patterns.md for template and example patterns
These files contain established best practices for effective skill design.
Start with Reusable Skill Contents
To begin implementation, start with the reusable resources identified above: scripts/, references/, and assets/ files. Note that this step may require user input. For example, when implementing a brand-guidelines skill, the user may need to provide brand assets or templates to store in assets/, or documentation to store in references/.
Added scripts must be tested by actually running them to ensure there are no bugs and that the output matches what is expected. If there are many similar scripts, only a representative sample needs to be tested to ensure confidence that they all work while balancing time to completion.
Any example files and directories not needed for the skill should be deleted. The initialization script creates example files in scripts/, references/, and assets/ to demonstrate structure, but most skills won't need all of them.
Update SKILL.md
Writing Guidelines: Always use imperative/infinitive form.
Frontmatter
Write the YAML frontmatter. All fields are optional except description which is recommended.
Core fields:
name: Display name (lowercase letters, numbers, hyphens, max 64 chars). If omitted, uses directory name.description: What the skill does and when to use it. Claude uses this to decide when to load the skill automatically.- Example: "Explains code with diagrams and analogies. Use when explaining how code works or when user asks 'how does this work?'"
Invocation control:
disable-model-invocation: true- Only user can invoke (prevents Claude auto-loading). Use for workflows with side effects like/deploy.user-invocable: false- Only Claude can invoke. Use for background knowledge that isn't actionable as a command.argument-hint: Hint shown during autocomplete. Example:[issue-number]or[filename]
Execution control:
allowed-tools: Tools Claude can use without asking permission when skill is active.model: Model to use when skill is active.context: fork- Run in a forked subagent context (isolated, no conversation history).agent: Which subagent type to use whencontext: forkis set (e.g.,Explore,Plan,general-purpose, or custom agent).hooks: Hooks scoped to this skill's lifecycle.
String substitutions (in skill content):
$ARGUMENTS- All arguments passed when invoking the skill${CLAUDE_SESSION_ID}- Current session ID
Dynamic context injection: Prefix a shell command with exclamation mark and wrap in backticks to run it before the skill content is sent to Claude. The output replaces the placeholder.
Syntax: exclamation + backtick + command + backtick (e.g., for "gh pr diff")
See official docs for examples: https://code.claude.com/en/skills#inject-dynamic-context
Subagent execution example:
---
name: deep-research
description: Research a topic thoroughly
context: fork
agent: Explore
---
Research $ARGUMENTS thoroughly:
1. Find relevant files using Glob and Grep
2. Read and analyze the code
3. Summarize findings with file references
See official documentation: https://code.claude.com/docs/llms.txt
Body
Write instructions for using the skill and its bundled resources.
Step 5: Packaging a Skill
Once development of the skill is complete, it must be packaged into a distributable .skill file that gets shared with the user. The packaging process automatically validates the skill first to ensure it meets all requirements:
bun scripts/package-skill.ts <path/to/skill-folder>
Optional output directory specification:
bun scripts/package-skill.ts <path/to/skill-folder> ./dist
The packaging script will:
-
Validate the skill automatically, checking:
- YAML frontmatter format and required fields
- Skill naming conventions and directory structure
- Description completeness and quality
- File organization and resource references
-
Package the skill if validation passes, creating a .skill file named after the skill (e.g.,
my-skill.skill) that includes all files and maintains the proper directory structure for distribution. The .skill file is a zip file with a .skill extension.
If validation fails, the script will report the errors and exit without creating a package. Fix any validation errors and run the packaging command again.
Step 6: Iterate
After testing the skill, users may request improvements. Often this happens right after using the skill, with fresh context of how the skill performed.
Iteration workflow:
- Use the skill on real tasks
- Notice struggles or inefficiencies
- Identify how SKILL.md or bundled resources should be updated
- Implement changes and test again
Reference Guides
For deeper topics and advanced patterns, see:
- references/xml-tag-guide.md - Complete guide to XML tags and structure (required/conditional tags, nesting, naming conventions)
- references/progressive-disclosure-patterns.md - Advanced strategies for organizing content across multiple files
- references/prompting-integration.md - How to integrate expert prompting techniques into skills
- references/real-world-examples.md - Complete examples of well-structured skills (simple, standard, complex)
- references/script-patterns.md - Executable code patterns, error handling, script templates
- references/output-patterns.md - Template and example patterns for consistent output
- references/workflows.md - Sequential and conditional workflow patterns
Sponsors
Details
- Marketplace
- atournayre/claude-marketplace
- Source
- claude
- Category
- Community
