Agent Skills: Skill Structure

Skill Structure

Commands and Skills Are Merged

Custom slash commands and skills are the same thing. A file at .claude/commands/review.md and a skill at .claude/skills/review/SKILL.md both create /review. Existing .claude/commands/ files keep working. Skills add: a directory for supporting files, frontmatter to control invocation, and automatic context loading.

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

When to use which:

| Type | When | |------|------| | Command file (commands/name.md) | Simple single-file workflow, no supporting files | | Skill directory (skills/name/SKILL.md) | Needs references, background knowledge, or progressive disclosure |

Naming Rules

| Rule | Example | |------|---------| | Format | kebab-case, lowercase, 1-64 chars | | Pattern | ^[a-z][a-z0-9]*(-[a-z0-9]+)*$ | | Must match | Directory name exactly |

Good/Bad Examples:

| Good | Bad | Why | |------|-----|-----| | stimulus-coder | MySkill | Uppercase not allowed | | tdd-workflow | skill_helper | Underscores not allowed | | pdf-processing | -invalid | Can't start with hyphen | | seo-content | skill--bad | No consecutive hyphens |

Directory Structure

Flat Structure (most skills)

plugins/majestic-rails/skills/stimulus-coder/SKILL.md
-> name: stimulus-coder
-> invoked as: /majestic-rails:stimulus-coder

Nested Structure (categorized skills)

plugins/majestic-company/skills/ceo/strategic-planning/SKILL.md
-> name: strategic-planning
-> invoked as: /majestic-company:ceo:strategic-planning

Key Points:

• The name field is ONLY the final skill name (not the full path)
• Directory name must match name exactly
• Use nesting to group related skills (ceo/, fundraising/, research/)

Progressive Disclosure

For complex skills, split into multiple files:

my-skill/
+-- SKILL.md (overview, <500 lines)
+-- references/
|   +-- patterns.md (detailed patterns)
|   +-- examples.md (extended examples)
+-- scripts/
    +-- helper.py (utility scripts)

Rules:

• References one level deep only (SKILL.md to reference.md, not deeper)
• Scripts execute without loading into context
• Keep SKILL.md focused on navigation and core content
• Subdirectories only: scripts/, references/, assets/

Frontmatter

Core Fields

---
name: skill-name              # Matches directory, defaults to dir name if omitted
description: What it does...  # Recommended, max 1024 chars
allowed-tools: Read Bash      # Optional, space-delimited
---

All Fields Reference

| Field | Required | Description | |-------|----------|-------------| | name | No | Lowercase letters, numbers, hyphens (max 64 chars). Defaults to directory name. | | description | Recommended | What it does AND when to use it. Max 1024 chars. | | argument-hint | No | Hint during autocomplete. Example: [issue-number] | | disable-model-invocation | No | true = Claude cannot auto-load. For manual workflows. Default: false | | user-invocable | No | false = hidden from / menu. For background knowledge. Default: true | | allowed-tools | No | Tools without permission prompts. Example: Read, Bash(git *) | | model | No | haiku, sonnet, or opus | | context | No | fork to run in isolated subagent context | | agent | No | Subagent type when context: fork: Explore, Plan, general-purpose, or custom |

Description Template

[What it does]. Use when [trigger contexts]. Triggers on [specific keywords].

Rules:

• Max 1024 characters
• Third person ("Processes..." not "I process...")
• Include trigger keywords users would naturally say

Invocation Control

| Frontmatter | User can invoke | Claude can invoke | When loaded | |-------------|----------------|-------------------|-------------| | (default) | Yes | Yes | Description always in context, full content on invocation | | user-invocable: false | No | Yes | Description always in context, loads when relevant |

Decision guide:

• Background knowledge (conventions, domain context) -> user-invocable: false
• Everything else -> defaults (both user and model can invoke)

Note: Avoid disable-model-invocation: true. Commands/skills with side effects should use confirmation steps (AskUserQuestion) rather than blocking model invocation entirely.

Dynamic Features

Arguments

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

---
name: fix-issue
---
Fix GitHub issue $ARGUMENTS following our coding standards.

Individual args: $ARGUMENTS[0] or shorthand $0, $1, $2.

Dynamic Context Injection

The !`command` syntax runs shell commands before content reaches Claude:

## Context
- Current branch: !`git branch --show-current`
- PR diff: !`gh pr diff`

Commands execute immediately; output replaces the placeholder.

Subagent Execution

Add context: fork to run in isolation (no conversation history):

---
name: deep-research
description: Research a topic thoroughly
context: fork
agent: Explore
---
Research $ARGUMENTS thoroughly...

Tool Access

| Tools Needed | Example Use Case | |--------------|------------------| | Read, Grep, Glob | Search codebase for patterns | | Bash(git *) | Git operations only | | Bash(gh *) | GitHub CLI operations | | WebFetch | Fetch external documentation | | None | Pure knowledge/guidance |

Limits

• SKILL.md: Max 500 lines
• Name: Max 64 characters
• Description: Max 1024 characters

Validation Checklist

• [ ] Name matches directory name exactly
• [ ] Name follows pattern ^[a-z][a-z0-9]*(-[a-z0-9]+)*$
• [ ] Description under 1024 chars with trigger keywords
• [ ] Uses standard markdown headings (not XML tags)
• [ ] SKILL.md under 500 lines
• [ ] Uses AskUserQuestion for confirmation if skill has side effects
• [ ] allowed-tools set if specific tools needed
• [ ] No persona statements or attribution
• [ ] Subdirectories only: scripts/, references/, assets/
• [ ] Tested with real usage