john/claude-engineering-plugin
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Reduce context token usage by 79% — fix silent component exclusion (#161)

Browse Source 
* 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
2026-02-08 22:28:51 -06:00
committed by GitHub
parent 04ee7e4506
commit f744b797ef
71 changed files with 1765 additions and 767 deletions
Download Patch File Download Diff File Expand all files Collapse all files

205
plugins/compound-engineering/skills/create-agent-skills/references/official-spec.md
View File

@@ -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

436
plugins/compound-engineering/skills/create-agent-skills/references/skill-structure.md
View File

@@ -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