# Creating Skills

> Guide for creating Claude Code skills following Anthropic's official best practices. Use when user wants to create a new skill, build a skill, write SKILL.md, update an existing skill, or needs skill creation guidelines. Provides structure, frontmatter fields, naming conventions, and new features like dynamic context injection and subagent execution.

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

---


# Creating skills

Guide for creating Claude Code skills following Anthropic's official best practices.

## Project skill layout

This project uses a unified `skills/` directory at the repo root, symlinked into tool-specific config directories:

```
<project-root>/
├── skills/                  # Canonical location for all skills
│   ├── code-review/
│   ├── creating-skills/
│   ├── dev/
│   └── git-commit/
├── .opencode/
│   └── skills -> ../skills  # Symlink for OpenCode
└── .codewiz/
    └── skills -> ../skills  # Symlink for Codewiz
```

This way a single set of skill definitions is shared across multiple AI coding tools.

## Quick start

```bash
# 1. Create skill directory (in the project's unified skills/ dir)
mkdir -p skills/<skill-name>

# 2. Create SKILL.md with frontmatter
cat > skills/<skill-name>/SKILL.md << 'EOF'
---
name: <skill-name>
description: <what it does>. Use when <triggers>. <capabilities>.
---

# <Skill title>

<instructions>
EOF

# 3. Add optional resources as needed
mkdir -p skills/<skill-name>/{scripts,references,assets}

# 4. Ensure symlinks exist (one-time setup per tool)
# ln -s ../skills .opencode/skills
# ln -s ../skills .codewiz/skills
```

## SKILL.md structure

### Frontmatter (YAML between `---` markers)

| Field                      | Required    | Description                                                                             |
| -------------------------- | ----------- | --------------------------------------------------------------------------------------- |
| `name`                     | No          | Display name. Defaults to directory name. Lowercase, hyphens, max 64 chars.             |
| `description`              | Recommended | What + when + capabilities. Max 1024 chars. Determines when Claude activates the skill. |
| `allowed-tools`            | No          | Tools Claude can use without asking permission when skill is active.                    |
| `argument-hint`            | No          | Autocomplete hint for arguments. Example: `[issue-number]`                              |
| `disable-model-invocation` | No          | `true` to prevent auto-invocation (manual `/name` only).                                |
| `user-invocable`           | No          | `false` to hide from `/` menu (background knowledge only).                              |
| `model`                    | No          | Model override when skill is active.                                                    |
| `context`                  | No          | `fork` to run in isolated subagent context.                                             |
| `agent`                    | No          | Subagent type when `context: fork`. Built-in: `Explore`, `Plan`, `general-purpose`.     |
| `hooks`                    | No          | Lifecycle hooks scoped to this skill.                                                   |

### Invocation control matrix

| Configuration                    | User can invoke | Claude can invoke |
| -------------------------------- | --------------- | ----------------- |
| (defaults)                       | Yes             | Yes               |
| `disable-model-invocation: true` | Yes             | No                |
| `user-invocable: false`          | No              | Yes               |

### Description formula

```
<what it does>. Use when <triggers>. <capabilities>.
```

Include action verbs ("create", "handle"), user intent ("wants to", "needs to"), and domain keywords users would say.

## Directory structure

```
skill-name/
├── SKILL.md          # Required: instructions (keep under 500 lines)
├── scripts/          # Optional: executable code (deterministic, token-efficient)
├── references/       # Optional: docs loaded into context on demand
└── assets/           # Optional: files used in output, NOT loaded into context
                      # (templates, images, fonts, boilerplate)
```

### Progressive disclosure (3-level loading)

1. **Metadata** (name + description) - always in context (~100 tokens per skill)
2. **SKILL.md body** - loaded when skill triggers (keep under 5k words)
3. **Bundled resources** - loaded as needed by Claude

Reference supporting files from SKILL.md so Claude knows they exist. Keep references one level deep. For files over 100 lines, include a table of contents.

### Scripts vs references vs assets

| Type          | Purpose                                      | Loaded into context?       |
| ------------- | -------------------------------------------- | -------------------------- |
| `scripts/`    | Deterministic operations, complex processing | No (executed via bash)     |
| `references/` | Documentation Claude reads while working     | Yes, on demand             |
| `assets/`     | Templates, images, fonts for output          | No (copied/used in output) |

Only create scripts when they add value: complex multi-step processing, repeated code generation, deterministic reliability. Not for single-command wrappers.

## Dynamic features

### Context injection

Inject shell command output into skill content before loading:

```markdown
## Recent commits
!`git log --oneline -5 2>/dev/null`
```

The output replaces the directive when the skill loads.

### String substitutions

Pass arguments to skills invoked via `/skill-name arg1 arg2`:

| Variable                         | Value                         |
| -------------------------------- | ----------------------------- |
| `$ARGUMENTS`                     | Full argument string          |
| `$ARGUMENTS[0]`, `$ARGUMENTS[1]` | Individual arguments          |
| `$1`, `$2`                       | Shorthand for `$ARGUMENTS[N]` |

### Subagent execution

Run a skill in isolated context with `context: fork`:

```yaml
---
name: deep-research
description: Research a topic thoroughly.
context: fork
agent: Explore
---
```

## Degrees of freedom

Match specificity to the task's fragility:

| Level                                       | When to use                                  | Example                                     |
| ------------------------------------------- | -------------------------------------------- | ------------------------------------------- |
| **High** (text instructions)                | Multiple valid approaches, context-dependent | "Analyze the code and suggest improvements" |
| **Medium** (pseudocode/scripts with params) | Preferred pattern exists, some variation OK  | Script with configurable parameters         |
| **Low** (specific scripts, few params)      | Fragile operations, consistency critical     | Exact sequence of API calls                 |

## Naming conventions

- Lowercase, hyphens between words, max 64 chars
- Styles: gerund (`processing-pdfs`), noun phrase (`github-pr-creation`), prefixed group (`github-pr-*`)

## Important rules

- **ALWAYS** write descriptions that include WHAT + WHEN triggers + capabilities
- **ALWAYS** keep SKILL.md under 500 lines, split to references when approaching
- **ALWAYS** reference bundled files from SKILL.md so Claude discovers them
- **NEVER** duplicate info between SKILL.md and reference files
- **NEVER** create wrapper scripts for single commands
- **NEVER** include extraneous files (README.md, CHANGELOG.md, INSTALLATION_GUIDE.md, QUICK_REFERENCE.md)
- **NEVER** explain things Claude already knows (standard libraries, common tools, basic patterns)

## References

- `references/official_best_practices.md` - Principles, anti-patterns, quality checklist, testing
- `references/skill_examples.md` - Concrete skill examples with new features