mirror of
https://github.com/zoriya/v10.git
synced 2026-08-16 02:45:09 +00:00
chore(claude): add /create-skill
This commit is contained in:
Rahim
@@ -20,6 +20,7 @@ Specialized knowledge for AI agents working on Video.js 10.
|
||||
| Reviewing branch changes | `/review-branch` |
|
||||
| Analyzing GitHub issues | `/gh-issue` |
|
||||
| Updating AI docs | `/claude-update` |
|
||||
| Creating new skills | `/create-skill` |
|
||||
|
||||
## Skills
|
||||
|
||||
@@ -30,6 +31,7 @@ Specialized knowledge for AI agents working on Video.js 10.
|
||||
| [claude-update](claude-update/SKILL.md) | Update CLAUDE.md and skills when introducing new patterns | No |
|
||||
| [commit-pr](commit-pr/SKILL.md) | Commit changes and create/update PRs with conventions | No |
|
||||
| [component](component/SKILL.md) | Build headless UI components — compound patterns, state, styling | Yes |
|
||||
| [create-skill](create-skill/SKILL.md) | Create new skills with proper structure and conventions | No |
|
||||
| [docs](docs/SKILL.md) | Write Video.js 10 documentation | Yes |
|
||||
| [gh-issue](gh-issue/SKILL.md) | Analyze GitHub issues and create implementation plans | No |
|
||||
| [git](git/SKILL.md) | Git workflow — commit messages, PRs, branch naming, scope inference | No |
|
||||
|
||||
@@ -0,0 +1,190 @@
|
||||
---
|
||||
name: create-skill
|
||||
description: >-
|
||||
Create new skills for Claude agents. Use when adding specialized knowledge,
|
||||
workflows, or commands. Guides through structure, frontmatter, and conventions.
|
||||
Triggers: "create skill", "new skill", "add skill", "write skill".
|
||||
allowed-tools: Bash(mkdir:*), Bash(ls:*), Glob, Grep, Read, Write, Edit, question
|
||||
context: fork
|
||||
---
|
||||
|
||||
# Create Skill
|
||||
|
||||
Create a new skill with proper structure and conventions.
|
||||
|
||||
## Usage
|
||||
|
||||
```
|
||||
/create-skill [name]
|
||||
```
|
||||
|
||||
- `name` (optional): Skill identifier. If omitted, will prompt interactively.
|
||||
|
||||
## Arguments
|
||||
|
||||
$ARGUMENTS
|
||||
|
||||
## When to Create a Skill
|
||||
|
||||
**Create a skill when:**
|
||||
|
||||
- Domain-specific knowledge that Claude doesn't inherently have
|
||||
- Multi-step workflows that benefit from procedural guidance
|
||||
- Automated commands that should run in isolated context
|
||||
- Patterns used repeatedly across conversations
|
||||
|
||||
**Don't create a skill when:**
|
||||
|
||||
- Cross-cutting convention (naming, utilities) → add to CLAUDE.md Code Rules
|
||||
- One-off task → just do it
|
||||
- Information Claude already knows well → unnecessary context bloat
|
||||
|
||||
**Decision tree:**
|
||||
|
||||
```
|
||||
Is this domain-specific knowledge?
|
||||
├─ No → Does it affect multiple domains?
|
||||
│ ├─ Yes → CLAUDE.md Code Rules
|
||||
│ └─ No → Probably don't need anything
|
||||
└─ Yes → Create a skill
|
||||
├─ Reference material for a domain? → Knowledge skill
|
||||
├─ Conventions and processes? → Workflow skill
|
||||
└─ Automated multi-step task? → Command skill
|
||||
```
|
||||
|
||||
## Skill Types
|
||||
|
||||
| Type | Characteristics | Examples |
|
||||
| ------------- | ------------------------------------------------------------ | ------------------------------------- |
|
||||
| **Knowledge** | Domain expertise, reference-heavy, may have review workflow | `api`, `component`, `aria`, `docs` |
|
||||
| **Workflow** | Conventions, processes, templates | `git`, `rfc` |
|
||||
| **Command** | Procedural steps, forked context, restricted tools | `commit-pr`, `gh-issue`, `review-branch` |
|
||||
|
||||
## Quick Reference
|
||||
|
||||
**Frontmatter (required):**
|
||||
|
||||
```yaml
|
||||
name: skill-name
|
||||
description: >-
|
||||
What it does. Use when X. Triggers: "phrase1", "phrase2".
|
||||
```
|
||||
|
||||
**Frontmatter (optional):**
|
||||
|
||||
```yaml
|
||||
context: fork # Isolated sub-agent context
|
||||
allowed-tools: Tool1, Tool2 # Restrict available tools
|
||||
agent: plan # Plan mode (no edits)
|
||||
disable-model-invocation: true # Prevent model calls
|
||||
```
|
||||
|
||||
**Structure options:**
|
||||
|
||||
```
|
||||
skill-name/
|
||||
├── SKILL.md # Always required
|
||||
├── references/ # Detailed content (load on demand)
|
||||
├── templates/ # Output templates
|
||||
└── review/ # Review workflow (if applicable)
|
||||
```
|
||||
|
||||
## Reference Material
|
||||
|
||||
| Topic | Load |
|
||||
| -------------------------------------------------- | --------------------------- |
|
||||
| Core principles (conciseness, progressive disclosure) | `references/principles.md` |
|
||||
| Full structure and frontmatter schema | `references/structure.md` |
|
||||
| Complete examples of each skill type | `references/patterns.md` |
|
||||
|
||||
## Your Tasks
|
||||
|
||||
### Step 1: Validate Need
|
||||
|
||||
Before creating, verify this should be a skill:
|
||||
|
||||
1. Check if similar skill exists: `ls .claude/skills/`
|
||||
2. Check if pattern belongs in CLAUDE.md instead
|
||||
3. If skill name provided, check for conflicts with existing skills
|
||||
|
||||
If the pattern is cross-cutting (affects all domains), suggest adding to CLAUDE.md Code Rules instead.
|
||||
|
||||
### Step 2: Gather Requirements
|
||||
|
||||
Ask the user (use `question` tool):
|
||||
|
||||
1. **Skill type**: Knowledge, Workflow, or Command?
|
||||
2. **Purpose**: What problem does this skill solve?
|
||||
3. **Triggers**: What phrases should activate this skill?
|
||||
4. **Scope**: What topics/tasks does it cover?
|
||||
5. **Review capability**: Does it need a review workflow?
|
||||
6. **Templates**: Does it need output templates?
|
||||
|
||||
### Step 3: Plan Structure
|
||||
|
||||
Based on requirements, determine:
|
||||
|
||||
- Skill name (kebab-case)
|
||||
- Which directories needed (`references/`, `templates/`, `review/`)
|
||||
- Reference file names and purposes
|
||||
|
||||
### Step 4: Create Skill
|
||||
|
||||
1. Create skill directory:
|
||||
|
||||
```bash
|
||||
mkdir -p .claude/skills/<skill-name>
|
||||
```
|
||||
|
||||
2. Create SKILL.md with:
|
||||
- Proper frontmatter (name, description, optional fields based on type)
|
||||
- Section headers with guidance comments
|
||||
- Reference table (if using references/)
|
||||
- Related Skills section
|
||||
|
||||
3. Create subdirectories if needed:
|
||||
|
||||
```bash
|
||||
mkdir -p .claude/skills/<skill-name>/references
|
||||
mkdir -p .claude/skills/<skill-name>/templates
|
||||
mkdir -p .claude/skills/<skill-name>/review
|
||||
```
|
||||
|
||||
4. Create placeholder reference files with:
|
||||
- Clear purpose header
|
||||
- Section structure
|
||||
- TODO markers for content
|
||||
|
||||
### Step 5: Update README
|
||||
|
||||
Add the new skill to `.claude/skills/README.md`:
|
||||
|
||||
1. Add to "Quick Reference" table (if it's a workflow)
|
||||
2. Add to "Skills" table with purpose and review status
|
||||
|
||||
### Step 6: Report
|
||||
|
||||
Output:
|
||||
|
||||
- Created file structure
|
||||
- Next steps (fill in content, test triggers)
|
||||
- Reminder to load `principles.md` when writing content
|
||||
|
||||
## What NOT to Include
|
||||
|
||||
Skills should only contain what Claude needs to do the job:
|
||||
|
||||
- No README.md, INSTALLATION_GUIDE.md, CHANGELOG.md
|
||||
- No setup and testing procedures
|
||||
- No user-facing documentation about the skill
|
||||
- No duplicate information (lives in SKILL.md OR references, not both)
|
||||
|
||||
## After Creating
|
||||
|
||||
Checklist:
|
||||
|
||||
- [ ] Fill in SKILL.md content
|
||||
- [ ] Write reference files (if any)
|
||||
- [ ] Test trigger phrases work
|
||||
- [ ] Verify skill loads correctly
|
||||
- [ ] Update README.md tables
|
||||
@@ -0,0 +1,276 @@
|
||||
# Skill Patterns
|
||||
|
||||
Complete examples of each skill type.
|
||||
|
||||
## Knowledge Skill Example
|
||||
|
||||
Based on `component` skill — domain expertise with review capability.
|
||||
|
||||
```markdown
|
||||
---
|
||||
name: component
|
||||
description: >-
|
||||
Build accessible, headless UI components with modern architecture patterns.
|
||||
Use when creating component libraries, design systems, or reusable UI primitives.
|
||||
Handles compound components, state management, accessibility, styling hooks.
|
||||
Includes Lit (controllers, ReactiveElement) and React (hooks, context) patterns.
|
||||
---
|
||||
|
||||
# Component Architecture Patterns
|
||||
|
||||
Build accessible, headless UI components using proven patterns.
|
||||
|
||||
**Primary sources:**
|
||||
- [Base UI Handbook](https://base-ui.com/react/handbook/overview)
|
||||
- [Ark UI](https://ark-ui.com/)
|
||||
|
||||
---
|
||||
|
||||
## Core Principles
|
||||
|
||||
1. **Headless over styled** — Separate behavior from presentation
|
||||
2. **Compound over monolithic** — Small composable parts
|
||||
3. **Accessible by default** — ARIA, keyboard, focus built-in
|
||||
|
||||
---
|
||||
|
||||
## Pattern 1: Compound Components
|
||||
|
||||
**What:** Components as related parts sharing state through context.
|
||||
|
||||
**Why:** Declarative, independently styleable, maps to ARIA roles.
|
||||
|
||||
---
|
||||
|
||||
## Reference Files
|
||||
|
||||
| File | Contents |
|
||||
|------|----------|
|
||||
| [lit.md](references/lit.md) | Lit controllers, mixins |
|
||||
| [react.md](references/react.md) | React hooks, context |
|
||||
| [props.md](references/props.md) | Prop naming conventions |
|
||||
|
||||
## Review
|
||||
|
||||
For component reviews, load `review/workflow.md`.
|
||||
|
||||
## Related Skills
|
||||
|
||||
| Need | Use |
|
||||
|------|-----|
|
||||
| Accessibility | `aria` skill |
|
||||
| API design | `api` skill |
|
||||
```
|
||||
|
||||
**Key characteristics:**
|
||||
|
||||
- Rich description with multiple trigger phrases
|
||||
- Quick reference section with core principles
|
||||
- Reference table for detailed content
|
||||
- Review section linking to workflow
|
||||
- Related skills for cross-domain work
|
||||
|
||||
---
|
||||
|
||||
## Workflow Skill Example
|
||||
|
||||
Based on `git` skill — conventions and processes.
|
||||
|
||||
```markdown
|
||||
---
|
||||
name: git
|
||||
description: >-
|
||||
Git workflow conventions for Video.js 10. Commit messages, PR descriptions,
|
||||
branch naming, and scope inference. Triggers: "commit", "push", "create PR",
|
||||
"conventional commit", "branch name".
|
||||
context: fork
|
||||
---
|
||||
|
||||
# Git
|
||||
|
||||
Git workflow conventions for Video.js 10.
|
||||
|
||||
## Reference Material
|
||||
|
||||
| Task | Load |
|
||||
|------|------|
|
||||
| Writing commits | `references/commit.md` |
|
||||
| Inferring scope | `references/scope.md` |
|
||||
| Creating PRs | `references/pr.md` |
|
||||
| Naming branches | `references/branch.md` |
|
||||
|
||||
## Quick Reference
|
||||
|
||||
**Commit:** `type(scope): lowercase description`
|
||||
|
||||
**Branch:** `type/short-description`
|
||||
|
||||
**PR Title:** Same as commit
|
||||
|
||||
## Process
|
||||
|
||||
1. Create branch following naming convention
|
||||
2. Make changes
|
||||
3. Commit with conventional message
|
||||
4. Push and create PR
|
||||
```
|
||||
|
||||
**Key characteristics:**
|
||||
|
||||
- `context: fork` for isolated execution
|
||||
- Reference table organized by task
|
||||
- Quick reference with condensed conventions
|
||||
- Simple linear process
|
||||
|
||||
---
|
||||
|
||||
## Command Skill Example
|
||||
|
||||
Based on `commit-pr` skill — automated multi-step task.
|
||||
|
||||
```markdown
|
||||
---
|
||||
name: commit-pr
|
||||
description: >-
|
||||
Commit all changes and create or update a PR following project conventions.
|
||||
Triggers: "commit and pr", "push changes", "create pull request".
|
||||
allowed-tools: Bash(git:*), Bash(gh:*), Glob, Grep, Read, question, mcp__github__*
|
||||
context: fork
|
||||
---
|
||||
|
||||
# Commit & PR
|
||||
|
||||
Stage all changes, create a conventional commit, and open a pull request.
|
||||
|
||||
## Usage
|
||||
|
||||
\`\`\`
|
||||
/commit-pr [refs]
|
||||
\`\`\`
|
||||
|
||||
- `refs` (optional): Issue/PR references (e.g., `#123`, `fixes #456`)
|
||||
|
||||
## Arguments
|
||||
|
||||
$ARGUMENTS
|
||||
|
||||
## Conventions
|
||||
|
||||
Load the `git` skill for commit and PR conventions.
|
||||
|
||||
## Your Tasks
|
||||
|
||||
### Step 1: Load Conventions
|
||||
|
||||
Load the `git` skill.
|
||||
|
||||
### Step 2: Analyze Changes
|
||||
|
||||
1. Run `git status`
|
||||
2. Run `git diff --staged` and `git diff`
|
||||
3. Read files if needed for context
|
||||
|
||||
### Step 3: Determine Commit Type and Scope
|
||||
|
||||
Based on changes and `git` skill conventions.
|
||||
|
||||
### Step 4: Create Commit
|
||||
|
||||
1. Stage: `git add -A`
|
||||
2. Commit: `git commit -m "type(scope): description"`
|
||||
|
||||
### Step 5: Push and Create/Update PR
|
||||
|
||||
1. Push: `git push -u origin HEAD`
|
||||
2. Check for existing PR
|
||||
3. Create or update as needed
|
||||
|
||||
### Step 6: Report
|
||||
|
||||
Output PR URL and status.
|
||||
|
||||
## Important
|
||||
|
||||
- Always stage ALL changes
|
||||
- Check for existing PR before creating
|
||||
- Follow PR description principles
|
||||
```
|
||||
|
||||
**Key characteristics:**
|
||||
|
||||
- `allowed-tools` restricts to git/GitHub tools
|
||||
- `context: fork` for isolated execution
|
||||
- `$ARGUMENTS` placeholder for user input
|
||||
- Step-by-step "Your Tasks" section
|
||||
- Loads other skills for domain knowledge
|
||||
- "Important" section with constraints
|
||||
|
||||
---
|
||||
|
||||
## Review Workflow Pattern
|
||||
|
||||
Structure for skills with review capability:
|
||||
|
||||
```
|
||||
skill/
|
||||
└── review/
|
||||
├── workflow.md # Main entry point
|
||||
├── checklist.md # Quick checklist
|
||||
├── templates.md # Output formats
|
||||
└── agents.md # Sub-agent prompts (optional)
|
||||
```
|
||||
|
||||
### workflow.md Template
|
||||
|
||||
```markdown
|
||||
# Skill Review Workflow
|
||||
|
||||
Review X for quality and correctness.
|
||||
|
||||
## When to Use
|
||||
|
||||
- Before merging PRs that touch X
|
||||
- When auditing existing X
|
||||
- When requested by user
|
||||
|
||||
## Process
|
||||
|
||||
### Single-Agent Review
|
||||
|
||||
1. Load checklist from `checklist.md`
|
||||
2. Review against each item
|
||||
3. Output issues using format from `templates.md`
|
||||
|
||||
### Multi-Agent Review (Large Scope)
|
||||
|
||||
1. Load agent prompts from `agents.md`
|
||||
2. Spawn agents for each domain
|
||||
3. Merge findings
|
||||
4. Output consolidated report
|
||||
|
||||
## Severity Levels
|
||||
|
||||
| Level | Description |
|
||||
|-------|-------------|
|
||||
| Critical | Must fix before merge |
|
||||
| Warning | Should fix, may defer |
|
||||
| Note | Suggestion for improvement |
|
||||
```
|
||||
|
||||
### checklist.md Template
|
||||
|
||||
```markdown
|
||||
# Skill Review Checklist
|
||||
|
||||
Quick checklist for single-agent review.
|
||||
|
||||
## Category A
|
||||
|
||||
- [ ] Check item 1
|
||||
- [ ] Check item 2
|
||||
|
||||
## Category B
|
||||
|
||||
- [ ] Check item 3
|
||||
- [ ] Check item 4
|
||||
```
|
||||
@@ -0,0 +1,134 @@
|
||||
# Skill Principles
|
||||
|
||||
Core principles for writing effective skills.
|
||||
|
||||
## Concise is Key
|
||||
|
||||
The context window is a shared resource. Skills compete with system prompts, conversation history, and user requests.
|
||||
|
||||
**Guidelines:**
|
||||
|
||||
- Claude is already smart — only add knowledge Claude doesn't have
|
||||
- Challenge each paragraph: "Does this justify its token cost?"
|
||||
- Prefer concise examples over verbose explanations
|
||||
- If Claude can figure it out, don't explain it
|
||||
|
||||
**Example:**
|
||||
|
||||
```markdown
|
||||
// ❌ Verbose
|
||||
In order to create a new component, you'll need to first understand
|
||||
the component architecture patterns. Components in this codebase follow
|
||||
the compound component pattern, which means...
|
||||
|
||||
// ✅ Concise
|
||||
Components use compound pattern. See `component` skill for details.
|
||||
```
|
||||
|
||||
## Degrees of Freedom
|
||||
|
||||
Match specificity to task fragility:
|
||||
|
||||
| Freedom | When to Use | Format |
|
||||
| ---------- | ---------------------------------------------- | ------------------------------------- |
|
||||
| **High** | Multiple valid approaches, context-dependent | Text instructions |
|
||||
| **Medium** | Preferred pattern exists, some variation OK | Pseudocode, templates with parameters |
|
||||
| **Low** | Fragile operations, consistency critical | Specific steps, exact commands |
|
||||
|
||||
**Metaphor:** A narrow bridge needs guardrails (low freedom). An open field allows many routes (high freedom).
|
||||
|
||||
**Examples:**
|
||||
|
||||
```markdown
|
||||
// High freedom — many valid approaches
|
||||
Write documentation following the tone and style guidelines.
|
||||
|
||||
// Medium freedom — preferred pattern
|
||||
Use this template structure:
|
||||
## Overview
|
||||
## Usage
|
||||
## API Reference
|
||||
|
||||
// Low freedom — exact sequence required
|
||||
1. Run `git add -A`
|
||||
2. Run `git commit -m "type(scope): message"`
|
||||
3. Run `git push -u origin HEAD`
|
||||
```
|
||||
|
||||
## Progressive Disclosure
|
||||
|
||||
Skills use a three-level loading system:
|
||||
|
||||
| Level | What | When Loaded | Target Size |
|
||||
| ----- | -------------------------------- | -------------------- | ------------ |
|
||||
| 1 | Metadata (name + description) | Always | ~100 words |
|
||||
| 2 | SKILL.md body | When skill triggers | <500 lines |
|
||||
| 3 | references/ files | On demand | Unlimited |
|
||||
|
||||
**Key insight:** Description is the ONLY thing Claude sees before deciding to load a skill. All "when to use" info MUST be in the description, not the body.
|
||||
|
||||
## Progressive Disclosure Patterns
|
||||
|
||||
### Pattern 1: High-Level Guide with References
|
||||
|
||||
Keep SKILL.md focused, link to details:
|
||||
|
||||
```markdown
|
||||
## Quick Reference
|
||||
|
||||
Create components using compound pattern with data attributes for styling.
|
||||
|
||||
## Detailed Guides
|
||||
|
||||
- **Props conventions**: See [props.md](references/props.md)
|
||||
- **Styling patterns**: See [styling.md](references/styling.md)
|
||||
- **Accessibility**: See [aria.md](references/aria.md)
|
||||
```
|
||||
|
||||
### Pattern 2: Domain-Specific Organization
|
||||
|
||||
Organize by domain to avoid loading irrelevant content:
|
||||
|
||||
```
|
||||
skill/
|
||||
├── SKILL.md (overview + navigation)
|
||||
└── references/
|
||||
├── react.md # React-specific patterns
|
||||
├── lit.md # Lit-specific patterns
|
||||
└── vanilla.md # Vanilla JS patterns
|
||||
```
|
||||
|
||||
When user asks about React, Claude only loads `react.md`.
|
||||
|
||||
### Pattern 3: Conditional Details
|
||||
|
||||
Show basics, link to advanced:
|
||||
|
||||
```markdown
|
||||
## Creating Components
|
||||
|
||||
Use compound pattern with Root, Trigger, and Content parts.
|
||||
|
||||
**For animations**: See [animation.md](references/animation.md)
|
||||
**For collections**: See [collection.md](references/collection.md)
|
||||
```
|
||||
|
||||
## Information Placement
|
||||
|
||||
Information lives in ONE place:
|
||||
|
||||
| Content Type | Location |
|
||||
| ------------------------------------ | ------------ |
|
||||
| Quick reference, process overview | SKILL.md |
|
||||
| Detailed patterns, examples, schemas | references/ |
|
||||
| Output formats, boilerplate | templates/ |
|
||||
| Review checklists, agent prompts | review/ |
|
||||
|
||||
**Anti-pattern:** Duplicating information between SKILL.md and references. This wastes tokens and creates maintenance burden.
|
||||
|
||||
## Reference File Guidelines
|
||||
|
||||
- Keep references one level deep from SKILL.md
|
||||
- Files >100 lines should have a table of contents
|
||||
- Structure by domain or variant, not by "type of content"
|
||||
- Include code examples — they're often more concise than prose
|
||||
@@ -0,0 +1,240 @@
|
||||
# Skill Structure
|
||||
|
||||
Complete reference for skill structure and frontmatter.
|
||||
|
||||
## Frontmatter Schema
|
||||
|
||||
### Required Fields
|
||||
|
||||
| Field | Type | Description |
|
||||
| ------------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| `name` | string | Skill identifier. Used with `skill` tool. Kebab-case, lowercase. |
|
||||
| `description` | string | When to use and trigger phrases. This is the PRIMARY mechanism for skill selection — Claude only sees this before deciding to load. |
|
||||
|
||||
### Optional Fields
|
||||
|
||||
| Field | Type | Default | Description |
|
||||
| -------------------------- | --------- | ------- | ----------------------------------------------------------------------------------------------------- |
|
||||
| `context` | `fork` | — | Creates isolated sub-agent context. Use for command skills that run autonomously. |
|
||||
| `allowed-tools` | string | all | Restricts available tools. Format: `Tool1, Tool2, Bash(cmd:*)`. Use for command skills. |
|
||||
| `agent` | `plan` | — | Sets agent to plan/research mode. Agent cannot make edits, only read and analyze. |
|
||||
| `disable-model-invocation` | boolean | false | Prevents skill from invoking other models. Use for skills that should only provide guidance. |
|
||||
|
||||
### Description Best Practices
|
||||
|
||||
```yaml
|
||||
# ❌ Too brief — won't trigger correctly
|
||||
description: Component patterns
|
||||
|
||||
# ❌ Triggers in body — won't work (body loads AFTER triggering)
|
||||
description: Component patterns
|
||||
---
|
||||
## When to Use
|
||||
Use this skill when building components...
|
||||
|
||||
# ✅ Complete — triggers included
|
||||
description: >-
|
||||
Build accessible, headless UI components with modern architecture patterns.
|
||||
Use when creating component libraries, design systems, or reusable UI primitives.
|
||||
Handles compound components, state management, accessibility, styling hooks.
|
||||
Triggers: "create component", "component architecture", "compound component".
|
||||
```
|
||||
|
||||
## Directory Structure
|
||||
|
||||
### Minimal (Command/Simple Workflow)
|
||||
|
||||
```
|
||||
skill-name/
|
||||
└── SKILL.md
|
||||
```
|
||||
|
||||
Use for: Simple commands, straightforward workflows.
|
||||
|
||||
Examples: `commit-pr`, `claude-update`
|
||||
|
||||
### With References (Knowledge/Complex Workflow)
|
||||
|
||||
```
|
||||
skill-name/
|
||||
├── SKILL.md
|
||||
└── references/
|
||||
├── topic-a.md
|
||||
├── topic-b.md
|
||||
└── topic-c.md
|
||||
```
|
||||
|
||||
Use for: Domain expertise, detailed patterns, multiple topics.
|
||||
|
||||
Examples: `api`, `component`, `aria`
|
||||
|
||||
### With Templates (Output-Focused)
|
||||
|
||||
```
|
||||
skill-name/
|
||||
├── SKILL.md
|
||||
├── references/
|
||||
└── templates/
|
||||
├── output-type-a.md
|
||||
├── output-type-b.md
|
||||
└── output-type-c.md
|
||||
```
|
||||
|
||||
Use for: Skills that produce structured outputs (docs, RFCs, etc.).
|
||||
|
||||
Examples: `docs`, `rfc`
|
||||
|
||||
### With Review Capability
|
||||
|
||||
```
|
||||
skill-name/
|
||||
├── SKILL.md
|
||||
├── references/
|
||||
└── review/
|
||||
├── workflow.md # Review process, when to use
|
||||
├── checklist.md # Quick single-agent checklist
|
||||
├── templates.md # Output formats for issues/reports
|
||||
└── agents.md # Sub-agent prompts (if multi-agent)
|
||||
```
|
||||
|
||||
Use for: Skills that can review existing code/content.
|
||||
|
||||
Examples: `api`, `component`, `aria`, `docs`
|
||||
|
||||
## SKILL.md Structure
|
||||
|
||||
### Knowledge Skill Template
|
||||
|
||||
```markdown
|
||||
---
|
||||
name: skill-name
|
||||
description: >-
|
||||
Domain description. Use when X, Y, Z.
|
||||
Triggers: "phrase1", "phrase2", "phrase3".
|
||||
---
|
||||
|
||||
# Skill Title
|
||||
|
||||
Brief overview (1-2 sentences).
|
||||
|
||||
## Quick Reference
|
||||
|
||||
Most important patterns/rules in condensed form.
|
||||
|
||||
## Reference Files
|
||||
|
||||
| File | Contents |
|
||||
|------|----------|
|
||||
| [references/topic-a.md](references/topic-a.md) | Description |
|
||||
| [references/topic-b.md](references/topic-b.md) | Description |
|
||||
|
||||
## Review
|
||||
|
||||
For reviewing X, load `review/workflow.md`.
|
||||
|
||||
## Related Skills
|
||||
|
||||
| Need | Use |
|
||||
|------|-----|
|
||||
| Related domain | `other-skill` skill |
|
||||
```
|
||||
|
||||
### Command Skill Template
|
||||
|
||||
```markdown
|
||||
---
|
||||
name: skill-name
|
||||
description: >-
|
||||
What command does. Triggers: "phrase1", "phrase2".
|
||||
allowed-tools: Tool1, Tool2, Bash(cmd:*)
|
||||
context: fork
|
||||
---
|
||||
|
||||
# Command Name
|
||||
|
||||
Brief description of what the command does.
|
||||
|
||||
## Usage
|
||||
|
||||
\`\`\`
|
||||
/skill-name [args]
|
||||
\`\`\`
|
||||
|
||||
- `arg` (optional/required): Description
|
||||
|
||||
## Arguments
|
||||
|
||||
$ARGUMENTS
|
||||
|
||||
## Your Tasks
|
||||
|
||||
### Step 1: Task Name
|
||||
|
||||
Instructions...
|
||||
|
||||
### Step 2: Task Name
|
||||
|
||||
Instructions...
|
||||
|
||||
## Important
|
||||
|
||||
- Key constraint 1
|
||||
- Key constraint 2
|
||||
```
|
||||
|
||||
### Workflow Skill Template
|
||||
|
||||
```markdown
|
||||
---
|
||||
name: skill-name
|
||||
description: >-
|
||||
Workflow description. Triggers: "phrase1", "phrase2".
|
||||
context: fork
|
||||
---
|
||||
|
||||
# Workflow Name
|
||||
|
||||
Brief overview.
|
||||
|
||||
## Reference Material
|
||||
|
||||
| Task | Load |
|
||||
|------|------|
|
||||
| Task type A | `references/a.md` |
|
||||
| Task type B | `references/b.md` |
|
||||
|
||||
## Quick Reference
|
||||
|
||||
Key conventions in condensed form.
|
||||
|
||||
## Process
|
||||
|
||||
1. Step one
|
||||
2. Step two
|
||||
3. Step three
|
||||
```
|
||||
|
||||
## Naming Conventions
|
||||
|
||||
| Element | Convention | Example |
|
||||
| ---------------- | ----------- | -------------------- |
|
||||
| Skill directory | kebab-case | `create-skill/` |
|
||||
| Skill name | kebab-case | `create-skill` |
|
||||
| Reference files | kebab-case | `anti-patterns.md` |
|
||||
| Template files | kebab-case | `component-page.md` |
|
||||
|
||||
## Tool Restriction Patterns
|
||||
|
||||
```yaml
|
||||
# Git and GitHub only
|
||||
allowed-tools: Bash(git:*), Bash(gh:*), Glob, Grep, Read, mcp__github__*
|
||||
|
||||
# Read-only exploration
|
||||
allowed-tools: Glob, Grep, Read
|
||||
|
||||
# File creation allowed
|
||||
allowed-tools: Bash(mkdir:*), Glob, Grep, Read, Write, Edit
|
||||
|
||||
# With user interaction
|
||||
allowed-tools: Bash(git:*), Glob, Grep, Read, question
|
||||
```
|
||||
Reference in New Issue
Block a user