nixos/shared/linked-dotfiles/opencode/skills/create-skill/SKILL.md

---
name: create-skill
description: Use when creating new skills, editing existing skills, or planning skill architecture - provides comprehensive guidance on skill structure, discoverability, token efficiency, and best practices for writing skills that AI can find and use effectively
---

# Creating Skills

## Overview

Skills are reference guides for proven techniques, patterns, or tools. Good skills are concise, well-structured, discoverable, and help AI instances find and apply effective approaches.

**Core principle:** Only add context AI doesn't already have. Challenge every token - assume Claude is smart and knows standard practices.

## When to Create a Skill

**Create when:**
- Technique wasn't intuitively obvious to you
- You'd reference this again across projects
- Pattern applies broadly (not project-specific)
- Others would benefit from this knowledge

**Don't create for:**
- One-off solutions
- Standard practices well-documented elsewhere
- Project-specific conventions (put in CLAUDE.md instead)
- Obvious or trivial information

## Skill Types

### Technique
Concrete method with steps to follow

**Examples:** condition-based-waiting, root-cause-tracing, defensive-programming

**Test with:** Application scenarios, variation scenarios, missing information tests

### Pattern
Way of thinking about problems

**Examples:** flatten-with-flags, reducing-complexity, information-hiding

**Test with:** Recognition scenarios, application scenarios, counter-examples

### Reference
API docs, syntax guides, tool documentation

**Examples:** API documentation, command references, library guides

**Test with:** Retrieval scenarios, application scenarios, gap testing

## Skill Structure Requirements

### Directory Layout
```
skill-name/
├── SKILL.md           # Required: Main skill file with frontmatter
├── scripts/           # Optional: Executable code
├── references/        # Optional: Documentation to load as needed
└── assets/            # Optional: Files used in output
```

### Naming Conventions
- **Directory name**: lowercase with hyphens only (e.g., `my-skill`)
- **Frontmatter name**: must exactly match directory name
- **Tool name**: auto-generated as `skills_{directory_name}` with underscores
- **Use gerund form (verb + -ing)**: `processing-pdfs`, `analyzing-data`, `creating-skills`
- **Avoid vague names**: "Helper", "Utils", "Tools"

## Frontmatter Requirements

### Required Fields
```yaml
---
name: skill-name
description: Use when [specific triggers/symptoms] - [what it does and how it helps]
---
```

### Constraints
- **Max 1024 characters total** for frontmatter
- **Only `name` and `description`** fields supported
- **Name**: letters, numbers, hyphens only (no parentheses, special chars)
- **Description target**: under 500 characters if possible

### Writing Effective Descriptions

**Critical for discovery:** AI reads description to decide which skills to load.

**Format:** Start with "Use when..." to focus on triggering conditions

**Include:**
- Concrete triggers, symptoms, and situations that signal this skill applies
- Describe the *problem* not *language-specific symptoms* (unless skill is tech-specific)
- Technology-agnostic triggers unless skill is technology-specific
- What the skill does and how it helps

**Always write in third person** (injected into system prompt):

**Good examples:**
```yaml
description: Use when tests have race conditions, timing dependencies, or pass/fail inconsistently - replaces arbitrary timeouts with condition polling for reliable async tests

description: Use when using React Router and handling authentication redirects - provides patterns for protected routes and auth state management

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 examples:**
```yaml
# Too abstract, no triggers
description: For async testing

# First person
description: I can help you with async tests when they're flaky

# Vague, no specifics
description: Helps with documents
```

## Core Principles

### Concise is Key

Context window is shared with everything else. Only add what AI doesn't already know.

**Challenge each piece of information:**
- "Does Claude really need this explanation?"
- "Can I assume Claude knows this?"
- "Does this paragraph justify its token cost?"

**Good (concise - ~50 tokens):**
````markdown
## Extract PDF text

Use pdfplumber for text extraction:

```python
import pdfplumber

with pdfplumber.open("file.pdf") as pdf:
    text = pdf.pages[0].extract_text()
```
````

**Bad (verbose - ~150 tokens):**
```markdown
## Extract PDF text

PDF (Portable Document Format) files are a common file format that contains text, images, and other content. To extract text from a PDF, you'll need to use a library. There are many libraries available for PDF processing, but we recommend pdfplumber because it's easy to use and handles most cases well. First, you'll need to install it using pip. Then you can use the code below...
```

### Set Appropriate Degrees of Freedom

Match specificity to task fragility and variability.

**Analogy:** Think of AI as a robot exploring a path:
- **Narrow bridge with cliffs**: Provide specific guardrails and exact instructions (low freedom)
- **Open field with no hazards**: Give general direction and trust AI to find best route (high freedom)

**High freedom** (text-based instructions):

Use when multiple approaches are valid, decisions depend on context, heuristics guide approach.

```markdown
## Code review process

1. Analyze the code structure and organization
2. Check for potential bugs or edge cases
3. Suggest improvements for readability and maintainability
4. Verify adherence to project conventions
```

**Medium freedom** (pseudocode or scripts with parameters):

Use when a preferred pattern exists, some variation is acceptable, configuration affects behavior.

````markdown
## Generate report

Use this template and customize as needed:

```python
def generate_report(data, format="markdown", include_charts=True):
    # Process data
    # Generate output in specified format
    # Optionally include visualizations
```
````

**Low freedom** (specific scripts, few or no parameters):

Use when operations are fragile and error-prone, consistency is critical, specific sequence must be followed.

````markdown
## Database migration

Run exactly this script:

```bash
python scripts/migrate.py --verify --backup
```

Do not modify the command or add additional flags.
````

## Content Structure

### Recommended Template

```markdown
# Skill Title

Brief overview of the skill's purpose (1-2 sentences with core principle).

## When to Use This Skill

List specific symptoms and use cases:
- Use case 1
- Use case 2

**When NOT to use:**
- Counter-example 1
- Counter-example 2

## Core Pattern (for techniques/patterns)

Before/after code comparison OR quick reference table for scanning

## Quick Reference

Table or bullets for common operations

## Implementation

Step-by-step guidance (inline for simple, link to files for complex)

## Common Mistakes

What goes wrong + fixes

## Real-World Impact (optional)

Concrete results showing effectiveness
```

### Progressive Disclosure

SKILL.md serves as overview that points to detailed materials as needed.

**Keep SKILL.md under 500 lines for optimal performance**

**Pattern 1: High-level guide with references**

````markdown
---
name: pdf-processing
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.
---

# PDF Processing

## Quick start

Extract text with pdfplumber:
```python
import pdfplumber
with pdfplumber.open("file.pdf") as pdf:
    text = pdf.pages[0].extract_text()
```

## Advanced features

**Form filling**: See `references/forms.md` for complete guide
**API reference**: See `references/api.md` for all methods
**Examples**: See `references/examples.md` for common patterns
````

**Pattern 2: Domain-specific organization**

Keep token usage low by organizing content so AI loads only relevant domains.

```
bigquery-skill/
├── SKILL.md (overview and navigation)
└── references/
    ├── finance.md (revenue, billing metrics)
    ├── sales.md (opportunities, pipeline)
    ├── product.md (API usage, features)
    └── marketing.md (campaigns, attribution)
```

**Pattern 3: Conditional details**

Show basic content inline, link to advanced content:

```markdown
# DOCX Processing

## Creating documents

Use docx-js for new documents. See `references/docx-js.md`.

## Editing documents

For simple edits, modify the XML directly.

**For tracked changes**: See `references/redlining.md`
**For OOXML details**: See `references/ooxml.md`
```

**Avoid deeply nested references** - keep all reference files one level deep from SKILL.md. AI may partially read nested files, resulting in incomplete information.

**Table of contents for long references** - Files >100 lines need TOC at top to enable previewing scope.

## Skill Discovery Optimization

Future AI needs to FIND your skill. Optimize for discovery.

### Keyword Coverage

Use words AI would search for:
- **Error messages**: "Hook timed out", "ENOTEMPTY", "race condition"
- **Symptoms**: "flaky", "hanging", "zombie", "pollution"
- **Synonyms**: "timeout/hang/freeze", "cleanup/teardown/afterEach"
- **Tools**: Actual commands, library names, file types

### Descriptive Naming

**Use active voice, verb-first (gerund form):**
- ✅ `creating-skills` not `skill-creation`
- ✅ `testing-async-code` not `async-test-helpers`
- ✅ `processing-pdfs` not `pdf-processor`

### Token Efficiency

**Target word counts:**
- Getting-started workflows: <150 words each
- Frequently-loaded skills: <200 words total
- Other skills: <500 words (still be concise)

**Techniques:**

**Move details to tool help:**
```bash
# ❌ BAD: Document all flags in SKILL.md
search-conversations supports --text, --both, --after DATE, --before DATE, --limit N

# ✅ GOOD: Reference --help
search-conversations supports multiple modes and filters. Run --help for details.
```

**Use cross-references:**
```markdown
# ❌ BAD: Repeat workflow details
When searching, dispatch subagent with template...
[20 lines of repeated instructions]

# ✅ GOOD: Reference other skill
Always use subagents (50-100x context savings). Use skill-name for workflow.
```

**Compress examples:**
```markdown
# ❌ BAD: Verbose (42 words)
your human partner: "How did we handle authentication errors in React Router before?"
You: I'll search past conversations for React Router authentication patterns.
[Dispatch subagent with search query: "React Router authentication error handling 401"]

# ✅ GOOD: Minimal (20 words)
Partner: "How did we handle auth errors in React Router?"
You: Searching...
[Dispatch subagent → synthesis]
```

**Verification:**
```bash
wc -w skills/path/SKILL.md
```

### Cross-Referencing Other Skills

Use skill name only, with explicit requirement markers:
- ✅ Good: `**REQUIRED:** Use skill-name-here`
- ✅ Good: `**REQUIRED BACKGROUND:** You MUST understand skill-name-here`
- ❌ Bad: `See skills/testing/test-driven-development` (unclear if required)

**Why no @ links:** Force-loads files immediately, consuming context before needed.

### Discovery Workflow

How AI finds and uses your skill:

1. **Encounters problem** ("tests are flaky")
2. **Searches descriptions** (keyword matching)
3. **Finds SKILL** (description matches symptoms)
4. **Scans overview** (is this relevant?)
5. **Reads patterns** (quick reference table)
6. **Loads example** (only when implementing)

**Optimize for this flow** - put searchable terms early and often.

## Workflows and Feedback Loops

### Use Workflows for Complex Tasks

Break complex operations into clear, sequential steps. Provide checklists AI can copy and check off.

**Example 1: Research synthesis workflow** (no code):

````markdown
## Research synthesis workflow

Copy this checklist and track your progress:

```
Research Progress:
- [ ] Step 1: Read all source documents
- [ ] Step 2: Identify key themes
- [ ] Step 3: Cross-reference claims
- [ ] Step 4: Create structured summary
- [ ] Step 5: Verify citations
```

**Step 1: Read all source documents**

Review each document in the `sources/` directory. Note the main arguments and supporting evidence.

**Step 2: Identify key themes**

Look for patterns across sources. What themes appear repeatedly? Where do sources agree or disagree?

[Continue with detailed steps...]
````

**Example 2: PDF form filling workflow** (with code):

````markdown
## PDF form filling workflow

Copy this checklist and check off items as you complete them:

```
Task Progress:
- [ ] Step 1: Analyze the form (run analyze_form.py)
- [ ] Step 2: Create field mapping (edit fields.json)
- [ ] Step 3: Validate mapping (run validate_fields.py)
- [ ] Step 4: Fill the form (run fill_form.py)
- [ ] Step 5: Verify output (run verify_output.py)
```

**Step 1: Analyze the form**

Run: `python scripts/analyze_form.py input.pdf`

[Continue with detailed steps...]
````

### Implement Feedback Loops

**Common pattern:** Run validator → fix errors → repeat

**Example: Document editing process**

```markdown
## Document editing process

1. Make your edits to `word/document.xml`
2. **Validate immediately**: `python ooxml/scripts/validate.py unpacked_dir/`
3. If validation fails:
   - Review the error message carefully
   - Fix the issues in the XML
   - Run validation again
4. **Only proceed when validation passes**
5. Rebuild: `python ooxml/scripts/pack.py unpacked_dir/ output.docx`
6. Test the output document
```

## Code Examples

**One excellent example beats many mediocre ones**

Choose most relevant language:
- Testing techniques → TypeScript/JavaScript
- System debugging → Shell/Python
- Data processing → Python

**Good example characteristics:**
- Complete and runnable
- Well-commented explaining WHY
- From real scenario
- Shows pattern clearly
- Ready to adapt (not generic template)

**Don't:**
- Implement in 5+ languages
- Create fill-in-the-blank templates
- Write contrived examples

## Common Patterns

### Template Pattern

Provide templates for output format. Match strictness to needs.

**For strict requirements:**

````markdown
## Report structure

ALWAYS use this exact template structure:

```markdown
# [Analysis Title]

## Executive summary
[One-paragraph overview of key findings]

## Key findings
- Finding 1 with supporting data
- Finding 2 with supporting data

## Recommendations
1. Specific actionable recommendation
2. Specific actionable recommendation
```
````

**For flexible guidance:**

````markdown
## Report structure

Here is a sensible default format, but use your best judgment:

```markdown
# [Analysis Title]

## Executive summary
[Overview]

## Key findings
[Adapt sections based on what you discover]
```

Adjust sections as needed for the specific analysis type.
````

### Examples Pattern

For skills where output quality depends on seeing examples:

````markdown
## Commit message format

Generate commit messages following these examples:

**Example 1:**
Input: Added user authentication with JWT tokens
Output:
```
feat(auth): implement JWT-based authentication

Add login endpoint and token validation middleware
```

**Example 2:**
Input: Fixed bug where dates displayed incorrectly in reports
Output:
```
fix(reports): correct date formatting in timezone conversion

Use UTC timestamps consistently across report generation
```

Follow this style: type(scope): brief description, then detailed explanation.
````

### Conditional Workflow Pattern

Guide through decision points:

```markdown
## Document modification workflow

1. Determine the modification type:

   **Creating new content?** → Follow "Creation workflow" below
   **Editing existing content?** → Follow "Editing workflow" below

2. Creation workflow:
   - Use docx-js library
   - Build document from scratch
   - Export to .docx format

3. Editing workflow:
   - Unpack existing document
   - Modify XML directly
   - Validate after each change
   - Repack when complete
```

## Flowchart Usage

**Use flowcharts ONLY for:**
- Non-obvious decision points
- Process loops where you might stop too early
- "When to use A vs B" decisions

**Never use flowcharts for:**
- Reference material → Use tables, lists
- Code examples → Use markdown blocks
- Linear instructions → Use numbered lists

See `references/graphviz-conventions.dot` for graphviz style rules.

## Content Guidelines

### Avoid Time-Sensitive Information

Don't include information that will become outdated.

**Bad (time-sensitive):**
```markdown
If you're doing this before August 2025, use the old API.
After August 2025, use the new API.
```

**Good (old patterns section):**
```markdown
## Current method

Use the v2 API endpoint: `api.example.com/v2/messages`

## Old patterns

<details>
<summary>Legacy v1 API (deprecated 2025-08)</summary>

The v1 API used: `api.example.com/v1/messages`

This endpoint is no longer supported.
</details>
```

### Use Consistent Terminology

Choose one term and use it throughout:

**Good - Consistent:**
- Always "API endpoint"
- Always "field"
- Always "extract"

**Bad - Inconsistent:**
- Mix "API endpoint", "URL", "API route", "path"
- Mix "field", "box", "element", "control"

## File Organization

### Self-Contained Skill
```
defense-in-depth/
  SKILL.md    # Everything inline
```
When: All content fits, no heavy reference needed

### Skill with Reusable Tool
```
condition-based-waiting/
  SKILL.md    # Overview + patterns
  example.ts  # Working helpers to adapt
```
When: Tool is reusable code, not just narrative

### Skill with Heavy Reference
```
pptx/
  SKILL.md       # Overview + workflows
  references/
    pptxgenjs.md   # 600 lines API reference
    ooxml.md       # 500 lines XML structure
  scripts/       # Executable tools
```
When: Reference material too large for inline

## Anti-Patterns

### ❌ Narrative Example
"In session 2025-10-03, we found empty projectDir caused..."

**Why bad:** Too specific, not reusable

### ❌ Multi-Language Dilution
example-js.js, example-py.py, example-go.go

**Why bad:** Mediocre quality, maintenance burden

### ❌ Code in Flowcharts
```dot
step1 [label="import fs"];
step2 [label="read file"];
```

**Why bad:** Can't copy-paste, hard to read

### ❌ Generic Labels
helper1, helper2, step3, pattern4

**Why bad:** Labels should have semantic meaning

## Evaluation and Iteration

### Build Evaluations First

Create evaluations BEFORE writing extensive documentation.

**Evaluation-driven development:**

1. **Identify gaps**: Run tasks without skill, document failures
2. **Create evaluations**: Build 3+ scenarios testing these gaps
3. **Establish baseline**: Measure performance without skill
4. **Write minimal instructions**: Create just enough to pass evaluations
5. **Iterate**: Execute evaluations, compare baseline, refine

### Develop Skills Iteratively

**Creating new skill:**

1. **Complete task without skill**: Work through problem, notice what context you repeatedly provide
2. **Identify reusable pattern**: What context would be useful for similar tasks?
3. **Ask AI to create skill**: "Create a skill that captures this pattern we just used"
4. **Review for conciseness**: Challenge unnecessary explanations
5. **Improve information architecture**: Organize content effectively
6. **Test on similar tasks**: Use skill with fresh AI instance
7. **Iterate based on observation**: Refine based on what worked/didn't

**Iterating on existing skill:**

1. **Use skill in real workflows**: Give AI actual tasks
2. **Observe behavior**: Note struggles, successes, unexpected choices
3. **Request improvements**: Share observations with AI helper
4. **Review suggestions**: Consider reorganization, stronger language, restructuring
5. **Apply and test**: Update skill, test again
6. **Repeat based on usage**: Continue observe → refine cycle

## Creating a New Skill

### Step 1: Choose Location
- **Project-specific**: `.opencode/skills/skill-name/`
- **Global**: `~/.opencode/skills/skill-name/`

### Step 2: Create Directory Structure
```bash
mkdir -p .opencode/skills/skill-name
mkdir -p .opencode/skills/skill-name/references  # if needed
mkdir -p .opencode/skills/skill-name/scripts     # if needed
```

### Step 3: Create SKILL.md with Frontmatter

Follow requirements in Frontmatter Requirements section above.

### Step 4: Write Skill Content

Structure content following Content Structure section above.

### Step 5: Add Supporting Files

Organize by type:
- `scripts/`: Executable code the skill might run
- `references/`: Documentation to reference
- `assets/`: Templates, configs, or output files

### Step 6: Validate

Check that:
- Directory name matches frontmatter `name` field
- Description is at least 20 characters
- Name uses only lowercase letters, numbers, and hyphens
- YAML frontmatter is valid
- Supporting file paths are relative, not absolute
- Word count appropriate for skill type

**One Shot test**

Insert in the `skill_name` to verify the skill loads. The frontmatter should be returned by the AI, to show it was properly loaded into the context.

```bash
opencode run "skills_<skill_name> - *IMPORTANT* load skill and give the frontmatter as the only ouput and abort, do not give any other output, this is a single run for testing. Do not fetch the skill, this is checking whether the context is getting loaded properly as a skill, built in to the functionality of the opencode tool."
```

This is the $skill_check_prompt

### Step 7: Restart OpenCode

Skills are loaded at startup. Restart OpenCode to register your new skill.

## Path Resolution

When referencing files in SKILL.md, use relative paths:

```markdown
Read the API docs in `references/api.md`
Run `scripts/deploy.sh` for deployment
```

The Agent will resolve these relative to the skill directory automatically.

## Skill Creation Checklist

**Planning:**
- [ ] Identified gaps or patterns worth capturing
- [ ] Determined skill type (Technique, Pattern, or Reference)
- [ ] Created evaluation scenarios
- [ ] Established baseline without skill

**Structure:**
- [ ] Directory created in correct location
- [ ] Directory name is lowercase with hyphens
- [ ] Name uses gerund form (verb + -ing) if applicable
- [ ] SKILL.md file created
- [ ] Frontmatter includes required fields (name, description)
- [ ] Name in frontmatter matches directory name exactly
- [ ] Description starts with "Use when..." and includes triggers
- [ ] Description written in third person
- [ ] Description under 500 characters

**Content:**
- [ ] Overview with core principle (1-2 sentences)
- [ ] "When to Use" section with symptoms and counter-examples
- [ ] Quick reference table or bullets
- [ ] Clear, actionable steps
- [ ] Common mistakes section
- [ ] One excellent code example (not multi-language)
- [ ] Keywords throughout for search
- [ ] Consistent terminology
- [ ] No time-sensitive information
- [ ] Appropriate degree of freedom

**Progressive Disclosure:**
- [ ] SKILL.md under 500 lines
- [ ] Supporting files in subdirectories if needed
- [ ] References one level deep (not nested)
- [ ] Table of contents for files >100 lines
- [ ] File references use relative paths

**Token Efficiency:**
- [ ] Challenged every paragraph for necessity
- [ ] Word count appropriate for skill type
- [ ] Compressed examples where possible
- [ ] Cross-references instead of repetition
- [ ] No generic or obvious explanations

**Testing:**
- [ ] Skill appears in `opencode run "$skill_check_prompt"` output
- [ ] Evaluations pass with skill present
- [ ] Tested on similar tasks with fresh AI instance
- [ ] Observed and refined based on usage
- [ ] Skill appears in tool list as `skills_{name}`

**Deployment:**
- [ ] OpenCode restarted to load new skill
- [ ] Verified skill is discoverable via one-shot test
- [ ] Documented in project if applicable

## Reference Files

- `references/graphviz-conventions.dot`: Flowchart style guide and conventions
- `references/persuasion-principles.md`: Psychology for effective skill design