> ## Documentation Index
> Fetch the complete documentation index at: https://docs.openhands.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# 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

### Automated Approach: Let OpenHands Help

To create a skill with guided assistance, ask OpenHands to help you:

```
Create a skill for [your use case]
```

or simply:

```
Write a new skill
```

The `skill-creator` skill (from the [OpenHands public skills library](https://github.com/OpenHands/extensions/tree/main/skills/skill-creator)) 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**:
   ```bash theme={null}
   mkdir -p .agents/skills/my-skill
   ```

2. **Create the SKILL.md file**:
   ```bash theme={null}
   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.

<AccordionGroup>
  <Accordion title="Keyword Triggers">
    List specific words or phrases that should activate the skill:

    ```yaml theme={null}
    ---
    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")
  </Accordion>

  <Accordion title="Description-Based Triggering">
    The skill description is crucial for trigger matching. Write it in third person and include specific phrases:

    ```yaml theme={null}
    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
  </Accordion>
</AccordionGroup>

### Examples of Good Triggers

```yaml theme={null}
# API integration skill
triggers:
- stripe
- payment
- checkout
```

```yaml theme={null}
# Database skill
triggers:
- bigquery
- sql query
- data warehouse
```

```yaml theme={null}
# 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

```markdown theme={null}
---
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:

````markdown theme={null}
## Deployment Workflow

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

2. **Apply to staging**:
   ```bash theme={null}
   kubectl apply -f deployment.yaml -n staging
   ```

3. **Verify pod status**:
   ```bash theme={null}
   kubectl get pods -n staging --watch
   ```

4. **Check logs**:
   ```bash theme={null}
   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:**

```markdown theme={null}
## 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:

```markdown theme={null}
## 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:

```markdown theme={null}
## 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:**

```markdown theme={null}
---
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**:
   ```bash theme={null}
   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

<Info>
  For production deployments, see [Monitoring and Improving Skills](/overview/skills/monitoring) to track performance using logging, evaluation metrics, dashboarding, and automated feedback aggregation.
</Info>

## Common Mistakes to Avoid

<Warning>
  **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`
</Warning>

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

<Warning>
  **Mistake 3: Using "you" in instructions**
  ❌ "You should validate the config"
  ✅ "Validate the config"
</Warning>

<Warning>
  **Mistake 4: Missing examples**
  ❌ Abstract descriptions only
  ✅ Concrete examples with actual commands
</Warning>

## Next Steps

* **[Add your skill](/overview/skills/adding)** to your workspace
* **[Monitor skill performance](/overview/skills/monitoring)** in production
* **[Share skills](https://github.com/OpenHands/extensions)** with the community
* **[Learn the AgentSkills format](/sdk/guides/skill)** for advanced features
* **[Explore example skills](https://github.com/OpenHands/extensions)** for inspiration

## Further Reading

For advanced skill creation techniques and SDK integration:

* **[Monitoring Skills](/overview/skills/monitoring)** - Track performance and improve skills in production
* **[Plugins](/overview/plugins)** - Bundle multiple skills with hooks and MCP config
* **[SDK Skills Guide](/sdk/guides/skill)** - Programmatic skill creation
* **[Observability & Tracing](/sdk/guides/observability)** - OpenTelemetry configuration details
* **[GitHub Workflows](/sdk/guides/github-workflows/pr-review)** - Automate skills in CI/CD pipelines
* **[Skills Architecture](/sdk/arch/skill)** - Technical details
* **[Official Skill Registry](https://github.com/OpenHands/extensions)** - Community examples