skill

Files (31)

• SKILL-compact.md
• SKILL.md
• anthropic-best-practices.md · references/
• api-security.md · references/
• be-clear-and-direct.md · references/
• best-practices.md · references/
• claude-search-optimization.md · references/
• common-patterns.md · references/
• core-principles.md · references/
• executable-code.md · references/
• iteration-and-testing.md · references/
• official-spec.md · references/
• persuasion-principles.md · references/
• recommended-structure.md · references/
• skill-structure.md · references/
• testing-skills-with-subagents.md · references/
• using-scripts.md · references/
• using-templates.md · references/
• workflows-and-validation.md · references/
• router-skill.md · templates/
• simple-skill.md · templates/
• add-reference.md · workflows/
• add-script.md · workflows/
• add-template.md · workflows/
• add-workflow.md · workflows/
• audit-skill.md · workflows/
• create-domain-expertise-skill.md · workflows/
• create-new-skill.md · workflows/
• get-guidance.md · workflows/
• upgrade-to-router.md · workflows/
• verify-skill.md · workflows/

SKILL.md (first lines)

# Creating Skills & Commands

This skill teaches how to create effective Claude Code skills following the official specification. It combines spec-driven creation with TDD-adapted pressure testing.

## Commands and Skills Are Now The Same Thing

Custom slash commands have been merged into skills. A file at `.claude/commands/review.md` and a skill at `.claude/skills/review/SKILL.md` both create `/review` and work the same way. Existing `.claude/commands/` files keep working. Skills add optional features: a directory for supporting files, frontmatter to control invocation, and automatic context loading.

**If a skill and a command share the same name, the skill takes precedence.**

## When To Create What

**Use a command file** (`commands/name.md`) when:
- Simple, single-file workflow
- No supporting files needed
- Task-oriented action (deploy, commit, triage)

**Use a skill directory** (`skills/name/SKILL.md`) when:
- Need supporting reference files, scripts, or templates
- Background knowledge Claude should auto-load
- Complex enough to benefit from progressive disclosure

Both use identical YAML frontmatter and markdown content format.

## Standard Markdown Format

Use YAML frontmatter + markdown body with **standard markdown headings**. Keep it clean and direct.

```markdown
---
name: my-skill-name
description: What it does and when to use it
---

# My Skill Name

## Quick Start
Immediate actionable guidance...

## Instructions
Step-by-step procedures...

## Examples
Concrete usage examples...
```

## Frontmatter Reference

All fields are optional. Only `description` is recommended.

| Field | Required | Description |
|-------|----------|-------------|
| `name` | No | Display name. Lowercase letters, numbers, hyphens (max 64 chars). Defaults to directory name. |
| `description` | Recommended | What it does AND when to use it. Claude uses this for auto-discovery. Max 1024 chars. |
| `argument-hint` | No | Hint shown during autocomplete. Example: `[issue-number]` |
| `disable-model-invocation` | No | Set `true` to prevent Claude auto-loading. Use for manual workflows like `/deploy`, `/commit`. Default: `false`. |
| `user-invocable` | No | Set `false` to hide from `/` menu. Use for background knowledge. Default: `true`. |
| `allowed-tools` | No | Tools Claude can use without permission prompts. Example: `Read, Bash(git *)` |
| `model` | No | Model to use. Options: `haiku`, `sonnet`, `opus`. |
| `context` | No | Set `fork` to run in isolated subagent context. |
| `agent` | No | Subagent type when `context: fork`. Options: `Explore`, `Plan`, `general-purpose`, or custom agent name. |

### Invocation Control

| Frontmatter | User can invoke | Claude can invoke | When loaded |
|-------------|----------------|-------------------|-------------|
| (default) | Yes | Yes | Description always in context, full content loads when invoked |
| `disable-model-invocation: true` | Yes | No | Description not in context, loads only when user invokes |
| `user-invocable: false` | No | Yes | Description always in context, loads when relevant |

**Use `disable-model-invocation: true`** for workflows with side effects: `/deploy`, `/commit`, `/triage-prs`, `/send-slack-message`. You don't want Claude deciding to deploy because your code looks ready.

**Use `user-invocable: false`** for background knowledge that isn't a meaningful user action: coding conventions, domain context, legacy system docs.

## Dynamic Features

### Arguments

Use `$ARGUMENTS` placeholder for user input. If not present in content, arguments are appended automatically.

Access individual args: `$ARGUMENTS[0]` or shorthand `$0`, `$1`, `$2`.

### Dynamic Context Injection

The `` !`command` `` syntax runs shell commands before content is sent to Claude.

### Running in a Subagent

Add `context: fork` to run in isolation. The skill content becomes the subagent's prompt.

## Progressive Disclosure

Keep SKILL.md under 500 lines. Split detailed content into reference files:

```
my-skill/
├── SKILL.md           # Entry point (required, overview + navigation)
├── reference.md       # Detailed docs (loaded when needed)
├── examples.md        # Usage examples (loaded when needed)
└── scripts/
    └── helper.py      # Utility script (executed, not loaded)
```

Keep references **one level deep** from SKILL.md.

## What Would You Like To Do?

1. **Create new skill** — Build from scratch (Phase 1: Spec → Phase 2: TDD Test)
2. **Create new command** — Build a slash command
3. **Audit existing skill** — Check against best practices (use `/interskill:audit`)
4. **Add component** — Add workflow/reference/example
5. **Get guidance** — Understand skill design

## Creating a New Skill

### Phase 1: Spec-Driven Creation

Follow [workflows/create-new-skill.md](workflows/create-new-skill.md) for the full step-by-step process.

From mistakeknot/interskill, MIT.

More from mistakeknot/interskill