Skip to main content

Skills

Skills are reusable instruction files that provide specialized workflows for specific tasks. While rules (AGENTS.md) define persistent project-wide behavior, skills are loaded on demand when a particular type of work needs to be done.

How Skills Work​

A skill is a SKILL.md file that contains step-by-step instructions, conventions, and contextual knowledge for a specific procedure. When an agent encounters a task that matches a skill's purpose, it loads the skill using the skill tool, injecting the skill's instructions into its context.

Skill Loading​

Skills are loaded explicitly by the agent. The process:

  1. The agent identifies a task that matches a skill (e.g., "deploy to production" matches the "deployment" skill).
  2. The agent invokes the skill tool with the skill name.
  3. opencode searches the skills directories for a matching SKILL.md file.
  4. The file contents are loaded into the agent's context.
  5. The agent follows the skill's instructions to complete the task.

Skill Locations​

Skills are loaded from two directories, searched in order:

Project Skills​

Place project-specific skills in .opencode/skills/:

.opencode/skills/
  deployment/
    SKILL.md
  migration/
    SKILL.md
  audit/
    SKILL.md
  testing/
    SKILL.md

Global Skills​

Place personal or organization-wide skills in ~/.config/opencode/skills/:

~/.config/opencode/skills/
  docker/
    SKILL.md
  terraform/
    SKILL.md
  security-review/
    SKILL.md

Project skills take precedence over global skills. If both locations define a skill with the same name, the project skill is loaded.

Skill File Structure​

A skill is a standalone Markdown file with a clear, structured format.

Minimal Skill​

# Deployment

Deploy the application to the staging environment.

## Prerequisites
- Docker must be running.
- You must be logged into the container registry.
- The `.env.staging` file must be present.

## Steps
1. Build the Docker image: `docker build -t app:staging .`
2. Tag the image: `docker tag app:staging registry.example.com/app:staging`
3. Push the image: `docker push registry.example.com/app:staging`
4. SSH into the staging server: `ssh deploy@staging.example.com`
5. Pull the image: `docker pull registry.example.com/app:staging`
6. Restart the container: `docker compose up -d`

## Verification
- Check that the container is running: `docker ps`
- Check the health endpoint: `curl https://staging.example.com/health`
- Verify the deployed version matches the build tag.

## Rollback
If the deployment fails health checks:
1. Revert to the previous image tag.
2. Restart the container.
3. Investigate the failure cause before redeploying.

Comprehensive Skill with Context​

# Database Migration

Run and verify database migrations safely.

## When to Use
- Before deploying new code that requires schema changes.
- When rolling back to a previous schema version.
- When setting up a fresh development environment.

## Safety Rules
- Always back up the database before running migrations in production.
- Never run irreversible migrations without a peer review.
- Always run migrations against staging first.
- If a migration fails, stop and investigate before retrying.

## Prerequisites
- Database URL configured in environment.
- Migration tool installed (Drizzle Kit, Prisma, or Knex as appropriate).
- Write access to the target database.

## Migration Steps

### 1. Generate Migration
```bash
npm run db:generate

2. Review Migration SQL​

Open the generated migration file and verify:

  • All column types are correct.
  • Foreign key constraints reference existing tables.
  • No destructive operations on production data.
  • Index names follow the project naming convention.

3. Apply Migration (Staging)​

npm run db:migrate:staging

4. Verify Staging​

  • Check that the application starts without errors.
  • Run the test suite: npm run test -- --run
  • Verify key queries return expected results.
  • Check that existing data is preserved.

5. Apply Migration (Production)​

npm run db:migrate:production

6. Verify Production​

  • Monitor error rates for 5 minutes after migration.
  • Check that the health endpoint returns 200.
  • Verify a sample of read and write operations.

Rollback​

If Migration Has Not Committed​

npm run db:migrate:rollback

If Migration Has Committed​

  1. Generate a reverse migration manually.
  2. Apply it with the same staged process.
  3. Verify data integrity after rollback.

Common Issues​

Lock Wait Timeout​

If the migration fails with a lock wait timeout:

  • Check for long-running queries on the affected tables.
  • Kill blocking processes if safe.
  • Retry the migration during low-traffic hours.

Foreign Key Violation​

If a foreign key constraint fails:

  • Identify the orphaned rows: SELECT * FROM child_table WHERE fk_id NOT IN (SELECT id FROM parent_table)
  • Decide whether to delete or update the orphaned rows.
  • Fix the data before retrying the migration.

## Use Cases

### Deployments

Skills for deployment workflows ensure every deployment follows the same steps, reducing the risk of human error. Create separate skills for staging and production deployments, or a parameterized skill that accepts the target environment.

### Migrations

Database schema migrations, data migrations, and infrastructure migrations benefit from skills because they encode safety checks and rollback procedures that might be forgotten under time pressure.

### Security Audits

A security audit skill can encode the OWASP checklist, project-specific threat models, and review procedures. Every audit is consistent and comprehensive.

### Maintenance Flows

Regular maintenance tasks like log rotation, certificate renewal, dependency updates, and cache invalidation can be encoded as skills so they are performed consistently.

### Onboarding Checks

A skill can encode the steps to verify a new developer's environment setup, reducing the time spent on manual onboarding.

## Creating Skills

### Manual Creation

Create a directory and `SKILL.md` file:

```bash
mkdir -p .opencode/skills/deployment
touch .opencode/skills/deployment/SKILL.md

Then write the skill content following the structure guidelines above.

Naming Conventions​

  • Use descriptive directory names: deployment, database-migration, security-audit.
  • Use lowercase with hyphens for multi-word names.
  • Each skill directory must contain a SKILL.md file.
  • Additional files (scripts, templates, reference docs) can be placed alongside SKILL.md.

Best Practices​

One Concern Per Skill​

Each skill should cover a single procedure or domain. A "deployment" skill should not include database migration steps. Split related but distinct procedures into separate skills.

Include Safety Checks​

Every skill that modifies state should include verification steps and rollback procedures. The agent should be able to confirm success and recover from failure without external guidance.

Be Specific​

Include exact commands, file paths, and environment variable names relevant to your project. Generic instructions force the agent to infer details, which can lead to errors.

Version Skills​

Consider including a version or changelog comment in the skill file so you can track when procedures change:

# Deployment v2.1

## Changelog
- v2.1: Added health check verification step.
- v2.0: Switched from Docker Compose to Kubernetes.
- v1.0: Initial deployment procedure.

Keep Skills Updated​

When your deployment process, migration tooling, or infrastructure changes, update the corresponding skills. Outdated skills will cause agents to follow incorrect procedures.

Test Skills​

Run through a skill manually after creating or updating it to verify all commands and steps are correct. An agent will follow the skill faithfully; errors in the skill will propagate to every execution.