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:

Naming Rules

Good/Bad Examples:

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

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

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

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