Create Custom Local Skills

This page shows how to turn project documentation into local, reusable OpenCode skills.

Why local skills are useful

If your project has:

business rules
architecture constraints
validation policies
folder conventions
team coding standards

you can package those into .opencode/skills/.../SKILL.md files so the agent stops guessing and starts following your project rules.

Folder structure

.opencode/
└── skills/
    ├── business-logic-expert/
    │   └── SKILL.md
    └── code-standards/
        └── SKILL.md

Strategy

Do not just dump raw documents into a skill. A better pattern is:

Convert narrative docs into explicit rules
Keep each skill focused on one domain
Make each SKILL.md self-contained
Store local skills in the project where they apply

Example: business logic skill

# Business Logic Expert

## Metadata
- **Name:** business-logic-expert
- **Description:** Expert in project-specific business rules

## Instructions for AI
1. Always validate against business rules before implementing features.
2. Never skip validation for quick fixes.
3. Ask for clarification if a new request conflicts with existing rules.

Example: code standards skill

# Code Standards Expert

## Tech Stack
- TypeScript strict mode
- Tailwind CSS
- Server Components by default

## Required Patterns
1. Always validate input before DB operations.
2. Always handle loading and error states.
3. Avoid prohibited patterns like `any` or ad-hoc logging in production.

Security note

If your local skills contain sensitive business logic, exclude them from public repositories.

Example .gitignore addition:

# OpenCode local skills
.opencode/

Best practice

Start with a minimal skill, then grow it as repeated agent mistakes reveal what rules are missing.