Creating New Skills

Learn how to create reusable skills instead of repeating prompts, with best practices for structure, triggers, and content organization.

Instead of repeating the same prompts or instructions in every conversation, create a skill that OpenHands can load automatically when needed. Skills transform one-time prompts into reusable, maintainable knowledge that improves over time.

Why Create Skills?

Before (repeating yourself):

Please analyze this code using our company's Python style guide:
- Use black for formatting
- Max line length 88
- Use type hints for all functions
- Follow PEP 8 naming conventions
...

After (using a skill):

Review this Python code

The skill triggers automatically and applies all your style guidelines consistently.

When to Create a Skill

Create a skill when you find yourself:

• Repeating the same instructions across multiple conversations
• Working with domain-specific knowledge (company policies, API schemas, workflows)
• Using the same multi-step procedures repeatedly
• Needing consistent behavior for specific tools or frameworks
• Sharing best practices across a team

Quick Start

Easiest Way: Let OpenHands Help

The simplest way to create a skill is to ask OpenHands to help you:

Create a skill for [your use case]

or simply:

Write a new skill

The skill-creator skill will guide you through an interactive process:

• Asks questions about your use cases and requirements
• Suggests appropriate skill structure (references, scripts, assets)
• Helps you write effective trigger keywords and descriptions
• Ensures you follow best practices automatically
• Creates the complete skill structure for you

This is the recommended approach, especially when you’re starting out.

Manual Approach

If you prefer to create the skill structure manually:

1. Create the skill directory:

   mkdir -p .agents/skills/my-skill
   

2. Create the SKILL.md file:

   touch .agents/skills/my-skill/SKILL.md
   

3. Add content (see structure and guidelines below)

4. Test it by using a trigger keyword in your prompt

Determining Scope

Before writing your skill, define its scope clearly:

Ask These Questions

1. What specific task does this skill handle?

   • ❌ Too broad: “Help with coding”
   • ✅ Focused: “Lint Python code using ruff with our company rules”

2. What knowledge is required?

   • Code style guidelines
   • API documentation
   • Domain-specific schemas
   • Multi-step procedures

3. What resources are needed?

   • Scripts for deterministic tasks
   • Reference documents for detailed information
   • Asset files for templates or boilerplate

4. Who will use this skill?

   • Just you (keep it simple)
   • Your team (add more documentation)
   • Public sharing (comprehensive examples)

Scope Examples

Good scope (focused):

• “Configure pre-commit hooks for Python projects”
• “Generate financial reports using our SQL schema”
• “Deploy to our Kubernetes staging environment”

Poor scope (too broad):

• “Help with Python”
• “Work with databases”
• “Deploy applications”

Choosing Name and Triggers

The skill name and trigger keywords determine when OpenHands loads your skill.

Naming Your Skill

Choose a clear, descriptive name:

• Use lowercase with hyphens: python-linting, k8s-deploy, api-docs
• Be specific: ruff-linter not just linter
• Match common terms: Use vocabulary your users know

Defining Triggers

Triggers are keywords that automatically activate your skill. Choose words users naturally say when they need this skill.

Keyword Triggers

List specific words or phrases that should activate the skill:

---
name: python-linting
description: This skill should be used when the user asks to "lint Python code", "check Python style", "run ruff", or mentions Python code quality.
triggers:
- lint
- linting
- ruff
- code quality
---

Best practices:

• Include 2-5 trigger keywords
• Use terms users actually say
• Include tool names (e.g., “ruff”, “pytest”)
• Include action words (e.g., “lint”, “test”, “deploy”)

Description-Based Triggering

The skill description is crucial for trigger matching. Write it in third person and include specific phrases:

description: This skill should be used when the user asks to "deploy to Kubernetes", "apply K8s manifests", "check pod status", or mentions kubectl commands. Provides comprehensive Kubernetes deployment workflows.

Key elements:

• Start with “This skill should be used when…”
• Quote specific user phrases: “deploy to Kubernetes”
• List concrete scenarios
• Mention related tools or frameworks

Examples of Good Triggers

# API integration skill
triggers:
- stripe
- payment
- checkout

# Database skill
triggers:
- bigquery
- sql query
- data warehouse

# Deployment skill
triggers:
- deploy
- kubernetes
- k8s
- kubectl

Defining the Skill Body

The skill body contains the instructions OpenHands will follow. Write in imperative form (command form) rather than second person.

Basic Structure

---
name: skill-name
description: This skill should be used when...
triggers:
- keyword1
- keyword2
---

# Skill Title

Brief overview of what this skill does.

## Core Instructions

Main procedures and guidelines.

## Common Patterns

Typical use cases and solutions.

## Additional Resources

(Optional) References to bundled files.

Writing Style

Use imperative/infinitive form: ✅ “Check the configuration file” ✅ “Validate input before processing” ✅ “Run tests after deployment”

Avoid second person: ❌ “You should check the configuration” ❌ “You need to validate input” ❌ “You must run tests”

Keep It Focused

SKILL.md content:

• Core concepts and workflows (1,500-2,000 words ideal)
• Essential procedures
• Quick reference information
• Pointers to additional resources

What NOT to include:

• Exhaustive API documentation (use references/ instead)
• Detailed edge cases (use references/ instead)
• Long examples (use references/ instead)

Best Practices and Tips

Use Numbered Step Workflows

For multi-step procedures, use numbered lists:

## Deployment Workflow

1. **Validate the configuration**:
   ```bash
   kubectl apply --dry-run=client -f deployment.yaml

2. Apply to staging:

   kubectl apply -f deployment.yaml -n staging
   

3. Verify pod status:

   kubectl get pods -n staging --watch
   

4. Check logs:

   kubectl logs -f deployment/app-name -n staging
   

**Benefits:**
- Clear sequence for complex workflows
- Easy to follow and verify
- Reduces errors from skipped steps

### Add Large Files as References

Keep SKILL.md lean by moving detailed content to `references/`:

my-skill/ ├── SKILL.md # Core instructions (< 3,000 words) └── references/ ├── api-docs.md # Detailed API reference ├── examples.md # Comprehensive examples └── troubleshooting.md # Edge cases and fixes

**In SKILL.md, reference these files:**

```markdown
## Additional Resources

For detailed information, see:
- **`references/api-docs.md`** - Complete API documentation
- **`references/examples.md`** - Working code examples
- **`references/troubleshooting.md`** - Common issues and solutions

Benefits:

• Keeps context window smaller when skill loads
• OpenHands reads references only when needed
• Easier to maintain and update specific sections

Create Scripts for Predictable Steps

For tasks that are repeatedly rewritten or need deterministic behavior, create executable scripts:

my-skill/
├── SKILL.md
└── scripts/
    ├── validate_config.py
    ├── deploy.sh
    └── rollback.sh

When to use scripts:

• Same code being rewritten repeatedly
• Deterministic reliability required
• Complex parsing or validation
• Multi-step automation

Reference scripts in SKILL.md:

## Validation

Run the validation script:

\`\`\`bash
python3 scripts/validate_config.py config.yaml
\`\`\`

This checks:
- YAML syntax
- Required fields
- Value constraints

Benefits:

• Token efficient (scripts can run without being read)
• Deterministic behavior
• Reusable across projects
• Can be versioned and tested

Include Quick Reference Tables

Use tables for configuration options, command flags, or status codes:

## Configuration Options

| Option | Default | Description |
|--------|---------|-------------|
| `timeout` | 30s | Maximum wait time |
| `retries` | 3 | Number of retry attempts |
| `env` | production | Target environment |

Provide Concrete Examples

Show real examples, not abstract descriptions:

## Example Usage

Deploy the web application:

\`\`\`bash
# Build the image
docker build -t myapp:v1.0 .

# Push to registry
docker push registry.example.com/myapp:v1.0

# Update Kubernetes deployment
kubectl set image deployment/web web=registry.example.com/myapp:v1.0
\`\`\`

Use Progressive Disclosure

Structure information from simple to complex:

1. SKILL.md: Essential workflows and core concepts
2. references/: Detailed patterns, advanced techniques, edge cases
3. scripts/: Automation for predictable tasks
4. assets/: Templates and boilerplate files

Complete Example

Here’s a complete skill for Python code review:

python-review/
├── SKILL.md
├── references/
│   ├── style-guide.md
│   └── common-issues.md
└── scripts/
    └── run-checks.sh

SKILL.md:

---
name: python-review
description: This skill should be used when the user asks to "review Python code", "check Python style", "lint Python", or requests code quality analysis. Provides comprehensive Python code review workflows.
triggers:
- python review
- code review
- lint python
- black
- ruff
---

# Python Code Review

Review Python code using company standards and best practices.

## Review Workflow

1. **Run automated checks**:
   \`\`\`bash
   scripts/run-checks.sh
   \`\`\`

2. **Review linter output** for:
   - Style violations (Black, Ruff)
   - Type errors (mypy)
   - Security issues (bandit)

3. **Check code structure**:
   - Function length (< 50 lines)
   - Complexity (< 10 cyclomatic)
   - Naming conventions

4. **Verify tests**:
   \`\`\`bash
   pytest tests/ --cov=src --cov-report=term
   \`\`\`

## Style Guidelines

- **Formatting**: Black with 88-character line limit
- **Linting**: Ruff with company config
- **Types**: Full type hints for public APIs
- **Docstrings**: Google style for all public functions

## Additional Resources

- **`references/style-guide.md`** - Complete style guide
- **`references/common-issues.md`** - Common mistakes and fixes
- **`scripts/run-checks.sh`** - Automated quality checks

Testing Your Skill

After creating your skill:

1. Verify structure:

   ls .agents/skills/your-skill/SKILL.md
   

2. Check frontmatter: Ensure YAML is valid with name, description, and triggers

3. Test trigger keywords: Use a trigger word in a prompt:

   Help me lint this Python code
   

4. Verify loading: OpenHands should indicate the skill was loaded

5. Iterate: Improve based on actual usage

Common Mistakes to Avoid

Mistake 1: Vague triggers ❌ description: Helps with Python ✅ description: This skill should be used when the user asks to "lint Python code", "run black", or mentions Python code quality

Mistake 2: Everything in SKILL.md ❌ Single 10,000-word SKILL.md ✅ Focused SKILL.md (2,000 words) + references/ for details

Mistake 3: Using “you” in instructions ❌ “You should validate the config” ✅ “Validate the config”

Mistake 4: Missing examples ❌ Abstract descriptions only ✅ Concrete examples with actual commands

Next Steps

• Add your skill to your workspace
• Share skills with the community
• Learn the AgentSkills format for advanced features
• Explore example skills for inspiration

Further Reading

For advanced skill creation techniques and SDK integration:

• Plugins - Bundle multiple skills with hooks and MCP config
• SDK Skills Guide - Programmatic skill creation
• Skills Architecture - Technical details
• Official Skill Registry - Community examples