Warp Terminal & Oz

Appearance

SOP 002: Skills Setup ​

Fresh
FieldValue
SOP IDSOP-002
Version1.0
StatusActive
Sourcedocs.warp.dev/agent-platform/capabilities/skills

Overview ​

Skills are reusable instruction sets that teach agents how to perform specific tasks. Create custom skills to standardize workflows and share expertise across your team.

Key Concepts ​

  • Automatic discovery - Agents see all available skills and invoke them when appropriate
  • Slash command invocation - Call any skill directly with /{skill-name}
  • Simple markdown format - Skills are just markdown files with YAML frontmatter
  • Supporting files - Include scripts, templates, or configs alongside your skill

Procedure ​

Step 1: Choose a Location ​

ScopePathUse Case
Project.agents/skills/ (recommended)Project-specific workflows, team-shared procedures
Project (alt).warp/skills/, .claude/skills/, .cursor/skills/Compatible with other AI tools
Global~/.agents/skills/Personal workflows used across all projects

Step 2: Create the Directory Structure ​

bash
# Project skill
mkdir -p .agents/skills/my-new-skill

# Global skill
mkdir -p ~/.agents/skills/my-new-skill

Step 3: Write the SKILL.md File ​

Create .agents/skills/my-new-skill/SKILL.md:

markdown
---
name: my-new-skill
description: One-line description of what this skill does and when to use it
---

# My New Skill

## When to use
Explain the scenarios where this skill is helpful.

## Instructions
1. First step the Agent should take
2. Second step with specific details
3. Continue with clear, actionable steps

## Important notes
- Any constraints or requirements
- Common pitfalls to avoid

WARNING

Both name and description fields are required in the YAML frontmatter. The description is how agents decide whether to use your skill.

Step 4: Add Supporting Files (Optional) ​

.agents/skills/
  check-broken-links/
    SKILL.md
    check_links.py      # Supporting script
    config.yaml         # Configuration file

Reference supporting files with relative paths in your SKILL.md:

markdown
## Running the check
python3 .agents/skills/check-broken-links/check_links.py --internal-only

Step 5: Test Your Skill ​

Natural language:

Use the my-new-skill skill to do the thing

Slash command:

/my-new-skill

Step 6: View Available Skills ​

Ask the agent:

What skills do I have?

Or use the slash command /open-skill to browse and edit skills.

Example: Feature Flag Skill ​

markdown
---
name: add-feature-flag
description: Add a new feature flag to the codebase with proper configuration and documentation
---

# Add Feature Flag

## Instructions
1. Ask the user for the feature flag name and default value
2. Add the flag definition to config/feature_flags.yaml
3. Create a helper function in src/utils/flags.ts
4. Update the feature flags documentation in docs/FEATURE_FLAGS.md

## Configuration Format
feature_name:
  default: false
  description: "What this flag controls"
  owner: "team-name"

Skill Name Conflicts ​

InvocationBehavior
Natural languageAgent sees all in-scope skills with paths, chooses appropriately
Slash commandsWarp shows all matching skills in menu for you to select
Background resolutionPrioritizes home directory (global) first, then higher directories

Best Practices ​

  • Write clear, specific descriptions
  • Include exact file paths and command syntax
  • Show concrete usage examples
  • Keep skills focused (one task per skill)
  • Use verb-noun naming (e.g., add-feature-flag, run-migrations)
  • Version control project skills

Pre-built Skills ​

Browse ready-to-use skills at warpdotdev/oz-skills on GitHub.

Verification Checklist ​

  • [ ] SKILL.md has valid YAML frontmatter with name and description
  • [ ] Skill appears when asking "What skills do I have?"
  • [ ] Slash command /{skill-name} shows the skill
  • [ ] Agent follows skill instructions correctly

See Also ​