# Creating Skills

> Create reusable skills that teach AI agents techniques, patterns, or reference material. Use when a proven approach should be captured for reuse across projects

- Skill: `azat-io/creating-skills` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add azat-io/creating-skills`
- Raw SKILL.md: https://api.skillmd.com/api/skills/azat-io/creating-skills/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: azat-io (https://skillmd.com/u/azat-io)
- Updated: 2026-09-10
- Page: https://skillmd.com/skills/azat-io/creating-skills

---


# Creating Skills

Skills are reference guides for proven techniques, patterns, or tools. They help
AI agents find and apply effective approaches.

## When to Create

- Technique wasn't intuitively obvious
- Pattern applies broadly (not project-specific)
- Would reference this again across projects

Skip if: one-off solution, project-specific convention (→ put in CLAUDE.md), or
well-documented elsewhere.

## Skill Types

| Type      | Purpose                        | Example                  |
| --------- | ------------------------------ | ------------------------ |
| Technique | Concrete method with steps     | discovering, researching |
| Pattern   | Way of thinking about problems | creating-subagents       |
| Reference | API docs, syntax guides        | tool documentation       |

## File Structure

```
skills/
  skill-name/
    skill.md    # Main reference (required)
    *.md        # Supporting files if needed
```

## skill.md Structure

```markdown
---
name: skill-name
description: [What it does]. Use when [specific triggering conditions].
---

# Skill Name

## Overview

What is this? Core principle in 1-2 sentences.

## When to Use

- Symptoms, situations, triggers
- When NOT to use

## Quick Reference

Table or bullets for scanning.

## Core Pattern

Main technique or approach.

## Delegate (if applicable)

Which agents/subagents to use and when.

## Common Mistakes

What goes wrong + fixes.
```

## Description Rules

**Description = What It Does + When to Use It**

Write in third person: one clause for the capability, then the triggers.

```yaml
# ❌ BAD: Retells the workflow step by step
description:
  Frame the problem, collect signals, compare 2-3 options, write a brief.

# ❌ BAD: Too vague
description: For research tasks.

# ❌ BAD: Triggers only, no capability signal
description: Use when requirements are fuzzy or multiple approaches exist.

# ✅ GOOD: Capability + triggering conditions
description:
  Evaluate technical options with evidence and choose an approach. Use when
  requirements are fuzzy or multiple approaches exist.
```

Why: The description is the only signal AI uses to pick a skill among many —
without a capability summary, routing degrades. Keep the capability to one
clause: if it retells the workflow, AI may follow the description instead of
reading the full skill content.

## Naming

- Lowercase with hyphens: `creating-skills`
- Gerunds for processes: `discovering`, `researching`, `creating-subagents`
- Verb-first, active voice

## Design Process

### 1. Define the Problem

Before writing:

- What technique/pattern does this teach?
- When should AI use this skill?
- What are the triggering symptoms?

### 2. Write Description First

Description determines when skill is loaded. Write it before content.

### 3. Minimal Content

- Start with the smallest skill that works
- Add sections only when needed
- Tables > prose for reference material

### 4. Test Before Deploy

Run scenarios where skill should activate:

- Does AI find the skill?
- Does AI follow the technique correctly?
- Are there gaps or ambiguities?

### 5. Iterate

When skill fails, identify the gap and fix.

## Common Mistakes

| Mistake                      | Fix                                         |
| ---------------------------- | ------------------------------------------- |
| Description retells workflow | One capability clause + triggers            |
| Too much content             | Minimal, scannable, tables                  |
| Narrative storytelling       | Structured reference format                 |
| Project-specific rules       | Put in CLAUDE.md instead                    |
| No "When to Use" section     | Always include triggers and skip conditions |
| Generic labels in examples   | Semantic, meaningful names                  |

## Cross-References

Reference other skills by name:

```markdown
# ✅ Good

**Prerequisites:** Use **discovering** skill first.

# ❌ Bad: force-loads file

@skills/discovering/skill.md
```

## Creation Checklist

- [ ] Problem clearly defined
- [ ] Description states capability, then "Use when..." triggers
- [ ] Description has no step-by-step workflow
- [ ] Name uses gerund for processes
- [ ] When to Use section with triggers and skip conditions
- [ ] Quick Reference for scanning
- [ ] Common Mistakes section
- [ ] Delegate section if skill uses agents or subagents
- [ ] Pipeline navigation (what comes before/after), if part of a pipeline
- [ ] Tested on real scenario