writing-skills

hgeldenhuys's avatarfrom hgeldenhuys

Guide for creating effective Claude Code skills. Use when creating new skills, refactoring existing skills, or validating skill structure. Covers YAML frontmatter, progressive disclosure, naming conventions, and best practices.

⭐1stars🔀0forks📁View on GitHub🕐Updated Jan 8, 2026
[Prompt Templates and Packaging]

When & Why to Use This Skill

This Claude skill provides a comprehensive framework and standardized methodology for developing high-quality Claude Code skills. It helps developers create structured, discoverable, and efficient agent capabilities by enforcing best practices in YAML frontmatter configuration, naming conventions, and progressive disclosure patterns, ultimately improving the reliability and maintainability of custom AI workflows.

Use Cases

  • Standardizing Skill Development: Use the guide to ensure all team-contributed skills follow the mandatory gerund naming conventions and YAML structures for optimal agent discovery.
  • Refactoring Monolithic Instructions: Apply progressive disclosure patterns to split over-lengthy SKILL.md files into modular reference files like TEMPLATES.md and EXAMPLES.md to keep the agent's context window clean.
  • Implementing Advanced Agent Logic: Configure complex behaviors such as forked contexts for isolated sub-agents or lifecycle hooks (PreToolUse/PostToolUse) for automated validation.
  • Quality Assurance for Agentic Workflows: Utilize the built-in validation checklist to audit existing skills, ensuring they include copyable workflows and clear third-person descriptions for better SEO and usability.
namewriting-skills
descriptionGuide for creating effective Claude Code skills. Use when creating new skills, refactoring existing skills, or validating skill structure. Covers YAML frontmatter, progressive disclosure, naming conventions, and best practices.

Writing Skills

Create effective Claude Code skills that are concise, well-structured, and follow official best practices.

Quick Reference

Element Requirement
Filename SKILL.md in skill directory
Name Lowercase, hyphens, numbers only (max 64 chars)
Description Third person, max 1024 chars
Main file Under 500 lines
References One level deep from SKILL.md

YAML Frontmatter

Every skill requires frontmatter:

---
name: skill-name
description: Third person description of what skill does and when to use it. Include trigger phrases.
allowed-tools: ["Read", "Write", "Edit", "Glob", "Grep", "Bash"]  # Optional
model: sonnet  # Optional: opus, sonnet, haiku
---

Frontmatter Fields

Field Required Notes
name Yes Lowercase letters, numbers, hyphens. Max 64 chars
description Yes Third person. Max 1024 chars. Include when to use
allowed-tools No Restricts which tools the skill can use
model No Force specific model (opus, sonnet, haiku)
context No Set to fork to run in sub-agent context
agent No Agent type when context: fork (requires context)
hooks No Lifecycle-scoped hooks (PreToolUse, PostToolUse, Stop)
user-invocable No false hides from slash menu but allows Skill tool
disable-model-invocation No true blocks Skill tool invocation

Naming Conventions

Use gerund form (verb ending in -ing):

Good Avoid
writing-skills skill-writer
debugging-api api-debugger
creating-hooks hook-creator

Rules:

  • Lowercase letters, numbers, hyphens only
  • No spaces or underscores
  • Maximum 64 characters
  • Descriptive of what the skill helps accomplish

Progressive Disclosure

Keep SKILL.md focused. Split detailed content to reference files.

Pattern 1: Table of Contents

## Reference Files

| File | Contents |
|------|----------|
| [TEMPLATES.md](./TEMPLATES.md) | Starter templates |
| [EXAMPLES.md](./EXAMPLES.md) | Real-world examples |
| [TROUBLESHOOTING.md](./TROUBLESHOOTING.md) | Common issues |

For detailed templates, see [TEMPLATES.md](./TEMPLATES.md).

Pattern 3: Conditional Loading

## Advanced Configuration

If you need custom model settings, see [ADVANCED.md](./ADVANCED.md).

Skill Structure

  1. Quick Reference - Table with key requirements
  2. Core Instructions - Main guidance (bulk of skill)
  3. Workflows - Step-by-step procedures with checklists
  4. Examples - Input/output pairs
  5. Reference Files - Links to detailed content

File Organization

skills/
└── skill-name/
    ├── SKILL.md           # Main skill file (required)
    ├── TEMPLATES.md       # Starter templates (optional)
    ├── EXAMPLES.md        # Detailed examples (optional)
    └── TROUBLESHOOTING.md # Common issues (optional)

Skill Discovery Locations

Skills are discovered from these locations:

Location Scope Priority
.claude/skills/ Current project Highest
~/.claude/skills/ All your projects Lower
Plugin skills/ Where plugin enabled Lowest

Nested Skills Discovery (2.1.6+): When working with files in subdirectories, Claude Code automatically discovers skills from nested .claude/skills directories. This enables monorepos and multi-package projects to have package-specific skills.

my-monorepo/
├── .claude/skills/          # Root skills (always available)
│   └── deploy/
├── packages/
│   ├── frontend/
│   │   └── .claude/skills/  # Auto-discovered when working in frontend/
│   │       └── component-generator/
│   └── backend/
│       └── .claude/skills/  # Auto-discovered when working in backend/
│           └── api-scaffolder/

Writing Effective Descriptions

Descriptions appear in skill discovery. Make them count.

Structure

[What it does]. [When to use it]. [Key triggers/phrases].

Examples

Good:

Guide for creating effective Claude Code skills. Use when creating new
skills, refactoring existing skills, or validating skill structure.
Covers YAML frontmatter, progressive disclosure, and naming conventions.

Avoid:

A skill for writing skills.

Workflows

Include step-by-step workflows with copyable checklists.

Workflow Template

## Workflow: [Name]

### Prerequisites
- [ ] Requirement 1
- [ ] Requirement 2

### Steps

1. **Step Name**
   - [ ] Action item
   - [ ] Action item

2. **Step Name**
   - [ ] Action item

### Validation
- [ ] Check 1
- [ ] Check 2

Examples Section

Show concrete input/output pairs.

Example Template

## Examples

### Example: [Scenario Name]

**Input:**

User request or context


**Output:**

Expected result or response


**Why:** Brief explanation of approach.

Validation Checklist

Before finalizing a skill:

  • Name uses gerund form
  • Name is lowercase with hyphens only
  • Description is third person
  • Description includes when to use
  • SKILL.md is under 500 lines
  • Reference files are one level deep
  • Workflows have copyable checklists
  • Examples show input/output pairs

Common Mistakes

Mistake Fix
Over 500 lines Split to reference files
Vague description Add specific triggers and use cases
No workflows Add step-by-step procedures
Missing examples Add input/output pairs
Deep file nesting Keep references one level deep

Advanced Configuration

Forked Context

Run skills in an isolated sub-agent context using context: fork:

---
name: complex-analysis
description: Deep analysis that benefits from isolated context
context: fork
agent: Explore  # Optional: specify agent type
---

When to use:

  • Long-running analysis that shouldn't pollute main context
  • Skills that generate large outputs
  • Isolated workflows that should not affect main conversation

Visibility Control

Control how skills appear and can be invoked:

Setting Slash Menu Skill Tool Use Case
(default) Visible Allowed Normal skill
user-invocable: false Hidden Allowed Model-only skills
disable-model-invocation: true Visible Blocked User-only skills
Both false/true Hidden Blocked Completely hidden 
---
name: internal-helper
description: Helper skill only invoked by other skills
user-invocable: false  # Hide from slash menu
---

Skills with Hooks

Add lifecycle hooks that run during skill execution:

---
name: validated-deploy
description: Deploy with validation hooks
hooks:
  PreToolUse:
    - matcher: "Bash"
      hooks:
        - type: command
          command: "./validate.sh"
          once: true
---

See creating-hooks for complete hook documentation.

Skills in Subagents

Skills can be auto-loaded for custom subagents using the skills field in agent definitions:

# .claude/agents/code-reviewer.md
---
name: code-reviewer
description: Reviews code using specialized skills
skills:
  - code-review
  - security-practices
---

Note: Built-in agents (Explore, Plan, general-purpose) do not have skill access.

Reference Files

File Contents
TEMPLATES.md Starter templates for new skills
EXAMPLES.md Real-world skill examples