Skill Creator

Create a new OpenCode Skill.

When to Use

Use this when the user wants to create a new OpenCode Skill.

Important References

Before creating a skill, you must read the following documents:

SKILL.md Format Specification — Format requirements for YAML frontmatter and Markdown content
Directory Structure Specification — Purpose and selection of scripts/references/assets
Script Language Selection Guide — When scripts are needed + language selection principles
Path Resolution Specification — Must-read: Compliant way to reference internal skill resources (relative paths / Markdown links, hard-coded absolute paths are prohibited)

Ecosystem Fields (Optional Frontmatter)

In addition to the required

name

and

description

, the agentskills.io specification supports the following optional fields (use as needed when creating, do not fill for the sake of filling):

Field	Purpose	Example
`license`	Name of the license, or a link to the license file included with the skill	`license: MIT` / `license: Proprietary. LICENSE.txt has complete terms`
`compatibility`	Environment requirements (target products, system packages, network access, etc.), 1-500 characters, most skills do not require it	`compatibility: Requires Python 3.14+ and uv`
`metadata`	Custom key-value pair metadata (author, version, category, etc.), can include `supportedAgents` to declare compatible Agents	See example below
`allowed-tools`	Space-separated list of pre-authorized tools (experimental field, support varies by Agent)	`allowed-tools: Read Write Edit Bash`

yaml

metadata:
  author: your-name
  version: "1.0.0"
  supportedAgents: ["claude-code", "opencode"]

Key Points:

```
license
```
: Optional, refer to other skills in this repository for writing style (e.g.,
```
license: MIT
```
).
```
metadata.supportedAgents
```
: Declare the list of Agents this skill is intended for; omitting it means full compatibility.
```
allowed-tools
```
: Optional, refer to other skills in this repository for writing style (e.g.,
```
allowed-tools: Bash
```
). Must be a space-separated string (e.g.,
```
allowed-tools: Read Write Edit
```
), supports subcommand restriction format (such as
```
Bash(git:*)
```
); do not write as YAML array or comma-separated. If not specified, all tools are available by default.

Creation Process

Phase 1: Clarify Requirements

Ask all necessary information in one round. Include:

Usage Scenarios: In which situations will this skill be invoked? Provide 2-3 typical scenarios.
Input/Output: What is the input → what is the output?
Edge Cases: Are there any edge cases that need special handling?
Skill Name (kebab-case)
Trigger Phrases: When should this skill be triggered? List keywords the user might say
Output Format: Are there any format requirements for the output?
Installation Location: Where is the final target path for this skill? (This is the only location, there is no deploy step)

Ask the user directly in the main conversation (questions/confirmations are regular conversations, no special question tool is needed).
allowed-tools
is an optional field; if not specified, all tools are available by default.

3 Sub-questions that must be asked about "Installation Location":

Scope: Is this skill for all projects of the current user (global), or only for the current project (project-level)?
Project Custom Directory: Does the current project root directory already have a skill directory convention (not
```
.opencode/skills/
```
, such as
```
skills/
```
,
```
.agents/skills/
```
)? If yes, prioritize the project's existing convention.
Is
.opencode
in
.gitignore
: If it is a project-level skill and needs to be shared with Git, confirm that
```
.opencode/
```
is not ignored; otherwise, use
```
skills/
```
or
```
skills.paths
```
in
```
opencode.json
```
instead.

Location Quick Reference(See Directory Structure Specification - Installation Location for details):

Global Use:
```
~/.config/opencode/skills/<name>/
```
← For personal use, recommended default
Project-level (Shared with Git):
```
<project>/.opencode/skills/<name>/
```
← Exclusive to the project
Project Custom:
```
skills/
```
or other directories in the user's project root ← Follow the project's existing convention

Summarize your understanding in the following format and ask the user to confirm:

## My Understanding
- **Problem Solved**: {one sentence}
- **Typical Scenarios**: {2-3 scenarios}
- **Input/Output**: {input} → {output}
- **Edge Cases**: {notable edge cases to watch for}
- **Skill Name**: `{name}`
- **Trigger Phrases**: {list of trigger phrases}
- **Installation Location**: `{absolute path}` ← This is the final location, ready to use after creation, no need to copy

Is the above understanding correct?

Is the above understanding correct? Please confirm, or supplement any missing information.

Phase 2: Create Files

Write SKILL.md directly in the main conversation. Determine whether subdirectories like scripts/, references/, assets/ are needed based on actual complexity.

Create directory structure
Write SKILL.md
If scripts/ is needed, create and write script files
If references/ is needed, create and write reference documents
If assets/ is needed, create and write resource files

Key: When referencing internal skill resources (files in subdirectories like scripts/, references/, assets/) in SKILL.md, use relative paths (relative to the skill directory, e.g.,

scripts/main.py

) or Markdown links (e.g.,

[Guide](references/guide.md)

), see Path Resolution Specification for details. Prohibit hard-coded absolute paths (e.g.,

~/.config/opencode/skills/xxx

), prohibit

@path

syntax (e.g.,

@scripts/xxx

— not allowed by agentskills.io specification, cannot be recognized by other Agents).

bash

# Example: Global skill — This is the final location
mkdir -p ~/.config/opencode/skills/{skill-name}/

# Example: Project-level skill — This is also the final location
mkdir -p .opencode/skills/{skill-name}/

⚠️ Key Clarification: The directory created by
mkdir -p
is the final storage location of the skill. OpenCode loads skills through a pure file discovery mechanism (scans 6+ known paths, later discovered skills with the same name override earlier ones), there is no "deploy to global" step. If the user wants a "global" skill, write directly to
~/.config/opencode/skills/<name>/
, do not write to
.opencode/skills/
first and then copy.

After writing, inform the user of the file path and let them directly review the final files. The user can:

Use it directly (no reply needed)
Propose modification suggestions (enter modification loop)
Delete files and start over

⚠️ Important Reminder

Phase 1 must be completed: Understand the user's problem thoroughly, ask if unclear.

Complete Directory Structure Description

skill-name/
├── SKILL.md              # Required: Instructions + Metadata
├── scripts/              # Optional: Executable scripts
├── references/          # Optional: Reference documents
└── assets/              # Optional: Templates/Resources

skill-creator

NPX Install

Tags

SKILL.md Content (Chinese)