Creating Extensions¶
Build custom skills and extensions to codify team knowledge and workflows.
Skill Architecture¶
my-skill/
├── SKILL.md # Required: frontmatter + instructions
├── scripts/ # Optional: helper scripts
│ └── helper.py
├── references/ # Optional: additional docs
│ └── api-spec.md
└── assets/ # Optional: templates, fonts, etc.
└── template.docx
SKILL.md Anatomy¶
---
# FRONTMATTER (Required)
name: my-skill-name # Lowercase, hyphens only
description: >
Clear description of what this skill does.
Include trigger phrases: "Use when user asks to..."
# OPTIONAL FRONTMATTER
context: fork # Run in isolated context (fork) or inline
agent: Explore # Which subagent to use
allowed-tools: # Tools granted without per-use approval
- Read
- Glob
- Grep
disable-model-invocation: true # Require explicit /skill-name invocation
---
# Skill Name
## Instructions
Clear, step-by-step guidance for Claude.
## Examples
Concrete usage examples.
## Guidelines
- Guideline 1
- Guideline 2
Frontmatter Fields¶
| Field | Required | Description |
|---|---|---|
name |
Yes | Lowercase with hyphens: code-review |
description |
Yes | What the skill does + trigger phrases |
context |
No | fork for isolated context, omit for inline |
agent |
No | Subagent type: Explore, Plan, or custom |
allowed-tools |
No | Tools available without approval |
disable-model-invocation |
No | Require explicit /skill-name |
user-invocable |
No | false = hidden from / menu (background knowledge only) |
hooks |
No | Hook definitions scoped to this skill |
Skill Templates¶
Code Review Skill¶
---
name: code-review
description: >
Reviews code for bugs, style, and patterns. Use when someone asks
to review code, check code quality, or find issues in a PR.
---
# Code Review
## Instructions
When reviewing code:
1. **Read the diff** — understand what changed
2. **Check against project patterns** in CLAUDE.md
3. **Look for**:
- Type safety issues (no `any`, proper null handling)
- Missing error handling
- Security concerns (input validation, SQL injection)
- Performance issues (N+1 queries, unnecessary re-renders)
- Test coverage gaps
4. **Format feedback** as:
- **Critical**: Must fix before merge
- **Suggestion**: Consider improving
- **Nitpick**: Minor style issue
## Guidelines
- Don't rewrite entire functions — suggest targeted fixes
- Reference existing patterns when suggesting changes
- Always explain *why* something is an issue
Retrospective Skill¶
---
name: retrospective
description: >
Save learnings from the current session as a new skill.
Use when finishing an experiment, debugging session, or
discovering something worth documenting.
---
# Retrospective
## Instructions
1. Summarize key findings from this conversation
2. Structure as:
- **Goal**: What we were trying to do
- **What Worked**: Successful approaches
- **What Failed**: Approaches that didn't work (include why)
- **Final Parameters**: Exact values/configurations that worked
3. Create a new skill in `.claude/skills/learnings/`
4. Create a branch and open a PR
ADR Skill¶
---
name: adr
description: >
Create Architecture Decision Records. Use when making
significant technical decisions or choosing between approaches.
---
# ADR Creator
## Instructions
Create an ADR in `docs/decisions/` with format `NNNN-title.md`:
```markdown
# [Number]. [Title]
Date: [YYYY-MM-DD]
Status: [proposed | accepted | deprecated | superseded]
## Context
[What is the issue? Why are we making this decision?]
## Decision
[What is the change we're making?]
## Consequences
### Positive
- [Benefit 1]
### Negative
- [Tradeoff 1]
Find the next ADR number by checking existing files in docs/decisions/.
### FastAPI Endpoint Skill
```yaml
---
name: fastapi-endpoint
description: >
Create FastAPI endpoints following our patterns. Use when
adding new API routes or building new backend features.
---
# FastAPI Endpoint Creator
## Our Patterns
### File Structure
Each feature gets its own domain folder:
### Router Pattern
```python
from fastapi import APIRouter, Depends, HTTPException, status
from sqlalchemy.ext.asyncio import AsyncSession
from src.database import get_db
from src.[domain] import schemas, service
router = APIRouter(prefix="/[domain]", tags=["[Domain]"])
@router.get("/{id}", response_model=schemas.[Domain]Response)
async def get_[domain](
id: int,
db: AsyncSession = Depends(get_db),
) -> schemas.[Domain]Response:
"""Get a [domain] by ID."""
result = await service.get_[domain](db, id)
if not result:
raise HTTPException(
status_code=status.HTTP_404_NOT_FOUND,
detail="[Domain] not found",
)
return result
Guidelines¶
- ALWAYS use async/await for database operations
- ALWAYS validate input with Pydantic
- ALWAYS include docstrings for endpoints
- NEVER put business logic in routers — use service.py
--- ## Dynamic Context Injection Use the `` `!command` `` syntax to inject runtime data into your skill: ```yaml --- name: deploy-status description: Check deployment status for the current branch. --- # Deploy Status ## Current Branch `!git branch --show-current` ## Recent Deploys `!gh run list --branch $(git branch --show-current) --limit 3`
Commands prefixed with ! execute when the skill loads, providing up-to-date context.
For the full skills reference, see official docs.
Testing Skills¶
1. Verify Frontmatter¶
Check for YAML syntax errors — invalid frontmatter silently breaks skills.
2. Check Discovery¶
Your skill should appear in the list.
3. Test Automatic Triggering¶
Ask a question matching the skill's description trigger phrases:
4. Test Explicit Triggering¶
5. Verify Instructions Are Followed¶
Check that Claude follows the skill's step-by-step instructions, not its own default behavior.
Publishing Skills¶
Personal Skills¶
Place in ~/.claude/skills/my-skill/SKILL.md — available in all your projects.
Team Skills¶
Place in .claude/skills/my-skill/SKILL.md — committed to git, shared with the team.
Plugin Skills¶
Bundle skills into a plugin for distribution via the marketplace. See the Marketplace Overview for the full catalog and contributing guide.