Skip to content
Systematic

create-agent-skills

Creating Skills & Commands

Section titled “Creating Skills & Commands”

This skill teaches how to create effective OpenCode skills following the official specification from code.claude.com/docs/en/skills.

Commands and Skills Are Now The Same Thing

Section titled “Commands and Skills Are Now The Same Thing”

Custom slash commands have been merged into skills. A file at .opencode/commands/review.md and a skill at .opencode/skills/review/SKILL.md both create /review and work the same way. Existing .opencode/commands/ files keep working. Skills add optional features: a directory for supporting files, frontmatter to control invocation, and automatic context loading.

If a skill and a command share the same name, the skill takes precedence.

When To Create What

Section titled “When To Create What”

Use a command file (commands/name.md) when:

  • Simple, single-file workflow
  • No supporting files needed
  • Task-oriented action (deploy, commit, triage)

Use a skill directory (skills/name/SKILL.md) when:

  • Need supporting reference files, scripts, or templates
  • Background knowledge Claude should auto-load
  • Complex enough to benefit from progressive disclosure

Both use identical YAML frontmatter and markdown content format.

Standard Markdown Format

Section titled “Standard Markdown Format”

Use YAML frontmatter + markdown body with standard markdown headings. Keep it clean and direct.

---
name: my-skill-name
description: What it does and when to use it
---


# My Skill Name


## Quick Start
Immediate actionable guidance...


## Instructions
Step-by-step procedures...


## Examples
Concrete usage examples...

Frontmatter Reference

Section titled “Frontmatter Reference”

All fields are optional. Only description is recommended.

FieldRequiredDescription
nameNoDisplay name. Lowercase letters, numbers, hyphens (max 64 chars). Defaults to directory name.
descriptionRecommendedWhat it does AND when to use it. Claude uses this for auto-discovery. Max 1024 chars.
argument-hintNoHint shown during autocomplete. Example: [issue-number]
disable-model-invocationNoSet true to prevent Claude auto-loading. Use for manual workflows like /deploy, /commit. Default: false.
user-invocableNoSet false to hide from / menu. Use for background knowledge. Default: true.
allowed-toolsNoTools Claude can use without permission prompts. Example: Read, Bash(git *)
modelNoModel to use. Options: haiku, sonnet, opus.
contextNoSet fork to run in isolated subagent context.
agentNoSubagent type when context: fork. Options: Explore, Plan, general-purpose, or custom agent name.

Invocation Control

Section titled “Invocation Control”
FrontmatterUser can invokeClaude can invokeWhen loaded
(default)YesYesDescription always in context, full content loads when invoked
disable-model-invocation: trueYesNoDescription not in context, loads only when user invokes
user-invocable: falseNoYesDescription always in context, loads when relevant

Use disable-model-invocation: true for workflows with side effects: /deploy, /commit, /triage-prs, /send-slack-message. You don’t want Claude deciding to deploy because your code looks ready.

Use user-invocable: false for background knowledge that isn’t a meaningful user action: coding conventions, domain context, legacy system docs.

Dynamic Features

Section titled “Dynamic Features”

Arguments

Section titled “Arguments”

Use $ARGUMENTS placeholder for user input. If not present in content, arguments are appended automatically.

---
name: fix-issue
description: Fix a GitHub issue
disable-model-invocation: true
---


Fix GitHub issue $ARGUMENTS following our coding standards.

Access individual args: $ARGUMENTS[0] or shorthand $0, $1, $2.

Dynamic Context Injection

Section titled “Dynamic Context Injection”

The !`command` syntax runs shell commands before content is sent to Claude:

---
name: pr-summary
description: Summarize changes in a pull request
context: fork
agent: Explore
---


## Context
- PR diff: !`gh pr diff`
- Changed files: !`gh pr diff --name-only`


Summarize this pull request...

Running in a Subagent

Section titled “Running in a Subagent”

Add context: fork to run in isolation. The skill content becomes the subagent’s prompt. It won’t have conversation history.

---
name: deep-research
description: Research a topic thoroughly
context: fork
agent: Explore
---


Research $ARGUMENTS thoroughly:
1. Find relevant files
2. Analyze the code
3. Summarize findings

Progressive Disclosure

Section titled “Progressive Disclosure”

Keep SKILL.md under 500 lines. Split detailed content into reference files:

my-skill/
├── SKILL.md           # Entry point (required, overview + navigation)
├── reference.md       # Detailed docs (loaded when needed)
├── examples.md        # Usage examples (loaded when needed)
└── scripts/
    └── helper.py      # Utility script (executed, not loaded)

Link from SKILL.md: For API details, see [reference.md](reference.md).

Keep references one level deep from SKILL.md. Avoid nested chains.

Effective Descriptions

Section titled “Effective Descriptions”

The description enables skill discovery. Include both what it does and when to use it.

Good:

description: Extract text and tables from PDF files, fill forms, merge documents. Use when working with PDF files or when the user mentions PDFs, forms, or document extraction.

Bad:

description: Helps with documents

What Would You Like To Do?

Section titled “What Would You Like To Do?”
  1. Create new skill - Build from scratch
  2. Create new command - Build a slash command
  3. Audit existing skill - Check against best practices
  4. Add component - Add workflow/reference/example
  5. Get guidance - Understand skill design

Creating a New Skill or Command

Section titled “Creating a New Skill or Command”

Step 1: Choose Type

Section titled “Step 1: Choose Type”

Ask: Is this a manual workflow (deploy, commit, triage) or background knowledge (conventions, patterns)?

  • Manual workflow → command with disable-model-invocation: true
  • Background knowledge → skill without disable-model-invocation
  • Complex with supporting files → skill directory

Step 2: Create the File

Section titled “Step 2: Create the File”

Command:

---
name: my-command
description: What this command does
argument-hint: [expected arguments]
disable-model-invocation: true
allowed-tools: Bash(gh *), Read
---


# Command Title


## Workflow


### Step 1: Gather Context
...


### Step 2: Execute
...


## Success Criteria
- [ ] Expected outcome 1
- [ ] Expected outcome 2

Skill:

---
name: my-skill
description: What it does. Use when [trigger conditions].
---


# Skill Title


## Quick Start
[Immediate actionable example]


## Instructions
[Core guidance]


## Examples
[Concrete input/output pairs]

Step 3: Add Reference Files (If Needed)

Section titled “Step 3: Add Reference Files (If Needed)”

Link from SKILL.md to detailed content:

For API reference, see [reference.md](reference.md).
For form filling guide, see [forms.md](forms.md).

Step 4: Test With Real Usage

Section titled “Step 4: Test With Real Usage”
  1. Test with actual tasks, not test scenarios
  2. Invoke directly with /skill-name to verify
  3. Check auto-triggering by asking something that matches the description
  4. Refine based on real behavior

Audit Checklist

Section titled “Audit Checklist”
  • Valid YAML frontmatter (name + description)
  • Description includes trigger keywords and is specific
  • Uses standard markdown headings (not XML tags)
  • SKILL.md under 500 lines
  • disable-model-invocation: true if it has side effects
  • allowed-tools set if specific tools needed
  • References one level deep, properly linked
  • Examples are concrete, not abstract
  • Tested with real usage

Anti-Patterns to Avoid

Section titled “Anti-Patterns to Avoid”
  • XML tags in body - Use standard markdown headings
  • Vague descriptions - Be specific with trigger keywords
  • Deep nesting - Keep references one level from SKILL.md
  • Missing invocation control - Side-effect workflows need disable-model-invocation: true
  • Too many options - Provide a default with escape hatch
  • Punting to Claude - Scripts should handle errors explicitly

Reference Files

Section titled “Reference Files”

For detailed guidance, see:

Sources

Section titled “Sources”