Update Skill

update-skill

This guide provides instructions for creating or updating skills in this repository. It covers the required structure, frontmatter, and best practices for skills.

Quick Start

Every skill is a directory containing a SKILL.md file with YAML frontmatter and markdown body:

---
name: pdf-processing
description: Extract text and tables from PDF files, fill forms, merge documents.
---

# PDF Processing

## When to use this skill
Use this skill when the user needs to work with PDF files...

## How to extract text
1. Use pdfplumber for text extraction...

## How to fill forms
...

Requirements

Frontmatter (Required)

Every SKILL.md must start with YAML frontmatter containing:

• name: Kebab-case identifier (lowercase letters, numbers, hyphens only)
• Example: add-feature-flag, pdf-processing, update-skill
• description: Specific description of what the skill does and when to use it
• Must be non-empty
• Should include key terms for skill discovery
• Begin with an action verb to clearly state what the skill accomplishes (e.g., "Adds feature flags..." instead of "Helps with features..."), and immediately follow with a specific use case or context (e.g., "Use when working with feature flags")
• Write in third person (e.g., "Adds feature flags..." not "I can help you add...")

Writing Effective Descriptions

The description field is critical for skill discovery. Include both what the skill does and when to use it. Some good examples:

• git-commit: "Generate descriptive commit messages by analyzing git diffs. Use when the user asks for help writing commit messages or reviewing staged changes."
• pdf-processing: "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 like "Helps with code" or "Does development tasks". For more context, see "Description Best Practices" in references/best-practices.md.

Skill Structure

Typical sections in Warp skills:

1. Title and brief summary – Clear title and a concise overview of the skill's purpose and primary use cases. Link to sections, reference files or related skills if useful 2. Overview - Context about the skill's purpose (optional but common), extends the summary with more details and context 3. Main content - Steps, usage instructions, or workflow guidance 4. Best Practices - Guidelines and recommendations (optional) 5. Examples / Reference PRs - Links to real examples (optional)

Keep the structure flexible based on the skill's needs. Simple skills can omit the optional sections.

Validation

Optionally, use the skills-ref reference library to validate your skills:

skills-ref validate ./my-skill

This checks that your SKILL.md frontmatter is valid and follows all naming conventions. If not installed, use the WebSearch tool to get context around this package.

Main Content Best Practices

• For guidance on what qualifies as good main content, see "Conciseness Principles" in references/best-practices.md
• When formatting code examples, see "Code Example Formatting" in references/best-practices.md.

File Organization

• Simple skills (<=200 lines): Keep everything in SKILL.md
• Complex skills (>200 lines): Split detailed content into references/ subdirectory
• Reference files from SKILL.md with clear links
• Example: "See references/best-practices.md for detailed guidance"

When to Split Content

Create references/ subdirectory when:

• SKILL.md approaches 200+ lines
• Skill covers multiple domains or workflows that can be loaded independently
• Detailed reference material would clutter the main instructions

Keep only essential workflow and procedural instructions in SKILL.md. Move detailed reference material, schemas, and extensive examples to references/ files.

Examples from Existing Skills

For reference on structure and style:

• .agents/skills/add-feature-flag/SKILL.md - Multi-step workflow with clear sequential steps
• .agents/skills/remove-feature-flag/SKILL.md - Cleanup workflow with search commands

Best Practices

See references/best-practices.md for detailed authoring guidance including:

• Progressive disclosure patterns
• Writing concise, effective instructions
• Code example formatting
• Common anti-patterns to avoid

Best Practices for Warp Skills

Detailed authoring guidance for creating effective skills in .agents/skills/.

Progressive Disclosure

Skills use a loading system to manage context efficiently:

1. Metadata (name + description) - Always loaded at startup 2. SKILL.md body - Loaded when skill triggers 3. Reference files - Loaded only when needed

When to Use References

Keep SKILL.md under 150-200 lines. When content grows beyond this:

Pattern 1: High-level guide with references

SKILL.md contains the core workflow and points to detailed references:

## Advanced Features

- **Detailed configuration**: See [references/config.md](references/config.md)
- **API reference**: See [references/api.md](references/api.md)
- **Examples**: See [references/examples.md](references/examples.md)

Pattern 2: Domain-specific organization

For skills with multiple independent domains, organize by domain:

skill-name/
├── SKILL.md (overview and navigation)
└── references/
    ├── domain-a.md
    ├── domain-b.md
    └── domain-c.md

When the user works with domain-a, the agent only loads domain-a.md, not the others.

Pattern 3: Conditional details

Show basic content inline, link to advanced content:

## Basic Usage

[Core instructions here]

**For advanced configuration**: See [references/advanced.md](references/advanced.md)

Important Guidelines

• Keep references one level deep - All reference files should link directly from SKILL.md
• Avoid nested references - Don't create references that reference other files
• Add table of contents - For reference files >100 lines, include TOC at the top

Writing Effective Descriptions

The description field enables skill discovery. the agent uses it to decide when to load the skill.

Description Best Practices

1. Be specific and include key terms

• Good: "Add a new feature flag to gate code changes in the Warp codebase."
• Avoid: "Helps with features."

2. Include both what and when

• What the skill does: "Write, improve, and run Rust unit tests"
• When to use it: "in the warp Rust codebase"

3. Write in third person

• Good: "Adds feature flags to gate code changes"
• Avoid: "I can help you add feature flags"
• Avoid: "You can use this to add feature flags"

4. Include trigger terms

• Mention specific files, commands, or concepts
• Example: "Use when working with PDF files, forms, or document extraction"

Conciseness Principles

Context window is shared across all skills, conversation history, and the system prompt. Every token matters.

Default Assumption: Agent is Already Smart

Only add context the agent doesn't already have. Challenge each piece:

• "Does the agent really need this explanation?"
• "Can I assume the agent knows this?"
• "Does this paragraph justify its token cost?"

Good (concise):

## 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):

## 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...

The concise version assumes the agent knows what PDFs are and how libraries work.

Code Example Formatting

Syntax Highlighting

Always specify the language for code blocks:

pub fn example() {
    println!("Always specify language");
}

cargo nextest run --workspace

Example Structure

For workflow-based skills, show before/after or step-by-step:

### Before:
\`\`\`rust
if FeatureFlag::YourFeature.is_enabled() {
    // new behavior
} else {
    // old behavior (dead code)
}
\`\`\`

### After:
\`\`\`rust
// new behavior (unconditionally enabled)
\`\`\`

Inline Commands

For shell commands, show the complete command with flags:

cargo clippy --workspace --all-targets --all-features --tests -- -D warnings

Explain non-obvious flags if necessary, but prefer self-documenting commands.

Workflows vs Simple Instructions

When to Use Workflows

Use numbered steps for multi-step processes where order matters:

## Workflow

1. Analyze the form structure
2. Create field mapping
3. Validate mapping
4. Fill the form
5. Verify output

Include a checklist for complex workflows:

Copy this checklist and track progress:

\`\`\`
Task Progress:
- [ ] Step 1: Analyze form
- [ ] Step 2: Create mapping
- [ ] Step 3: Validate
- [ ] Step 4: Fill form
- [ ] Step 5: Verify
\`\`\`

When to Use Simple Instructions

For straightforward tasks, skip the workflow structure:

## Adding a Feature Flag

Add the feature to `app/Cargo.toml`:

\`\`\`toml
[features]
your_feature_name = []
\`\`\`

Then gate code with the runtime check:

\`\`\`rust
if FeatureFlag::YourFeatureName.is_enabled() {
    // feature-gated behavior
}
\`\`\`

Common Anti-Patterns

❌ Windows-Style Paths

Always use forward slashes:

• ✓ Good: scripts/helper.py, references/guide.md
• ✗ Avoid: scripts\helper.py, references\guide.md

❌ Vague Descriptions

Be specific:

• ✗ Avoid: "Helps with documents"
• ✓ Good: "Extract text and tables from PDF files"

❌ Too Many Options

Don't present multiple approaches unless necessary:

• ✗ Avoid: "You can use pypdf, or pdfplumber, or PyMuPDF, or..."
• ✓ Good: "Use pdfplumber for text extraction. For scanned PDFs requiring OCR, use pdf2image with pytesseract instead."

❌ Time-Sensitive Information

Don't include dates or version-specific guidance:

• ✗ Avoid: "If you're doing this before August 2025, use the old API."
• ✓ Good: Use a "Current method" and "Old patterns" section with deprecation notes

❌ Inconsistent Terminology

Choose one term and use it throughout:

• ✗ Avoid: Mix "API endpoint", "URL", "API route", "path"
• ✓ Good: Always "API endpoint"

❌ Explaining the Obvious

Skip explanations for concepts the agent already knows:

• ✗ Avoid: "Git is a version control system that tracks changes in files..."
• ✓ Good: "Use git --no-pager diff to see changes without pagination"

❌ Over-Structuring Simple Skills

Not every skill needs an Overview, Best Practices, and Examples section. Use only what adds value:

• Simple skills: Title + instructions
• Medium skills: Title + Overview + instructions
• Complex skills: Full structure with multiple sections

Naming Conventions

Use consistent naming patterns for skills:

Recommended: Gerund form (verb + -ing)

• processing-pdfs
• analyzing-spreadsheets
• managing-databases
• testing-code

Acceptable alternatives:

• Noun phrases: pdf-processing, spreadsheet-analysis
• Action-oriented: process-pdfs, analyze-spreadsheets

Avoid:

• Vague names: helper, utils, tools
• Overly generic: documents, data, files

Consistent naming makes skills easier to reference, understand at a glance, and organize.

Skill Iteration

Skills improve through usage. When updating a skill:

1. Observe usage - Note where the agent struggles or succeeds 2. Identify gaps - What information was missing or unclear? 3. Update targeted sections - Fix specific issues without over-explaining 4. Test changes - Use the skill on similar tasks to verify improvements

Keep iterations focused. Don't add content preemptively—only add what's proven necessary through real usage.