Skill Creator

Skill Creation Guide

This skill helps you create well-structured Claude Code skills following official best practices.

When to Create a Skill

Key insight: Skills load on-demand via progressive disclosure. CLAUDE.md loads every conversation. Use skills for domain expertise you don't always need.

Required Structure

Every skill needs a directory with at minimum a SKILL.md file:

skill-name/
└── SKILL.md

SKILL.md Format

---
name: skill-name
description: What this skill does and WHEN to use it. Claude uses this to decide when to invoke the skill automatically.
---

# Skill Title

## Instructions
[Step-by-step guidance for Claude to follow]

## Examples
[Concrete examples of using this skill]

Field Requirements

name (required):

• Max 64 characters
• Lowercase letters, numbers, hyphens only
• No reserved words: "anthropic", "claude"

description (required):

• Max 1024 characters
• Must explain both WHAT and WHEN
• Claude uses this to decide when to invoke

Optional Frontmatter

---
name: skill-name
description: Description here
disable-model-invocation: true  # Only user can invoke via /skill-name
user-invocable: false           # Only Claude can invoke (background knowledge)
allowed-tools: Read, Grep, Glob # Restrict tool access
context: fork                   # Run in isolated subagent
agent: Explore                  # Which agent type when forked
---

Invocation Control Matrix

Progressive Disclosure (3 Levels)

Skills load content in stages to minimize token usage:

Implication: You can bundle extensive reference materials without token penalty until actually used.

Adding Resources

For complex skills, add additional files:

skill-name/
├── SKILL.md           # Main instructions (required)
├── REFERENCE.md       # Additional docs (loaded when referenced)
├── templates/
│   └── template.yaml  # Templates to apply
└── scripts/
    └── validate.sh    # Scripts Claude can execute

Reference these in SKILL.md:

For API details, see [REFERENCE.md](REFERENCE.md).
Use the template in [templates/template.yaml](templates/template.yaml).

Dynamic Context Injection

Use backtick commands to inject live data before the skill runs:

## Current State
- Branch: !`git branch --show-current`
- Status: !`git status --short`

The command output replaces the placeholder before Claude sees the content.

Arguments Pattern

Skills can receive arguments when invoked:

Generate documentation for: $ARGUMENTS

When user runs /skill-name src/utils.ts, $ARGUMENTS becomes src/utils.ts.

Best Practices

1. Keep it focused - One workflow per skill. Multiple focused skills compose better than one large skill.

2. Write clear descriptions - Claude uses the description to decide when to invoke. Be specific about triggers.

3. Start simple - Begin with basic instructions in Markdown before adding scripts.

4. Use examples - Include example inputs/outputs so Claude understands success.

5. Test incrementally - Test after each change rather than building complex skills all at once.

6. Tool docstrings matter - If your skill references scripts, their docstrings help Claude understand usage.

7. Avoid secrets - Never hardcode API keys or passwords.

Example: API Documentation Skill

api-doc/
├── SKILL.md
└── openapi-template.yaml

SKILL.md:

---
name: api-doc
description: Generate OpenAPI documentation for an endpoint. Use when documenting API routes or creating API specs.
---

Generate OpenAPI documentation for the endpoint at $ARGUMENTS.

Use the template in [openapi-template.yaml](openapi-template.yaml) as the structure.

1. Read the endpoint code
2. Extract path, method, parameters, request/response schemas
3. Fill in the template with actual values
4. Output the completed YAML

Example: Deploy Skill (User-Only)

---
name: deploy-staging
description: Deploy current branch to staging environment
disable-model-invocation: true  # Prevent accidental deploys
---

## Pre-deploy Checks
- Branch: !`git branch --show-current`
- Status: !`git status --short`

## Steps
1. Verify all changes are committed
2. Run `railway up --detach` from the correct directory
3. Monitor logs: `timeout 10 railway logs`
4. Report deployment status

Example: Background Knowledge Skill

---
name: project-conventions
description: Code style and patterns for this project. Apply when writing or reviewing code.
user-invocable: false  # Claude-only, automatic
---

## Naming
- Components: PascalCase
- Utilities: camelCase
- Files: kebab-case

## Patterns
- Use `Result<T, E>` for fallible operations
- All API responses: `{ data, error, meta }`

## Forbidden
- No `any` types
- No `console.log` in production

References

• Official Skills Documentation
• Skills Cookbook
• Example Skills
• Agent Skills Spec