Skill Writer

Guide for creating and maintaining Agent Skills for Claude Code.

When to Use

• Creating a new skill
• Improving an existing skill
• Adding resources to a skill

Skill Structure

.claude/skills/[skill-name]/
├── SKILL.md              # Main skill file (required)
└── resources/            # Supporting files (optional)
    ├── patterns.md       # Code patterns
    ├── examples.md       # Working examples
    └── reference.md      # API reference

SKILL.md Format

Frontmatter (Required)

---
name: skill-name          # lowercase, hyphens, max 64 chars
description: Brief description of what this skill does and when to use it. Max 1024 chars.
---

Content Structure

# Skill Title

**Activation:** Keywords that trigger this skill

## Overview
Brief explanation of the skill's purpose.

## Key Patterns
Code patterns with examples.

## Common Tasks
Step-by-step for frequent operations.

## Resources
Link to resources/ files for deep dives.

Writing Effective Skills

1. Clear Activation Triggers

Include keywords in the description and first section:

**Activation:** FastAPI, SQLAlchemy, async Python, database operations

2. Concise Main File

• Keep SKILL.md under 500 lines
• Put detailed reference in resources/
• Focus on "what to do" not "what it is"

3. Working Examples

# GOOD: Complete, copy-paste ready
@router.get("/items/{id}")
async def get_item(
    id: int,
    db: Annotated[AsyncSession, Depends(get_db)],
) -> Item:
    item = await db.get(Item, id)
    if not item:
        raise HTTPException(status_code=404)
    return item

# BAD: Pseudocode
def get_item(id):
    # query database
    # return item

4. Progressive Disclosure

Main file → Quick patterns Resources → Deep dives, edge cases, full API

5. Actionable Instructions

# GOOD
Use `selectinload()` to eager-load relationships:
```python
stmt = select(User).options(selectinload(User.posts))

BAD

Consider using eager loading for better performance.

## Skill Activation

Claude Code activates skills automatically via **semantic matching** of the YAML frontmatter:

1. **name** - The skill identifier
2. **description** - Describes what the skill does and when to use it

When a user's prompt matches the description semantically, Claude loads and applies the skill.

**Best practices for descriptions:**
- Include specific keywords users would say
- Mention technologies/frameworks covered
- Keep under 1024 characters

Example:
```yaml
---
name: frontend-dev
description: Astro + React islands with TanStack (Query, Form, Table) and Tailwind CSS. Use for frontend UI development, components, data fetching, forms, and styling.
---

This activates when users mention "React component", "TanStack Query", "Tailwind", etc.

Skill Creation Checklist

• Created SKILL.md with frontmatter
• Description includes trigger keywords
• Examples are complete and tested
• Under 500 lines (use resources/ for more)
• Tested activation with relevant prompts

Updating Existing Skills

1. Read current SKILL.md
2. Identify what's missing or outdated
3. Update patterns to latest versions
4. Add new examples if needed
5. Update description in frontmatter if activation triggers changed

This Project's Skills