Back to Details

writing-skills

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Writing Skills (Excellence)

编写Skill（卓越级）

Dispatcher for skill creation excellence. Use the decision tree below to find the right template and standards.
这是Skill创建的卓越指导工具，使用下方的决策树来找到合适的模板和标准。

⚡ Quick Decision Tree

⚡ 快速决策树

What do you need to do?

你需要完成什么操作？

  1. Create a NEW skill:
    • Is it simple (single file, <200 lines)? → Tier 1 Architecture
    • Is it complex (multi-concept, 200-1000 lines)? → Tier 2 Architecture
    • Is it a massive platform (10+ products, AWS, Convex)? → Tier 3 Architecture
  2. Improve an EXISTING skill:
    • Fix "it's too long" -> Modularize (Tier 3)
    • Fix "AI ignores rules" -> Anti-Rationalization
    • Fix "users can't find it" -> CSO (Search Optimization)
  3. Verify Compliance:
    • Check metadata/naming -> Standards
    • Add tests -> Testing Guide
  1. 创建全新Skill：
    • 是否为简单Skill（单文件，少于200行）？ → Tier 1架构
    • 是否为复杂Skill（多概念，200-1000行）？ → Tier 2架构
    • 是否为大型平台类Skill（10+产品，涉及AWS、Convex）？ → Tier 3架构
  2. 优化现有Skill：
    • 解决「内容过长」问题 → 模块化重构（Tier 3）
    • 解决「AI忽略规则」问题 → 反合理化设计
    • 解决「用户无法找到Skill」问题 → CSO（搜索优化）
  3. 合规性验证：
    • 检查元数据/命名规范 → 标准规范
    • 添加测试 → 测试指南

📚 Component Index

📚 组件索引

ComponentPurpose
CSO"SEO for LLMs". How to write descriptions that trigger.
StandardsFile naming, YAML frontmatter, directory structure.
Anti-RationalizationHow to write rules that agents won't ignore.
TestingHow to ensure your skill actually works.
组件用途
CSO「LLM版SEO」，指导如何编写能触发Skill的描述。
标准规范文件命名、YAML前置元数据、目录结构规范。
反合理化设计指导如何编写Agent不会忽略的规则。
测试指南指导如何确保Skill实际生效。

🛠️ Templates

🛠️ 模板

  • Technique Skill (How-to)
  • Reference Skill (Docs)
  • Discipline Skill (Rules)
  • Pattern Skill (Design Patterns)
  • 技巧类Skill（操作指南类）
  • 参考类Skill（文档类）
  • 规则类Skill（规则约束类）
  • 模式类Skill（设计模式类）

When to Use

适用场景

  • Creating a NEW skill from scratch
  • Improving an EXISTING skill that agents ignore
  • Debugging why a skill isn't being triggered
  • Standardizing skills across a team
  • 从零开始创建全新Skill
  • 优化Agent会忽略的现有Skill
  • 调试Skill无法触发的问题
  • 团队内Skill标准化统一

How It Works

工作流程

  1. Identify goal → Use decision tree above
  2. Select template → From 
    references/templates/
  3. Apply CSO → Optimize description for discovery
  4. Add anti-rationalization → For discipline skills
  5. Test → RED-GREEN-REFACTOR cycle
  1. 明确目标 → 使用上方的决策树
  2. 选择模板 → 从
    references/templates/
    中选取
  3. 应用CSO优化 → 优化描述以提升可发现性
  4. 添加反合理化设计 → 针对规则类Skill
  5. 测试 → 遵循RED-GREEN-REFACTOR循环

Quick Example

快速示例

yaml
---
name: my-technique
description: Use when [specific symptom occurs].
metadata:
  category: technique
  triggers: error-text, symptom, tool-name
---
yaml
---
name: my-technique
description: Use when [specific symptom occurs].
metadata:
  category: technique
  triggers: error-text, symptom, tool-name
---

My Technique

My Technique

When to Use

When to Use

  • [Symptom A]
  • [Error message]
undefined
  • [Symptom A]
  • [Error message]
undefined

Common Mistakes

常见错误

MistakeFix
Description summarizes workflowUse "Use when..." triggers only
No 
metadata.triggers
Add 3+ keywords
Generic name ("helper")Use gerund (
creating-skills
)
Long monolithic SKILL.mdSplit into 
references/
See gotchas.md for more.
错误修复方案
描述内容总结工作流仅使用「Use when...」格式的触发条件
未设置
metadata.triggers
添加3个以上关键词
名称过于通用（如"helper"）使用动名词格式（如
creating-skills
）
SKILL.md内容冗长且单一拆分至
references/
目录下
更多内容请查看gotchas.md。

✅ Pre-Deploy Checklist

✅ 部署前检查清单

Before deploying any skill:
  • name
    field matches directory name exactly
  • SKILL.md
    filename is ALL CAPS
  • Description starts with "Use when..."
  • metadata.triggers
    has 3+ keywords
  • Total lines < 500 (use 
    references/
    for more)
  • No 
    @
    force-loading in cross-references
  • Tested with real scenarios
部署任何Skill前，请确认：
  • name
    字段与目录名称完全一致
  • SKILL.md
    文件名全部为大写
  • 描述以"Use when..."开头
  • metadata.triggers
    包含3个以上关键词
  • 总代码行数少于500（内容更多时使用
    references/
    目录）
  • 跨引用中未使用
    @
    强制加载
  • 已通过真实场景测试

🔗 Related Skills

🔗 相关Skill

  • opencode-expert: For OpenCode environment configuration
  • Use 
    /write-skill
    command for guided skill creation
  • opencode-expert: 用于OpenCode环境配置
  • 使用
    /write-skill
    命令进行引导式Skill创建

Examples

示例

Create a Tier 1 skill:
bash
mkdir -p ~/.config/opencode/skills/my-technique
touch ~/.config/opencode/skills/my-technique/SKILL.md
Create a Tier 2 skill:
bash
mkdir -p ~/.config/opencode/skills/my-skill/references/core
touch ~/.config/opencode/skills/my-skill/{SKILL.md,gotchas.md}
touch ~/.config/opencode/skills/my-skill/references/core/README.md
创建Tier 1 Skill：
bash
mkdir -p ~/.config/opencode/skills/my-technique
touch ~/.config/opencode/skills/my-technique/SKILL.md
创建Tier 2 Skill：
bash
mkdir -p ~/.config/opencode/skills/my-skill/references/core
touch ~/.config/opencode/skills/my-skill/{SKILL.md,gotchas.md}
touch ~/.config/opencode/skills/my-skill/references/core/README.md