Reduce context token usage by 79% — fix silent component exclusion (#161)
* Update create-agent-skills to match 2026 official docs, add /triage-prs command - Rewrite SKILL.md to document that commands and skills are now merged - Add new frontmatter fields: disable-model-invocation, user-invocable, context, agent - Add invocation control table and dynamic context injection docs - Fix skill-structure.md: was incorrectly recommending XML tags over markdown headings - Update official-spec.md with complete 2026 specification - Add local /triage-prs command for PR triage workflow - Add PR triage plan document Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com> * [2.31.0] Reduce context token usage by 79%, include recent community contributions The plugin was consuming 316% of Claude Code's description character budget (~50,500 chars vs 16,000 limit), causing components to be silently excluded. Now at 65% (~10,400 chars) with all components visible. Changes: - Trim all 29 agent descriptions (move examples to body) - Add disable-model-invocation to 18 manual commands - Add disable-model-invocation to 6 manual skills - Include recent community contributions in changelog - Fix component counts (29 agents, 24 commands, 18 skills) Contributors: @trevin, @terryli, @robertomello, @zacwilliams, @aarnikoskela, @samxie, @davidalley Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com> * Fix: keep disable-model-invocation off commands called by /lfg, rename xcode-test - Remove disable-model-invocation from test-browser, feature-video, resolve_todo_parallel — these are called programmatically by /lfg and /slfg - Rename xcode-test to test-xcode to match test-browser naming convention Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com> * Fix: keep git-worktree skill auto-invocable (used by /workflows:work) Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com> * feat(converter): support disable-model-invocation frontmatter Parse disable-model-invocation from command and skill frontmatter. Commands/skills with this flag are excluded from OpenCode command maps and Codex prompt/skill generation, matching Claude Code behavior where these components are user-only invocable. Bump converter version to 0.3.0. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com> --------- Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>
This commit is contained in:
Kieran Klaassen
@@ -1,6 +1,7 @@
|
||||
---
|
||||
name: compound-docs
|
||||
description: Capture solved problems as categorized documentation with YAML frontmatter for fast lookup
|
||||
disable-model-invocation: true
|
||||
allowed-tools:
|
||||
- Read # Parse conversation context
|
||||
- Write # Create resolution docs
|
||||
|
||||
@@ -1,21 +1,35 @@
|
||||
---
|
||||
name: creating-agent-skills
|
||||
description: Expert guidance for creating, writing, and refining Claude Code Skills. Use when working with SKILL.md files, authoring new skills, improving existing skills, or understanding skill structure and best practices.
|
||||
name: create-agent-skills
|
||||
description: Expert guidance for creating Claude Code skills and slash commands. Use when working with SKILL.md files, authoring new skills, improving existing skills, creating slash commands, or understanding skill structure and best practices.
|
||||
---
|
||||
|
||||
# Creating Agent Skills
|
||||
# Creating Skills & Commands
|
||||
|
||||
This skill teaches how to create effective Claude Code Skills following Anthropic's official specification.
|
||||
This skill teaches how to create effective Claude Code skills following the official specification from [code.claude.com/docs/en/skills](https://code.claude.com/docs/en/skills).
|
||||
|
||||
## Core Principles
|
||||
## Commands and Skills Are Now The Same Thing
|
||||
|
||||
### 1. Skills Are Prompts
|
||||
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.
|
||||
|
||||
All prompting best practices apply. Be clear, be direct. Assume Claude is smart - only add context Claude doesn't have.
|
||||
**If a skill and a command share the same name, the skill takes precedence.**
|
||||
|
||||
### 2. Standard Markdown Format
|
||||
## When To Create What
|
||||
|
||||
Use YAML frontmatter + markdown body. **No XML tags** - use standard markdown headings.
|
||||
**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
|
||||
---
|
||||
@@ -35,25 +49,113 @@ Step-by-step procedures...
|
||||
Concrete usage examples...
|
||||
```
|
||||
|
||||
### 3. Progressive Disclosure
|
||||
## Frontmatter Reference
|
||||
|
||||
Keep SKILL.md under 500 lines. Split detailed content into reference files. Load only what's needed.
|
||||
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.
|
||||
|
||||
```yaml
|
||||
---
|
||||
name: fix-issue
|
||||
description: Fix a GitHub issue
|
||||
disable-model-invocation: true
|
||||
---
|
||||
|
||||
Fix GitHub issue $ARGUMENTS following our coding standards.
|
||||
```
|
||||
|
||||
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:
|
||||
|
||||
```yaml
|
||||
---
|
||||
name: pr-summary
|
||||
description: Summarize changes in a pull request
|
||||
context: fork
|
||||
agent: Explore
|
||||
---
|
||||
|
||||
## Context
|
||||
- PR diff: !`gh pr diff`
|
||||
- Changed files: !`gh pr diff --name-only`
|
||||
|
||||
Summarize this pull request...
|
||||
```
|
||||
|
||||
### Running in a Subagent
|
||||
|
||||
Add `context: fork` to run in isolation. The skill content becomes the subagent's prompt. It won't have conversation history.
|
||||
|
||||
```yaml
|
||||
---
|
||||
name: deep-research
|
||||
description: Research a topic thoroughly
|
||||
context: fork
|
||||
agent: Explore
|
||||
---
|
||||
|
||||
Research $ARGUMENTS thoroughly:
|
||||
1. Find relevant files
|
||||
2. Analyze the code
|
||||
3. Summarize findings
|
||||
```
|
||||
|
||||
## Progressive Disclosure
|
||||
|
||||
Keep SKILL.md under 500 lines. Split detailed content into reference files:
|
||||
|
||||
```
|
||||
my-skill/
|
||||
├── SKILL.md # Entry point (required)
|
||||
├── reference.md # Detailed docs (loaded when needed)
|
||||
├── examples.md # Usage examples
|
||||
└── scripts/ # Utility scripts (executed, not loaded)
|
||||
├── 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)
|
||||
```
|
||||
|
||||
### 4. Effective Descriptions
|
||||
Link from SKILL.md: `For API details, see [reference.md](reference.md).`
|
||||
|
||||
The description field enables skill discovery. Include both what the skill does AND when to use it. Write in third person.
|
||||
Keep references **one level deep** from SKILL.md. Avoid nested chains.
|
||||
|
||||
## Effective Descriptions
|
||||
|
||||
The description enables skill discovery. Include both **what** it does and **when** to use it.
|
||||
|
||||
**Good:**
|
||||
```yaml
|
||||
description: Extracts text and tables from PDF files, fills forms, merges documents. Use when working with PDF files or when the user mentions PDFs, forms, or document extraction.
|
||||
description: Extract text and tables from PDF files, fill forms, merge documents. Use when working with PDF files or when the user mentions PDFs, forms, or document extraction.
|
||||
```
|
||||
|
||||
**Bad:**
|
||||
@@ -61,239 +163,113 @@ description: Extracts text and tables from PDF files, fills forms, merges docume
|
||||
description: Helps with documents
|
||||
```
|
||||
|
||||
## Skill Structure
|
||||
|
||||
### Required Frontmatter
|
||||
|
||||
| Field | Required | Max Length | Description |
|
||||
|-------|----------|------------|-------------|
|
||||
| `name` | Yes | 64 chars | Lowercase letters, numbers, hyphens only |
|
||||
| `description` | Yes | 1024 chars | What it does AND when to use it |
|
||||
| `allowed-tools` | No | - | Tools Claude can use without asking |
|
||||
| `model` | No | - | Specific model to use |
|
||||
|
||||
### Naming Conventions
|
||||
|
||||
Use **gerund form** (verb + -ing) for skill names:
|
||||
|
||||
- `processing-pdfs`
|
||||
- `analyzing-spreadsheets`
|
||||
- `generating-commit-messages`
|
||||
- `reviewing-code`
|
||||
|
||||
Avoid: `helper`, `utils`, `tools`, `anthropic-*`, `claude-*`
|
||||
|
||||
### Body Structure
|
||||
|
||||
Use standard markdown headings:
|
||||
|
||||
```markdown
|
||||
# Skill Name
|
||||
|
||||
## Quick Start
|
||||
Fastest path to value...
|
||||
|
||||
## Instructions
|
||||
Core guidance Claude follows...
|
||||
|
||||
## Examples
|
||||
Input/output pairs showing expected behavior...
|
||||
|
||||
## Advanced Features
|
||||
Additional capabilities (link to reference files)...
|
||||
|
||||
## Guidelines
|
||||
Rules and constraints...
|
||||
```
|
||||
|
||||
## What Would You Like To Do?
|
||||
|
||||
1. **Create new skill** - Build from scratch
|
||||
2. **Audit existing skill** - Check against best practices
|
||||
3. **Add component** - Add workflow/reference/example
|
||||
4. **Get guidance** - Understand skill design
|
||||
2. **Create new command** - Build a slash command
|
||||
3. **Audit existing skill** - Check against best practices
|
||||
4. **Add component** - Add workflow/reference/example
|
||||
5. **Get guidance** - Understand skill design
|
||||
|
||||
## Creating a New Skill
|
||||
## Creating a New Skill or Command
|
||||
|
||||
### Step 1: Choose Type
|
||||
|
||||
**Simple skill (single file):**
|
||||
- Under 500 lines
|
||||
- Self-contained guidance
|
||||
- No complex workflows
|
||||
Ask: Is this a manual workflow (deploy, commit, triage) or background knowledge (conventions, patterns)?
|
||||
|
||||
**Progressive disclosure skill (multiple files):**
|
||||
- SKILL.md as overview
|
||||
- Reference files for detailed docs
|
||||
- Scripts for utilities
|
||||
- **Manual workflow** → command with `disable-model-invocation: true`
|
||||
- **Background knowledge** → skill without `disable-model-invocation`
|
||||
- **Complex with supporting files** → skill directory
|
||||
|
||||
### Step 2: Create SKILL.md
|
||||
### Step 2: Create the File
|
||||
|
||||
**Command:**
|
||||
```markdown
|
||||
---
|
||||
name: your-skill-name
|
||||
description: [What it does]. Use when [trigger conditions].
|
||||
name: my-command
|
||||
description: What this command does
|
||||
argument-hint: [expected arguments]
|
||||
disable-model-invocation: true
|
||||
allowed-tools: Bash(gh *), Read
|
||||
---
|
||||
|
||||
# Your Skill Name
|
||||
# Command Title
|
||||
|
||||
## Quick Start
|
||||
## Workflow
|
||||
|
||||
[Immediate actionable example]
|
||||
### Step 1: Gather Context
|
||||
...
|
||||
|
||||
```[language]
|
||||
[Code example]
|
||||
### Step 2: Execute
|
||||
...
|
||||
|
||||
## Success Criteria
|
||||
- [ ] Expected outcome 1
|
||||
- [ ] Expected outcome 2
|
||||
```
|
||||
|
||||
## Instructions
|
||||
**Skill:**
|
||||
```markdown
|
||||
---
|
||||
name: my-skill
|
||||
description: What it does. Use when [trigger conditions].
|
||||
---
|
||||
|
||||
# Skill Title
|
||||
|
||||
## Quick Start
|
||||
[Immediate actionable example]
|
||||
|
||||
## Instructions
|
||||
[Core guidance]
|
||||
|
||||
## Examples
|
||||
|
||||
**Example 1:**
|
||||
Input: [description]
|
||||
Output:
|
||||
```
|
||||
[result]
|
||||
```
|
||||
|
||||
## Guidelines
|
||||
|
||||
- [Constraint 1]
|
||||
- [Constraint 2]
|
||||
[Concrete input/output pairs]
|
||||
```
|
||||
|
||||
### Step 3: Add Reference Files (If Needed)
|
||||
|
||||
Link from SKILL.md to detailed content:
|
||||
|
||||
```markdown
|
||||
For API reference, see [REFERENCE.md](REFERENCE.md).
|
||||
For form filling guide, see [FORMS.md](FORMS.md).
|
||||
For API reference, see [reference.md](reference.md).
|
||||
For form filling guide, see [forms.md](forms.md).
|
||||
```
|
||||
|
||||
Keep references **one level deep** from SKILL.md.
|
||||
|
||||
### Step 4: Add Scripts (If Needed)
|
||||
|
||||
Scripts execute without loading into context:
|
||||
|
||||
```markdown
|
||||
## Utility Scripts
|
||||
|
||||
Extract fields:
|
||||
```bash
|
||||
python scripts/analyze.py input.pdf > fields.json
|
||||
```
|
||||
```
|
||||
|
||||
### Step 5: Test With Real Usage
|
||||
### Step 4: Test With Real Usage
|
||||
|
||||
1. Test with actual tasks, not test scenarios
|
||||
2. Observe where Claude struggles
|
||||
3. Refine based on real behavior
|
||||
4. Test with Haiku, Sonnet, and Opus
|
||||
2. Invoke directly with `/skill-name` to verify
|
||||
3. Check auto-triggering by asking something that matches the description
|
||||
4. Refine based on real behavior
|
||||
|
||||
## Auditing Existing Skills
|
||||
|
||||
Check against this rubric:
|
||||
## Audit Checklist
|
||||
|
||||
- [ ] Valid YAML frontmatter (name + description)
|
||||
- [ ] Description includes trigger keywords
|
||||
- [ ] Description includes trigger keywords and is specific
|
||||
- [ ] Uses standard markdown headings (not XML tags)
|
||||
- [ ] SKILL.md under 500 lines
|
||||
- [ ] References one level deep
|
||||
- [ ] `disable-model-invocation: true` if it has side effects
|
||||
- [ ] `allowed-tools` set if specific tools needed
|
||||
- [ ] References one level deep, properly linked
|
||||
- [ ] Examples are concrete, not abstract
|
||||
- [ ] Consistent terminology
|
||||
- [ ] No time-sensitive information
|
||||
- [ ] Scripts handle errors explicitly
|
||||
|
||||
## Common Patterns
|
||||
|
||||
### Template Pattern
|
||||
|
||||
Provide output templates for consistent results:
|
||||
|
||||
```markdown
|
||||
## Report Template
|
||||
|
||||
```markdown
|
||||
# [Analysis Title]
|
||||
|
||||
## Executive Summary
|
||||
[One paragraph overview]
|
||||
|
||||
## Key Findings
|
||||
- Finding 1
|
||||
- Finding 2
|
||||
|
||||
## Recommendations
|
||||
1. [Action item]
|
||||
2. [Action item]
|
||||
```
|
||||
```
|
||||
|
||||
### Workflow Pattern
|
||||
|
||||
For complex multi-step tasks:
|
||||
|
||||
```markdown
|
||||
## Migration Workflow
|
||||
|
||||
Copy this checklist:
|
||||
|
||||
```
|
||||
- [ ] Step 1: Backup database
|
||||
- [ ] Step 2: Run migration script
|
||||
- [ ] Step 3: Validate output
|
||||
- [ ] Step 4: Update configuration
|
||||
```
|
||||
|
||||
**Step 1: Backup database**
|
||||
Run: `./scripts/backup.sh`
|
||||
...
|
||||
```
|
||||
|
||||
### Conditional Pattern
|
||||
|
||||
Guide through decision points:
|
||||
|
||||
```markdown
|
||||
## Choose Your Approach
|
||||
|
||||
**Creating new content?** Follow "Creation workflow" below.
|
||||
**Editing existing?** Follow "Editing workflow" below.
|
||||
```
|
||||
- [ ] Tested with real usage
|
||||
|
||||
## Anti-Patterns to Avoid
|
||||
|
||||
- **XML tags in body** - Use markdown headings instead
|
||||
- **XML tags in body** - Use standard markdown headings
|
||||
- **Vague descriptions** - Be specific with trigger keywords
|
||||
- **Deep nesting** - Keep references one level from SKILL.md
|
||||
- **Missing invocation control** - Side-effect workflows need `disable-model-invocation: true`
|
||||
- **Too many options** - Provide a default with escape hatch
|
||||
- **Windows paths** - Always use forward slashes
|
||||
- **Punting to Claude** - Scripts should handle errors
|
||||
- **Time-sensitive info** - Use "old patterns" section instead
|
||||
- **Punting to Claude** - Scripts should handle errors explicitly
|
||||
|
||||
## Reference Files
|
||||
|
||||
For detailed guidance, see:
|
||||
|
||||
- [official-spec.md](references/official-spec.md) - Anthropic's official skill specification
|
||||
- [official-spec.md](references/official-spec.md) - Official skill specification
|
||||
- [best-practices.md](references/best-practices.md) - Skill authoring best practices
|
||||
|
||||
## Success Criteria
|
||||
## Sources
|
||||
|
||||
A well-structured skill:
|
||||
- Has valid YAML frontmatter with descriptive name and description
|
||||
- Uses standard markdown headings (not XML tags)
|
||||
- Keeps SKILL.md under 500 lines
|
||||
- Links to reference files for detailed content
|
||||
- Includes concrete examples with input/output pairs
|
||||
- Has been tested with real usage
|
||||
|
||||
Sources:
|
||||
- [Agent Skills - Claude Code Docs](https://code.claude.com/docs/en/skills)
|
||||
- [Skill authoring best practices](https://platform.claude.com/docs/en/agents-and-tools/agent-skills/best-practices)
|
||||
- [Extend Claude with skills - Official Docs](https://code.claude.com/docs/en/skills)
|
||||
- [GitHub - anthropics/skills](https://github.com/anthropics/skills)
|
||||
|
||||
@@ -1,36 +1,56 @@
|
||||
# Anthropic Official Skill Specification
|
||||
# Official Skill Specification (2026)
|
||||
|
||||
Source: [code.claude.com/docs/en/skills](https://code.claude.com/docs/en/skills)
|
||||
|
||||
## Commands and Skills Are Merged
|
||||
|
||||
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.
|
||||
|
||||
## SKILL.md File Structure
|
||||
|
||||
Every Skill requires a `SKILL.md` file with YAML frontmatter followed by Markdown instructions.
|
||||
|
||||
### Basic Format
|
||||
Every skill requires a `SKILL.md` file with YAML frontmatter followed by standard markdown instructions.
|
||||
|
||||
```markdown
|
||||
---
|
||||
name: your-skill-name
|
||||
description: Brief description of what this Skill does and when to use it
|
||||
description: What it does and when to use it
|
||||
---
|
||||
|
||||
# Your Skill Name
|
||||
|
||||
## Instructions
|
||||
Provide clear, step-by-step guidance for Claude.
|
||||
Clear, step-by-step guidance.
|
||||
|
||||
## Examples
|
||||
Show concrete examples of using this Skill.
|
||||
Concrete examples of using this skill.
|
||||
```
|
||||
|
||||
## Required Frontmatter Fields
|
||||
## Complete Frontmatter Reference
|
||||
|
||||
All fields are optional. Only `description` is recommended.
|
||||
|
||||
| Field | Required | Description |
|
||||
|-------|----------|-------------|
|
||||
| `name` | Yes | Skill name using lowercase letters, numbers, and hyphens only (max 64 characters). Should match the directory name. |
|
||||
| `description` | Yes | What the Skill does and when to use it (max 1024 characters). Claude uses this to decide when to apply the Skill. |
|
||||
| `allowed-tools` | No | Tools Claude can use without asking permission when this Skill is active. Example: `Read, Grep, Glob` |
|
||||
| `model` | No | Specific model to use when this Skill is active (e.g., `claude-sonnet-4-20250514`). Defaults to the conversation's model. |
|
||||
| `name` | No | Display name. Lowercase letters, numbers, hyphens only (max 64 chars). Defaults to directory name if omitted. |
|
||||
| `description` | Recommended | What it does AND when to use it (max 1024 chars). Claude uses this to decide when to apply the skill. |
|
||||
| `argument-hint` | No | Hint shown during autocomplete. Example: `[issue-number]` or `[filename] [format]` |
|
||||
| `disable-model-invocation` | No | Set `true` to prevent Claude from auto-loading. Use for manual workflows. 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: `haiku`, `sonnet`, or `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 |
|
||||
| `hooks` | No | Hooks scoped to this skill's lifecycle |
|
||||
|
||||
## Invocation Control
|
||||
|
||||
| Frontmatter | User can invoke | Claude can invoke | When loaded into context |
|
||||
|-------------|----------------|-------------------|--------------------------|
|
||||
| (default) | Yes | Yes | Description always in context, full skill loads when invoked |
|
||||
| `disable-model-invocation: true` | Yes | No | Description not in context, full skill loads when you invoke |
|
||||
| `user-invocable: false` | No | Yes | Description always in context, full skill loads when invoked |
|
||||
|
||||
## Skill Locations & Priority
|
||||
|
||||
@@ -40,146 +60,75 @@ Enterprise (highest priority) → Personal → Project → Plugin (lowest priori
|
||||
|
||||
| Type | Path | Applies to |
|
||||
|------|------|-----------|
|
||||
| **Enterprise** | See managed settings | All users in organization |
|
||||
| **Personal** | `~/.claude/skills/` | You, across all projects |
|
||||
| **Project** | `.claude/skills/` | Anyone working in repository |
|
||||
| **Plugin** | Bundled with plugins | Anyone with plugin installed |
|
||||
| Enterprise | See managed settings | All users in organization |
|
||||
| Personal | `~/.claude/skills/<name>/SKILL.md` | You, across all projects |
|
||||
| Project | `.claude/skills/<name>/SKILL.md` | Anyone working in repository |
|
||||
| Plugin | `<plugin>/skills/<name>/SKILL.md` | Where plugin is enabled |
|
||||
|
||||
Plugin skills use a `plugin-name:skill-name` namespace, so they cannot conflict with other levels.
|
||||
|
||||
## How Skills Work
|
||||
|
||||
1. **Discovery**: Claude loads only name and description at startup
|
||||
2. **Activation**: When your request matches a Skill's description, Claude asks for confirmation
|
||||
3. **Execution**: Claude follows the Skill's instructions and loads referenced files
|
||||
1. **Discovery**: Claude loads only name and description at startup (2% of context window budget)
|
||||
2. **Activation**: When your request matches a skill's description, Claude loads the full content
|
||||
3. **Execution**: Claude follows the skill's instructions
|
||||
|
||||
**Key Principle**: Skills are **model-invoked** — Claude automatically decides which Skills to use based on your request.
|
||||
## String Substitutions
|
||||
|
||||
## Progressive Disclosure Pattern
|
||||
| Variable | Description |
|
||||
|----------|-------------|
|
||||
| `$ARGUMENTS` | All arguments passed when invoking |
|
||||
| `$ARGUMENTS[N]` | Specific argument by 0-based index |
|
||||
| `$N` | Shorthand for `$ARGUMENTS[N]` |
|
||||
| `${CLAUDE_SESSION_ID}` | Current session ID |
|
||||
|
||||
Keep `SKILL.md` under 500 lines by linking to supporting files:
|
||||
## Dynamic Context Injection
|
||||
|
||||
The `` !`command` `` syntax runs shell commands before content is sent to Claude:
|
||||
|
||||
```markdown
|
||||
## Context
|
||||
- Current branch: !`git branch --show-current`
|
||||
- PR diff: !`gh pr diff`
|
||||
```
|
||||
|
||||
Commands execute immediately and their output replaces the placeholder. Claude only sees the final result.
|
||||
|
||||
## Progressive Disclosure
|
||||
|
||||
```
|
||||
my-skill/
|
||||
├── SKILL.md (required - overview and navigation)
|
||||
├── reference.md (detailed API docs - loaded when needed)
|
||||
├── examples.md (usage examples - loaded when needed)
|
||||
├── SKILL.md # Entry point (required)
|
||||
├── reference.md # Detailed docs (loaded when needed)
|
||||
├── examples.md # Usage examples (loaded when needed)
|
||||
└── scripts/
|
||||
└── helper.py (utility script - executed, not loaded)
|
||||
└── helper.py # Utility script (executed, not loaded)
|
||||
```
|
||||
|
||||
### Example SKILL.md with References
|
||||
|
||||
Keep SKILL.md under 500 lines. Link to supporting files:
|
||||
```markdown
|
||||
---
|
||||
name: pdf-processing
|
||||
description: Extract text, fill forms, merge PDFs. Use when working with PDF files, forms, or document extraction. Requires pypdf and pdfplumber packages.
|
||||
allowed-tools: Read, Bash(python:*)
|
||||
---
|
||||
|
||||
# PDF Processing
|
||||
|
||||
## Quick start
|
||||
|
||||
Extract text:
|
||||
```python
|
||||
import pdfplumber
|
||||
with pdfplumber.open("doc.pdf") as pdf:
|
||||
text = pdf.pages[0].extract_text()
|
||||
For API details, see [reference.md](reference.md).
|
||||
```
|
||||
|
||||
For form filling, see [FORMS.md](FORMS.md).
|
||||
For detailed API reference, see [REFERENCE.md](REFERENCE.md).
|
||||
## Running in a Subagent
|
||||
|
||||
## Requirements
|
||||
|
||||
Packages must be installed:
|
||||
```bash
|
||||
pip install pypdf pdfplumber
|
||||
```
|
||||
```
|
||||
|
||||
## Restricting Tool Access
|
||||
Add `context: fork` to run in isolation:
|
||||
|
||||
```yaml
|
||||
---
|
||||
name: reading-files-safely
|
||||
description: Read files without making changes. Use when you need read-only file access.
|
||||
allowed-tools: Read, Grep, Glob
|
||||
---
|
||||
```
|
||||
|
||||
Benefits:
|
||||
- Read-only Skills that shouldn't modify files
|
||||
- Limited scope for specific tasks
|
||||
- Security-sensitive workflows
|
||||
|
||||
## Writing Effective Descriptions
|
||||
|
||||
The `description` field enables Skill discovery and should include both what the Skill does and when to use it.
|
||||
|
||||
**Always write in third person.** The description is injected into the system prompt.
|
||||
|
||||
- **Good:** "Processes Excel files and generates reports"
|
||||
- **Avoid:** "I can help you process Excel files"
|
||||
- **Avoid:** "You can use this to process Excel files"
|
||||
|
||||
**Be specific and include key terms:**
|
||||
|
||||
```yaml
|
||||
description: Extract text and tables from PDF files, fill forms, merge documents. Use when working with PDF files or when the user mentions PDFs, forms, or document extraction.
|
||||
```
|
||||
|
||||
**Avoid vague descriptions:**
|
||||
|
||||
```yaml
|
||||
description: Helps with documents # Too vague!
|
||||
```
|
||||
|
||||
## Complete Example: Commit Message Generator
|
||||
|
||||
```markdown
|
||||
---
|
||||
name: generating-commit-messages
|
||||
description: Generates clear commit messages from git diffs. Use when writing commit messages or reviewing staged changes.
|
||||
name: deep-research
|
||||
description: Research a topic thoroughly
|
||||
context: fork
|
||||
agent: Explore
|
||||
---
|
||||
|
||||
# Generating Commit Messages
|
||||
|
||||
## Instructions
|
||||
|
||||
1. Run `git diff --staged` to see changes
|
||||
2. I'll suggest a commit message with:
|
||||
- Summary under 50 characters
|
||||
- Detailed description
|
||||
- Affected components
|
||||
|
||||
## Best practices
|
||||
|
||||
- Use present tense
|
||||
- Explain what and why, not how
|
||||
Research $ARGUMENTS thoroughly...
|
||||
```
|
||||
|
||||
## Complete Example: Code Explanation Skill
|
||||
|
||||
```markdown
|
||||
---
|
||||
name: explaining-code
|
||||
description: Explains code with visual diagrams and analogies. Use when explaining how code works, teaching about a codebase, or when the user asks "how does this work?"
|
||||
---
|
||||
|
||||
# Explaining Code
|
||||
|
||||
When explaining code, always include:
|
||||
|
||||
1. **Start with an analogy**: Compare the code to something from everyday life
|
||||
2. **Draw a diagram**: Use ASCII art to show the flow, structure, or relationships
|
||||
3. **Walk through the code**: Explain step-by-step what happens
|
||||
4. **Highlight a gotcha**: What's a common misconception?
|
||||
|
||||
Keep explanations conversational. For complex concepts, use multiple analogies.
|
||||
```
|
||||
The skill content becomes the subagent's prompt. It won't have access to conversation history.
|
||||
|
||||
## Distribution
|
||||
|
||||
- **Project Skills**: Commit `.claude/skills/` to version control
|
||||
- **Plugins**: Add `skills/` directory to plugin with Skill folders
|
||||
- **Project skills**: Commit `.claude/skills/` to version control
|
||||
- **Plugins**: Add `skills/` directory to plugin
|
||||
- **Enterprise**: Deploy organization-wide through managed settings
|
||||
|
||||
@@ -1,372 +1,152 @@
|
||||
<overview>
|
||||
Skills have three structural components: YAML frontmatter (metadata), pure XML body structure (content organization), and progressive disclosure (file organization). This reference defines requirements and best practices for each component.
|
||||
</overview>
|
||||
# Skill Structure Reference
|
||||
|
||||
<xml_structure_requirements>
|
||||
<critical_rule>
|
||||
**Remove ALL markdown headings (#, ##, ###) from skill body content.** Replace with semantic XML tags. Keep markdown formatting WITHIN content (bold, italic, lists, code blocks, links).
|
||||
</critical_rule>
|
||||
Skills have three structural components: YAML frontmatter (metadata), standard markdown body (content), and progressive disclosure (file organization).
|
||||
|
||||
<required_tags>
|
||||
Every skill MUST have these three tags:
|
||||
## Body Format
|
||||
|
||||
- **`<objective>`** - What the skill does and why it matters (1-3 paragraphs)
|
||||
- **`<quick_start>`** - Immediate, actionable guidance (minimal working example)
|
||||
- **`<success_criteria>`** or **`<when_successful>`** - How to know it worked
|
||||
</required_tags>
|
||||
Use **standard markdown headings** for structure. Keep markdown formatting within content (bold, italic, lists, code blocks, links).
|
||||
|
||||
<conditional_tags>
|
||||
Add based on skill complexity and domain requirements:
|
||||
```markdown
|
||||
---
|
||||
name: my-skill
|
||||
description: What it does and when to use it
|
||||
---
|
||||
|
||||
- **`<context>`** - Background/situational information
|
||||
- **`<workflow>` or `<process>`** - Step-by-step procedures
|
||||
- **`<advanced_features>`** - Deep-dive topics (progressive disclosure)
|
||||
- **`<validation>`** - How to verify outputs
|
||||
- **`<examples>`** - Multi-shot learning
|
||||
- **`<anti_patterns>`** - Common mistakes to avoid
|
||||
- **`<security_checklist>`** - Non-negotiable security patterns
|
||||
- **`<testing>`** - Testing workflows
|
||||
- **`<common_patterns>`** - Code examples and recipes
|
||||
- **`<reference_guides>` or `<detailed_references>`** - Links to reference files
|
||||
# Skill Name
|
||||
|
||||
See [use-xml-tags.md](use-xml-tags.md) for detailed guidance on each tag.
|
||||
</conditional_tags>
|
||||
## Quick Start
|
||||
Immediate actionable guidance...
|
||||
|
||||
<tag_selection_intelligence>
|
||||
**Simple skills** (single domain, straightforward):
|
||||
- Required tags only
|
||||
- Example: Text extraction, file format conversion
|
||||
## Instructions
|
||||
Step-by-step procedures...
|
||||
|
||||
**Medium skills** (multiple patterns, some complexity):
|
||||
- Required tags + workflow/examples as needed
|
||||
- Example: Document processing with steps, API integration
|
||||
## Examples
|
||||
Concrete usage examples...
|
||||
|
||||
**Complex skills** (multiple domains, security, APIs):
|
||||
- Required tags + conditional tags as appropriate
|
||||
- Example: Payment processing, authentication systems, multi-step workflows
|
||||
</tag_selection_intelligence>
|
||||
|
||||
<xml_nesting>
|
||||
Properly nest XML tags for hierarchical content:
|
||||
|
||||
```xml
|
||||
<examples>
|
||||
<example number="1">
|
||||
<input>User input</input>
|
||||
<output>Expected output</output>
|
||||
</example>
|
||||
</examples>
|
||||
## Guidelines
|
||||
Rules and constraints...
|
||||
```
|
||||
|
||||
Always close tags:
|
||||
```xml
|
||||
<objective>
|
||||
Content here
|
||||
</objective>
|
||||
```
|
||||
</xml_nesting>
|
||||
## Recommended Sections
|
||||
|
||||
<tag_naming_conventions>
|
||||
Use descriptive, semantic names:
|
||||
- `<workflow>` not `<steps>`
|
||||
- `<success_criteria>` not `<done>`
|
||||
- `<anti_patterns>` not `<dont_do>`
|
||||
Every skill should have:
|
||||
|
||||
Be consistent within your skill. If you use `<workflow>`, don't also use `<process>` for the same purpose (unless they serve different roles).
|
||||
</tag_naming_conventions>
|
||||
</xml_structure_requirements>
|
||||
- **Quick Start** - Immediate, actionable guidance (minimal working example)
|
||||
- **Instructions** - Core step-by-step guidance
|
||||
- **Success Criteria** - How to know it worked
|
||||
|
||||
Add based on complexity:
|
||||
|
||||
- **Context** - Background/situational information
|
||||
- **Workflow** - Multi-step procedures
|
||||
- **Examples** - Concrete input/output pairs
|
||||
- **Advanced Features** - Deep-dive topics (link to reference files)
|
||||
- **Anti-Patterns** - Common mistakes to avoid
|
||||
- **Guidelines** - Rules and constraints
|
||||
|
||||
## YAML Frontmatter
|
||||
|
||||
### Required/Recommended Fields
|
||||
|
||||
<yaml_requirements>
|
||||
<required_fields>
|
||||
```yaml
|
||||
---
|
||||
name: skill-name-here
|
||||
description: What it does and when to use it (third person, specific triggers)
|
||||
description: What it does and when to use it (specific triggers included)
|
||||
---
|
||||
```
|
||||
</required_fields>
|
||||
|
||||
<name_field>
|
||||
**Validation rules**:
|
||||
### Name Field
|
||||
|
||||
**Validation rules:**
|
||||
- Maximum 64 characters
|
||||
- Lowercase letters, numbers, hyphens only
|
||||
- No XML tags
|
||||
- Must match directory name
|
||||
- No reserved words: "anthropic", "claude"
|
||||
- Must match directory name exactly
|
||||
|
||||
**Examples**:
|
||||
- ✅ `process-pdfs`
|
||||
- ✅ `manage-facebook-ads`
|
||||
- ✅ `setup-stripe-payments`
|
||||
- ❌ `PDF_Processor` (uppercase)
|
||||
- ❌ `helper` (vague)
|
||||
- ❌ `claude-helper` (reserved word)
|
||||
</name_field>
|
||||
**Examples:**
|
||||
- `triage-prs`
|
||||
- `deploy-production`
|
||||
- `review-code`
|
||||
- `setup-stripe-payments`
|
||||
|
||||
<description_field>
|
||||
**Validation rules**:
|
||||
- Non-empty, maximum 1024 characters
|
||||
- No XML tags
|
||||
- Third person (never first or second person)
|
||||
**Avoid:** `helper`, `utils`, `tools`, generic names
|
||||
|
||||
### Description Field
|
||||
|
||||
**Validation rules:**
|
||||
- Maximum 1024 characters
|
||||
- Include what it does AND when to use it
|
||||
- Third person voice
|
||||
|
||||
**Critical rule**: Always write in third person.
|
||||
- ✅ "Processes Excel files and generates reports"
|
||||
- ❌ "I can help you process Excel files"
|
||||
- ❌ "You can use this to process Excel files"
|
||||
|
||||
**Structure**: Include both capabilities and triggers.
|
||||
|
||||
**Effective examples**:
|
||||
**Good:**
|
||||
```yaml
|
||||
description: Extract text and tables from PDF files, fill forms, merge documents. Use when working with PDF files or when the user mentions PDFs, forms, or document extraction.
|
||||
```
|
||||
|
||||
```yaml
|
||||
description: Analyze Excel spreadsheets, create pivot tables, generate charts. Use when analyzing Excel files, spreadsheets, tabular data, or .xlsx files.
|
||||
```
|
||||
|
||||
```yaml
|
||||
description: Generate descriptive commit messages by analyzing git diffs. Use when the user asks for help writing commit messages or reviewing staged changes.
|
||||
```
|
||||
|
||||
**Avoid**:
|
||||
**Bad:**
|
||||
```yaml
|
||||
description: Helps with documents
|
||||
```
|
||||
|
||||
```yaml
|
||||
description: Processes data
|
||||
### Optional Fields
|
||||
|
||||
| Field | Description |
|
||||
|-------|-------------|
|
||||
| `argument-hint` | Usage hints. Example: `[issue-number]` |
|
||||
| `disable-model-invocation` | `true` to prevent auto-loading. Use for side-effect workflows. |
|
||||
| `user-invocable` | `false` to hide from `/` menu. Use for background knowledge. |
|
||||
| `allowed-tools` | Tools without permission prompts. Example: `Read, Bash(git *)` |
|
||||
| `model` | `haiku`, `sonnet`, or `opus` |
|
||||
| `context` | `fork` for isolated subagent execution |
|
||||
| `agent` | Subagent type: `Explore`, `Plan`, `general-purpose`, or custom |
|
||||
|
||||
## Naming Conventions
|
||||
|
||||
Use descriptive names that indicate purpose:
|
||||
|
||||
| Pattern | Examples |
|
||||
|---------|----------|
|
||||
| Action-oriented | `triage-prs`, `deploy-production`, `review-code` |
|
||||
| Domain-specific | `setup-stripe-payments`, `manage-facebook-ads` |
|
||||
| Descriptive | `git-worktree`, `frontend-design`, `dhh-rails-style` |
|
||||
|
||||
## Progressive Disclosure
|
||||
|
||||
Keep SKILL.md under 500 lines. Split 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)
|
||||
```
|
||||
</description_field>
|
||||
</yaml_requirements>
|
||||
|
||||
<naming_conventions>
|
||||
Use **verb-noun convention** for skill names:
|
||||
|
||||
<pattern name="create">
|
||||
Building/authoring tools
|
||||
|
||||
Examples: `create-agent-skills`, `create-hooks`, `create-landing-pages`
|
||||
</pattern>
|
||||
|
||||
<pattern name="manage">
|
||||
Managing external services or resources
|
||||
|
||||
Examples: `manage-facebook-ads`, `manage-zoom`, `manage-stripe`, `manage-supabase`
|
||||
</pattern>
|
||||
|
||||
<pattern name="setup">
|
||||
Configuration/integration tasks
|
||||
|
||||
Examples: `setup-stripe-payments`, `setup-meta-tracking`
|
||||
</pattern>
|
||||
|
||||
<pattern name="generate">
|
||||
Generation tasks
|
||||
|
||||
Examples: `generate-ai-images`
|
||||
</pattern>
|
||||
|
||||
<avoid_patterns>
|
||||
- Vague: `helper`, `utils`, `tools`
|
||||
- Generic: `documents`, `data`, `files`
|
||||
- Reserved words: `anthropic-helper`, `claude-tools`
|
||||
- Inconsistent: Directory `facebook-ads` but name `facebook-ads-manager`
|
||||
</avoid_patterns>
|
||||
</naming_conventions>
|
||||
|
||||
<progressive_disclosure>
|
||||
<principle>
|
||||
SKILL.md serves as an overview that points to detailed materials as needed. This keeps context window usage efficient.
|
||||
</principle>
|
||||
|
||||
<practical_guidance>
|
||||
- Keep SKILL.md body under 500 lines
|
||||
- Split content into separate files when approaching this limit
|
||||
**Rules:**
|
||||
- Keep references one level deep from SKILL.md
|
||||
- Add table of contents to reference files over 100 lines
|
||||
</practical_guidance>
|
||||
- Use forward slashes in paths: `scripts/helper.py`
|
||||
- Name files descriptively: `form_validation_rules.md` not `doc2.md`
|
||||
|
||||
<pattern name="high_level_guide">
|
||||
Quick start in SKILL.md, details in reference files:
|
||||
## Validation Checklist
|
||||
|
||||
```markdown
|
||||
---
|
||||
name: pdf-processing
|
||||
description: Extracts text and tables from PDF files, fills forms, and merges documents. Use when working with PDF files or when the user mentions PDFs, forms, or document extraction.
|
||||
---
|
||||
Before finalizing:
|
||||
|
||||
<objective>
|
||||
Extract text and tables from PDF files, fill forms, and merge documents using Python libraries.
|
||||
</objective>
|
||||
- [ ] YAML frontmatter valid (name matches directory, description specific)
|
||||
- [ ] Uses standard markdown headings (not XML tags)
|
||||
- [ ] Has Quick Start, Instructions, and Success Criteria sections
|
||||
- [ ] `disable-model-invocation: true` if skill has side effects
|
||||
- [ ] SKILL.md under 500 lines
|
||||
- [ ] Reference files linked properly from SKILL.md
|
||||
- [ ] File paths use forward slashes
|
||||
- [ ] Tested with real usage
|
||||
|
||||
<quick_start>
|
||||
Extract text with pdfplumber:
|
||||
## Anti-Patterns
|
||||
|
||||
```python
|
||||
import pdfplumber
|
||||
with pdfplumber.open("file.pdf") as pdf:
|
||||
text = pdf.pages[0].extract_text()
|
||||
```
|
||||
</quick_start>
|
||||
|
||||
<advanced_features>
|
||||
**Form filling**: See [forms.md](forms.md)
|
||||
**API reference**: See [reference.md](reference.md)
|
||||
</advanced_features>
|
||||
```
|
||||
|
||||
Claude loads forms.md or reference.md only when needed.
|
||||
</pattern>
|
||||
|
||||
<pattern name="domain_organization">
|
||||
For skills with multiple domains, organize by domain to avoid loading irrelevant context:
|
||||
|
||||
```
|
||||
bigquery-skill/
|
||||
├── SKILL.md (overview and navigation)
|
||||
└── reference/
|
||||
├── finance.md (revenue, billing metrics)
|
||||
├── sales.md (opportunities, pipeline)
|
||||
├── product.md (API usage, features)
|
||||
└── marketing.md (campaigns, attribution)
|
||||
```
|
||||
|
||||
When user asks about revenue, Claude reads only finance.md. Other files stay on filesystem consuming zero tokens.
|
||||
</pattern>
|
||||
|
||||
<pattern name="conditional_details">
|
||||
Show basic content in SKILL.md, link to advanced in reference files:
|
||||
|
||||
```xml
|
||||
<objective>
|
||||
Process DOCX files with creation and editing capabilities.
|
||||
</objective>
|
||||
|
||||
<quick_start>
|
||||
<creating_documents>
|
||||
Use docx-js for new documents. See [docx-js.md](docx-js.md).
|
||||
</creating_documents>
|
||||
|
||||
<editing_documents>
|
||||
For simple edits, modify XML directly.
|
||||
|
||||
**For tracked changes**: See [redlining.md](redlining.md)
|
||||
**For OOXML details**: See [ooxml.md](ooxml.md)
|
||||
</editing_documents>
|
||||
</quick_start>
|
||||
```
|
||||
|
||||
Claude reads redlining.md or ooxml.md only when the user needs those features.
|
||||
</pattern>
|
||||
|
||||
<critical_rules>
|
||||
**Keep references one level deep**: All reference files should link directly from SKILL.md. Avoid nested references (SKILL.md → advanced.md → details.md) as Claude may only partially read deeply nested files.
|
||||
|
||||
**Add table of contents to long files**: For reference files over 100 lines, include a table of contents at the top.
|
||||
|
||||
**Use pure XML in reference files**: Reference files should also use pure XML structure (no markdown headings in body).
|
||||
</critical_rules>
|
||||
</progressive_disclosure>
|
||||
|
||||
<file_organization>
|
||||
<filesystem_navigation>
|
||||
Claude navigates your skill directory using bash commands:
|
||||
|
||||
- Use forward slashes: `reference/guide.md` (not `reference\guide.md`)
|
||||
- Name files descriptively: `form_validation_rules.md` (not `doc2.md`)
|
||||
- Organize by domain: `reference/finance.md`, `reference/sales.md`
|
||||
</filesystem_navigation>
|
||||
|
||||
<directory_structure>
|
||||
Typical skill structure:
|
||||
|
||||
```
|
||||
skill-name/
|
||||
├── SKILL.md (main entry point, pure XML structure)
|
||||
├── references/ (optional, for progressive disclosure)
|
||||
│ ├── guide-1.md (pure XML structure)
|
||||
│ ├── guide-2.md (pure XML structure)
|
||||
│ └── examples.md (pure XML structure)
|
||||
└── scripts/ (optional, for utility scripts)
|
||||
├── validate.py
|
||||
└── process.py
|
||||
```
|
||||
</directory_structure>
|
||||
</file_organization>
|
||||
|
||||
<anti_patterns>
|
||||
<pitfall name="markdown_headings_in_body">
|
||||
❌ Do NOT use markdown headings in skill body:
|
||||
|
||||
```markdown
|
||||
# PDF Processing
|
||||
|
||||
## Quick start
|
||||
Extract text...
|
||||
|
||||
## Advanced features
|
||||
Form filling...
|
||||
```
|
||||
|
||||
✅ Use pure XML structure:
|
||||
|
||||
```xml
|
||||
<objective>
|
||||
PDF processing with text extraction, form filling, and merging.
|
||||
</objective>
|
||||
|
||||
<quick_start>
|
||||
Extract text...
|
||||
</quick_start>
|
||||
|
||||
<advanced_features>
|
||||
Form filling...
|
||||
</advanced_features>
|
||||
```
|
||||
</pitfall>
|
||||
|
||||
<pitfall name="vague_descriptions">
|
||||
- ❌ "Helps with documents"
|
||||
- ✅ "Extract text and tables from PDF files, fill forms, merge documents. Use when working with PDF files or when the user mentions PDFs, forms, or document extraction."
|
||||
</pitfall>
|
||||
|
||||
<pitfall name="inconsistent_pov">
|
||||
- ❌ "I can help you process Excel files"
|
||||
- ✅ "Processes Excel files and generates reports"
|
||||
</pitfall>
|
||||
|
||||
<pitfall name="wrong_naming_convention">
|
||||
- ❌ Directory: `facebook-ads`, Name: `facebook-ads-manager`
|
||||
- ✅ Directory: `manage-facebook-ads`, Name: `manage-facebook-ads`
|
||||
- ❌ Directory: `stripe-integration`, Name: `stripe`
|
||||
- ✅ Directory: `setup-stripe-payments`, Name: `setup-stripe-payments`
|
||||
</pitfall>
|
||||
|
||||
<pitfall name="deeply_nested_references">
|
||||
Keep references one level deep from SKILL.md. Claude may only partially read nested files (SKILL.md → advanced.md → details.md).
|
||||
</pitfall>
|
||||
|
||||
<pitfall name="windows_paths">
|
||||
Always use forward slashes: `scripts/helper.py` (not `scripts\helper.py`)
|
||||
</pitfall>
|
||||
|
||||
<pitfall name="missing_required_tags">
|
||||
Every skill must have: `<objective>`, `<quick_start>`, and `<success_criteria>` (or `<when_successful>`).
|
||||
</pitfall>
|
||||
</anti_patterns>
|
||||
|
||||
<validation_checklist>
|
||||
Before finalizing a skill, verify:
|
||||
|
||||
- ✅ YAML frontmatter valid (name matches directory, description in third person)
|
||||
- ✅ No markdown headings in body (pure XML structure)
|
||||
- ✅ Required tags present: objective, quick_start, success_criteria
|
||||
- ✅ Conditional tags appropriate for complexity level
|
||||
- ✅ All XML tags properly closed
|
||||
- ✅ Progressive disclosure applied (SKILL.md < 500 lines)
|
||||
- ✅ Reference files use pure XML structure
|
||||
- ✅ File paths use forward slashes
|
||||
- ✅ Descriptive file names
|
||||
</validation_checklist>
|
||||
- **XML tags in body** - Use standard markdown headings
|
||||
- **Vague descriptions** - Be specific with trigger keywords
|
||||
- **Deep nesting** - Keep references one level from SKILL.md
|
||||
- **Missing invocation control** - Side-effect workflows need `disable-model-invocation: true`
|
||||
- **Inconsistent naming** - Directory name must match `name` field
|
||||
- **Windows paths** - Always use forward slashes
|
||||
|
||||
@@ -1,6 +1,7 @@
|
||||
---
|
||||
name: file-todos
|
||||
description: This skill should be used when managing the file-based todo tracking system in the todos/ directory. It provides workflows for creating todos, managing status and dependencies, conducting triage, and integrating with slash commands and code review processes.
|
||||
disable-model-invocation: true
|
||||
---
|
||||
|
||||
# File-Based Todo Tracking Skill
|
||||
|
||||
@@ -1,6 +1,7 @@
|
||||
---
|
||||
name: orchestrating-swarms
|
||||
description: This skill should be used when orchestrating multi-agent swarms using Claude Code's TeammateTool and Task system. It applies when coordinating multiple agents, running parallel code reviews, creating pipeline workflows with dependencies, building self-organizing task queues, or any task benefiting from divide-and-conquer patterns.
|
||||
disable-model-invocation: true
|
||||
---
|
||||
|
||||
# Claude Code Swarm Orchestration
|
||||
|
||||
@@ -0,0 +1,89 @@
|
||||
---
|
||||
name: resolve_pr_parallel
|
||||
description: Resolve all PR comments using parallel processing. Use when addressing PR review feedback, resolving review threads, or batch-fixing PR comments.
|
||||
argument-hint: "[optional: PR number or current PR]"
|
||||
disable-model-invocation: true
|
||||
allowed-tools: Bash(gh *), Bash(git *), Read
|
||||
---
|
||||
|
||||
# Resolve PR Comments in Parallel
|
||||
|
||||
Resolve all unresolved PR review comments by spawning parallel agents for each thread.
|
||||
|
||||
## Context Detection
|
||||
|
||||
Claude Code automatically detects git context:
|
||||
- Current branch and associated PR
|
||||
- All PR comments and review threads
|
||||
- Works with any PR by specifying the number
|
||||
|
||||
## Workflow
|
||||
|
||||
### 1. Analyze
|
||||
|
||||
Fetch unresolved review threads using the GraphQL script:
|
||||
|
||||
```bash
|
||||
bash ${CLAUDE_PLUGIN_ROOT}/skills/resolve-pr-parallel/scripts/get-pr-comments PR_NUMBER
|
||||
```
|
||||
|
||||
This returns only **unresolved, non-outdated** threads with file paths, line numbers, and comment bodies.
|
||||
|
||||
If the script fails, fall back to:
|
||||
```bash
|
||||
gh pr view PR_NUMBER --json reviews,comments
|
||||
gh api repos/{owner}/{repo}/pulls/PR_NUMBER/comments
|
||||
```
|
||||
|
||||
### 2. Plan
|
||||
|
||||
Create a TodoWrite list of all unresolved items grouped by type:
|
||||
- Code changes requested
|
||||
- Questions to answer
|
||||
- Style/convention fixes
|
||||
- Test additions needed
|
||||
|
||||
### 3. Implement (PARALLEL)
|
||||
|
||||
Spawn a `pr-comment-resolver` agent for each unresolved item in parallel.
|
||||
|
||||
If there are 3 comments, spawn 3 agents:
|
||||
|
||||
1. Task pr-comment-resolver(comment1)
|
||||
2. Task pr-comment-resolver(comment2)
|
||||
3. Task pr-comment-resolver(comment3)
|
||||
|
||||
Always run all in parallel subagents/Tasks for each Todo item.
|
||||
|
||||
### 4. Commit & Resolve
|
||||
|
||||
- Commit changes with a clear message referencing the PR feedback
|
||||
- Resolve each thread programmatically:
|
||||
|
||||
```bash
|
||||
bash ${CLAUDE_PLUGIN_ROOT}/skills/resolve-pr-parallel/scripts/resolve-pr-thread THREAD_ID
|
||||
```
|
||||
|
||||
- Push to remote
|
||||
|
||||
### 5. Verify
|
||||
|
||||
Re-fetch comments to confirm all threads are resolved:
|
||||
|
||||
```bash
|
||||
bash ${CLAUDE_PLUGIN_ROOT}/skills/resolve-pr-parallel/scripts/get-pr-comments PR_NUMBER
|
||||
```
|
||||
|
||||
Should return an empty array `[]`. If threads remain, repeat from step 1.
|
||||
|
||||
## Scripts
|
||||
|
||||
- [scripts/get-pr-comments](scripts/get-pr-comments) - GraphQL query for unresolved review threads
|
||||
- [scripts/resolve-pr-thread](scripts/resolve-pr-thread) - GraphQL mutation to resolve a thread by ID
|
||||
|
||||
## Success Criteria
|
||||
|
||||
- All unresolved review threads addressed
|
||||
- Changes committed and pushed
|
||||
- Threads resolved via GraphQL (marked as resolved on GitHub)
|
||||
- Empty result from get-pr-comments on verify
|
||||
@@ -0,0 +1,68 @@
|
||||
#!/usr/bin/env bash
|
||||
|
||||
set -e
|
||||
|
||||
if [ $# -lt 1 ]; then
|
||||
echo "Usage: get-pr-comments PR_NUMBER [OWNER/REPO]"
|
||||
echo "Example: get-pr-comments 123"
|
||||
echo "Example: get-pr-comments 123 EveryInc/cora"
|
||||
exit 1
|
||||
fi
|
||||
|
||||
PR_NUMBER=$1
|
||||
|
||||
if [ -n "$2" ]; then
|
||||
OWNER=$(echo "$2" | cut -d/ -f1)
|
||||
REPO=$(echo "$2" | cut -d/ -f2)
|
||||
else
|
||||
OWNER=$(gh repo view --json owner -q .owner.login 2>/dev/null)
|
||||
REPO=$(gh repo view --json name -q .name 2>/dev/null)
|
||||
fi
|
||||
|
||||
if [ -z "$OWNER" ] || [ -z "$REPO" ]; then
|
||||
echo "Error: Could not detect repository. Pass OWNER/REPO as second argument."
|
||||
exit 1
|
||||
fi
|
||||
|
||||
gh api graphql -f owner="$OWNER" -f repo="$REPO" -F pr="$PR_NUMBER" -f query='
|
||||
query FetchUnresolvedComments($owner: String!, $repo: String!, $pr: Int!) {
|
||||
repository(owner: $owner, name: $repo) {
|
||||
pullRequest(number: $pr) {
|
||||
title
|
||||
url
|
||||
reviewThreads(first: 100) {
|
||||
totalCount
|
||||
edges {
|
||||
node {
|
||||
id
|
||||
isResolved
|
||||
isOutdated
|
||||
isCollapsed
|
||||
path
|
||||
line
|
||||
startLine
|
||||
diffSide
|
||||
comments(first: 100) {
|
||||
totalCount
|
||||
nodes {
|
||||
id
|
||||
author {
|
||||
login
|
||||
}
|
||||
body
|
||||
createdAt
|
||||
updatedAt
|
||||
url
|
||||
outdated
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
pageInfo {
|
||||
hasNextPage
|
||||
endCursor
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}' | jq '.data.repository.pullRequest.reviewThreads.edges | map(select(.node.isResolved == false and .node.isOutdated == false))'
|
||||
@@ -0,0 +1,23 @@
|
||||
#!/usr/bin/env bash
|
||||
|
||||
set -e
|
||||
|
||||
if [ $# -eq 0 ]; then
|
||||
echo "Usage: resolve-pr-thread THREAD_ID"
|
||||
echo "Example: resolve-pr-thread PRRT_kwDOABC123"
|
||||
exit 1
|
||||
fi
|
||||
|
||||
THREAD_ID=$1
|
||||
|
||||
gh api graphql -f threadId="$THREAD_ID" -f query='
|
||||
mutation ResolveReviewThread($threadId: ID!) {
|
||||
resolveReviewThread(input: {threadId: $threadId}) {
|
||||
thread {
|
||||
id
|
||||
isResolved
|
||||
path
|
||||
line
|
||||
}
|
||||
}
|
||||
}'
|
||||
@@ -2,6 +2,7 @@
|
||||
name: skill-creator
|
||||
description: Guide for creating effective skills. This skill should be used when users want to create a new skill (or update an existing skill) that extends Claude's capabilities with specialized knowledge, workflows, or tool integrations.
|
||||
license: Complete terms in LICENSE.txt
|
||||
disable-model-invocation: true
|
||||
---
|
||||
|
||||
# Skill Creator
|
||||
|
||||
Reference in New Issue
Block a user