Smithery is now a part of Arcade.dev! Read more in our announcement here

opencode-skills

justinlevinedotme/opencode-skills

Productivity

About

SKILL.md

opencode-skills

justinlevinedotme/opencode-skills

Productivity

About

Create and manage OpenCode skills with proper SKILL.md format, frontmatter, and organization...

SKILL.md

Create loadable knowledge modules that enhance agent capabilities.

A skill is a markdown file that provides specialized knowledge, workflows, or tool integrations. Skills are loaded on-demand via the skill tool when needed.

Skill Fundamentals

Location

Scope	Path
Project	`.opencode/skill/<name>/SKILL.md`
Global	`~/.config/opencode/skill/<name>/SKILL.md`

CRITICAL: The folder name MUST match the name in frontmatter.

Directory Structure

.opencode/skill/my-skill/
├── SKILL.md           # REQUIRED - Main skill definition
├── scripts/           # Optional - Executable scripts
│   └── validate.sh
├── references/        # Optional - Reference documents
│   └── schema.md
└── assets/            # Optional - Images, data files
    └── diagram.png

Naming Rules

Rule	Valid	Invalid
Lowercase	`my-skill`	`My-Skill`
Alphanumeric + hyphen	`api-client`	`api_client`
Match folder name	`foo/SKILL.md` with `name: foo`	Mismatch

Frontmatter Schema

---
name: my-skill-name          # REQUIRED, MUST match folder name
description: |-              # REQUIRED, 1-1024 characters
  [Capability summary]. Use for [use cases].
  
  Use proactively when [trigger contexts].
  
  Examples:
  - user: "query" → action
  - user: "another query" → action
---

Description Pattern

The description MUST have three parts:

Capability statement: What the skill does (1-2 sentences)
Trigger contexts: "Use proactively when [conditions]"
Examples: user: "query" → action format

description: |-
  Generate comprehensive API documentation from source code. Use for documenting REST endpoints, GraphQL schemas, and SDK methods.
  
  Use proactively when user says "document API", "generate docs", "API reference", or asks about endpoint documentation.
  
  Examples:
  - user: "Document this FastAPI app" → analyze routes, generate OpenAPI-style docs
  - user: "Create SDK documentation" → extract methods, parameters, return types

Skill Content Structure

Recommended Sections

---
name: example-skill
description: |-
  [Description as above]
---

# Skill Title

Brief overview of what this skill enables.

## Core Concepts

Fundamental knowledge the agent needs.

## Workflow

Step-by-step process:

1. **Understand**: Gather requirements
2. **Analyze**: Assess current state
3. **Implement**: Make changes
4. **Verify**: Confirm correctness

## Patterns

### Pattern Name

\`\`\`language
// Code example
\`\`\`

## Anti-Patterns

- **Problem**: Description → **Solution**: Fix

## Validation

How to verify the skill's output is correct.

Length Guidelines

Guideline	Recommendation
SKILL.md total length	SHOULD be under 500 lines
Complex documentation	SHOULD use `references/` dir
Code examples	SHOULD use `scripts/` dir
Progressive disclosure	Core in SKILL.md, details in references

Permission Configuration

Control which skills agents can load:

# In agent frontmatter or opencode.json
permission:
  skill:
    "*": "deny"              # Deny all by default
    "security-*": "allow"    # Allow security-prefixed
    "my-skill": "allow"      # Allow specific skill

Pattern Matching

Pattern	Matches
`"*"`	All skills
`"prefix-*"`	Skills starting with `prefix-`
`"exact-name"`	Only that exact skill

References Directory

For detailed documentation that would bloat SKILL.md:

.opencode/skill/my-skill/
├── SKILL.md
└── references/
    ├── schema.md          # JSON schema documentation
    ├── examples.md        # Extended examples
    └── troubleshooting.md # Common issues

Reference in SKILL.md:

See `references/schema.md` for the complete configuration schema.

Scripts Directory

For executable utilities:

.opencode/skill/my-skill/
├── SKILL.md
└── scripts/
    ├── validate.sh        # Validation script
    └── generate.py        # Generator script

Reference in SKILL.md:

Run validation:
\`\`\`bash
bash .opencode/skill/my-skill/scripts/validate.sh
\`\`\`

Skill Discovery

Skills are discovered at:

Project: .opencode/skill/*/SKILL.md
Global: ~/.config/opencode/skill/*/SKILL.md

Project skills take precedence over global skills with the same name.

Best Practices

MUST

Use the description pattern (capability + triggers + examples)
Keep SKILL.md focused and under 500 lines
Use references/ for detailed documentation
Test skill loading with skill my-skill-name
Include validation steps

MUST NOT

Create overly broad skills (prefer focused, composable skills)
Duplicate content that exists in other skills
Include secrets or credentials in skill files
Forget to match folder name with frontmatter name

Validation

After creating a skill:

opencode run "test"

Then test loading:

Load the my-skill-name skill and explain what it does.

About

SKILL.md

About

Create and manage OpenCode skills with proper SKILL.md format, frontmatter, and organization...

SKILL.md

Create loadable knowledge modules that enhance agent capabilities.

A skill is a markdown file that provides specialized knowledge, workflows, or tool integrations. Skills are loaded on-demand via the skill tool when needed.

Skill Fundamentals

Location

Scope	Path
Project	`.opencode/skill/<name>/SKILL.md`
Global	`~/.config/opencode/skill/<name>/SKILL.md`

CRITICAL: The folder name MUST match the name in frontmatter.

Directory Structure

.opencode/skill/my-skill/
├── SKILL.md           # REQUIRED - Main skill definition
├── scripts/           # Optional - Executable scripts
│   └── validate.sh
├── references/        # Optional - Reference documents
│   └── schema.md
└── assets/            # Optional - Images, data files
    └── diagram.png

Naming Rules

Rule	Valid	Invalid
Lowercase	`my-skill`	`My-Skill`
Alphanumeric + hyphen	`api-client`	`api_client`
Match folder name	`foo/SKILL.md` with `name: foo`	Mismatch

Frontmatter Schema

---
name: my-skill-name          # REQUIRED, MUST match folder name
description: |-              # REQUIRED, 1-1024 characters
  [Capability summary]. Use for [use cases].
  
  Use proactively when [trigger contexts].
  
  Examples:
  - user: "query" → action
  - user: "another query" → action
---

Description Pattern

The description MUST have three parts:

Capability statement: What the skill does (1-2 sentences)
Trigger contexts: "Use proactively when [conditions]"
Examples: user: "query" → action format

description: |-
  Generate comprehensive API documentation from source code. Use for documenting REST endpoints, GraphQL schemas, and SDK methods.
  
  Use proactively when user says "document API", "generate docs", "API reference", or asks about endpoint documentation.
  
  Examples:
  - user: "Document this FastAPI app" → analyze routes, generate OpenAPI-style docs
  - user: "Create SDK documentation" → extract methods, parameters, return types

Skill Content Structure

Recommended Sections

---
name: example-skill
description: |-
  [Description as above]
---

# Skill Title

Brief overview of what this skill enables.

## Core Concepts

Fundamental knowledge the agent needs.

## Workflow

Step-by-step process:

1. **Understand**: Gather requirements
2. **Analyze**: Assess current state
3. **Implement**: Make changes
4. **Verify**: Confirm correctness

## Patterns

### Pattern Name

\`\`\`language
// Code example
\`\`\`

## Anti-Patterns

- **Problem**: Description → **Solution**: Fix

## Validation

How to verify the skill's output is correct.

Length Guidelines

Guideline	Recommendation
SKILL.md total length	SHOULD be under 500 lines
Complex documentation	SHOULD use `references/` dir
Code examples	SHOULD use `scripts/` dir
Progressive disclosure	Core in SKILL.md, details in references

Permission Configuration

Control which skills agents can load:

# In agent frontmatter or opencode.json
permission:
  skill:
    "*": "deny"              # Deny all by default
    "security-*": "allow"    # Allow security-prefixed
    "my-skill": "allow"      # Allow specific skill

Pattern Matching

Pattern	Matches
`"*"`	All skills
`"prefix-*"`	Skills starting with `prefix-`
`"exact-name"`	Only that exact skill

References Directory

For detailed documentation that would bloat SKILL.md:

.opencode/skill/my-skill/
├── SKILL.md
└── references/
    ├── schema.md          # JSON schema documentation
    ├── examples.md        # Extended examples
    └── troubleshooting.md # Common issues

Reference in SKILL.md:

See `references/schema.md` for the complete configuration schema.

Scripts Directory

For executable utilities:

.opencode/skill/my-skill/
├── SKILL.md
└── scripts/
    ├── validate.sh        # Validation script
    └── generate.py        # Generator script

Reference in SKILL.md:

Run validation:
\`\`\`bash
bash .opencode/skill/my-skill/scripts/validate.sh
\`\`\`

Skill Discovery

Skills are discovered at:

Project: .opencode/skill/*/SKILL.md
Global: ~/.config/opencode/skill/*/SKILL.md

Project skills take precedence over global skills with the same name.

Best Practices

MUST

Use the description pattern (capability + triggers + examples)
Keep SKILL.md focused and under 500 lines
Use references/ for detailed documentation
Test skill loading with skill my-skill-name
Include validation steps

MUST NOT

Create overly broad skills (prefer focused, composable skills)
Duplicate content that exists in other skills
Include secrets or credentials in skill files
Forget to match folder name with frontmatter name

Validation

After creating a skill:

opencode run "test"

Then test loading:

Load the my-skill-name skill and explain what it does.