description: Standards and naming rules for creating agent skills.
metadata:
tags: [standards, naming, yaml, structure]
技能开发指南
创建有效代理技能的全面参考。
目录结构
~/.config/opencode/skills/
{skill-name}/ # kebab-case, matches `name` field
SKILL.md # Required: main skill definition
references/ # Optional: supporting documentation
README.md # Sub-topic entry point
*.md # Additional files
项目本地替代方案：
.agent/skills/{skill-name}/SKILL.md
命名规则
| Directory | kebab-case, 1-64 chars | react-best-practices |
| SKILL.md | ALL CAPS, exact filename | SKILL.md (not skill.md) |
| name field | Must match directory name | name: react-best-practices |
SKILL.md 结构
—
name: {skill-name}
description: >-
Use when [trigger condition].
metadata:
category: technique
triggers: keyword1, keyword2, error-text
—
# Skill Title
Brief description of what this skill does.
## When to Use
– Symptom or situation A
– Symptom or situation B
## How It Works
Step-by-step instructions or reference content.
## Examples
Concrete usage examples.
## Common Mistakes
What to avoid and why.
描述最佳实践
description 字段对技能发现至关重要：
# ❌ 错误：工作流总结（代理跳过阅读完整技能）
description: Analyzes code, finds bugs, suggests fixes
# ✅ 正确：只写触发条件
description: Use when debugging errors or reviewing code quality.
metadata:
triggers: bug, error, code review
规则：
- 以"Use when…"开头
- 把触发词放在 metadata.triggers 下
- 保持在 500 字符以内
- 使用第三人称（不是"I"或"You"）
上下文效率
技能按需加载到上下文。优化 token 使用：
| Keep SKILL.md < 500 lines | Reduces context consumption |
| Put details in supporting files | Agent reads only what’s needed |
| Use tables for reference data | More compact than prose |
| Link to –help for CLI tools | Avoids duplicating docs |
支撑文件
对于复杂技能，使用附加文件：
my-skill/
SKILL.md # Overview + navigation
patterns.md # Detailed patterns
examples.md # Code examples
troubleshooting.md # Common issues
支撑文件 frontmatter 是必需的（对于除 SKILL.md 之外的任何 .md）：
—
description: >-
Short summary used for search and retrieval.
metadata:
tags: [pattern, troubleshooting, api]
source: internal
—
这个 frontmatter 帮助 LLM 在从 SKILL.md 引用时定位正确的文件。
从 SKILL.md 引用：
## Detailed Reference
– Patterns – Common usage patterns
– Examples – Code samples
技能类型
| Reference | Documentation, APIs | bigquery-analysis |
| Technique | How-to guides | condition-based-waiting |
| Pattern | Mental models | flatten-with-flags |
| Discipline | Rules to enforce | test-driven-development |
验证检查清单
部署之前：
- name 与目录名匹配？
- SKILL.md 全大写？
- 描述以"Use when…"开头？
- 触发词列在 metadata 下？
- 少于 500 行？
- 已用真实场景测试？
