Skip to main content

Skills

tip

Skills encode repeatable procedures so the agent performs complex tasks consistently every time.

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

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

:::tip
Deployments benefit from skills because every deploy follows the same verified steps.
:::

### Migrations



### Security Audits



### 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



## 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​

Include Safety Checks​

Be Specific​

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​

Test Skills​