11. Skills and SKILL.md

11.1 What is a skill?

A skill is a reusable set of instructions for a specialized task.

OpenCode discovers skills and loads them on demand through its skill mechanism.

Examples:

• API testing
• Git release
• Security review
• Documentation
• Cloud deployment

11.2 Skill structure

A project skill can be structured like:

.opencode/
└── skills/
    └── api-testing/
        └── SKILL.md

The skill directory name becomes the skill identifier.

11.3 Example SKILL.md

---
description: Standard API testing workflow
---

# API Testing

When testing an API:

1. Identify endpoints.
2. Identify authentication.
3. Test successful requests.
4. Test invalid input.
5. Test missing authentication.
6. Test authorization failures.
7. Test malformed requests.
8. Test boundary conditions.
9. Verify response status codes.
10. Verify response schemas.
11. Report failures clearly.

11.4 Skill vs AGENTS.md

AGENTS.md

Project-wide guidance:

How should the agent work in this repository?

SKILL.md

Specialized procedure:

How should the agent perform this particular task?

11.5 Supporting files

A skill can be more than one Markdown file.

For example:

.opencode/
└── skills/
    └── api-testing/
        ├── SKILL.md
        ├── checklist.md
        └── examples/
            └── api-example.md

The main skill can instruct the agent to read supporting files when needed.

11.6 Skill permissions

OpenCode supports permissions for skills.

A safe pattern is to explicitly control which skills agents can load, especially for sensitive or experimental procedures.

Exercise

Create three skills:

api-testing
security-review
documentation

Give each:

• Description
• Purpose
• Procedure
• Verification
• Expected output