技能工坊

概述

Skill Lab

技能工坊 — 基于 WorkBuddy 内置 skill-creator 修改增强（Apache-2.0）。

新增/整合：需求访谈、测试评估框架、失败模式追踪、统一发布检查、Description 路由规则。

如需创建/改进/评估技能，请使用本技能。

This skill provides guidance for creating effective skills.

About Skills

Skills are modular, self-contained packages that extend CodeBuddy's capabilities by providing specialized knowledge, workflows, and tools. Think of them as "onboarding guides" for specific domains or tasks—they transform CodeBuddy from a general-purpose agent into a specialized agent equipped with procedural knowledge that no model can fully possess.

What Skills Provide

1. Specialized workflows – Multi-step procedures for specific domains
2. Tool integrations – Instructions for working with specific file formats or APIs
3. Domain expertise – Company-specific knowledge, schemas, business logic
4. Bundled resources – Scripts, references, and assets for complex and repetitive tasks

Anatomy of a Skill

Every skill consists of a required SKILL.md file and optional bundled resources:

skill-name/
├── SKILL.md (required)
│   ├── YAML frontmatter metadata (required)
│   │   ├── name: (required)
│   │   └── description: (required)
│   └── Markdown instructions (required)
└── Bundled Resources (optional)
    ├── scripts/          - Executable code (Python/Bash/etc.)
    ├── references/       - Documentation intended to be loaded into context as needed
    ├── examples/         - [推荐] 历史案例, 展示典型场景和 Gotchas
    └── assets/           - Files used in output (templates, icons, fonts, etc.)

SKILL.md (required)

Metadata Quality: The name and description in YAML frontmatter determine when CodeBuddy will use the skill. Be specific about what the skill does and when to use it. Use the third-person (e.g. "This skill should be used when…" instead of "Use this skill when…").

Agent-Created Flag: The YAML frontmatter MUST include agent_created: true so that skill_manage can modify or delete the skill later.

SkillHub 发布 frontmatter 附加字段： 发布到 SkillHub 时，frontmatter 还需包含 slug（发布标识）、displayName（展示名）、summary（一句话简介）、license、version，可选 metadata.openclaw.emoji。参考已发布技能格式，发布前对照 references/publishing-checklist.md 核对。

Bundled Resources (optional)

Scripts (scripts/)

Executable code (Python/Bash/etc.) for tasks that require deterministic reliability or are repeatedly rewritten.

• When to include: When the same code is being rewritten repeatedly or deterministic reliability is needed
• Example: scripts/rotate_pdf.py for PDF rotation tasks
• Benefits: Token efficient, deterministic, may be executed without loading into context
• Note: Scripts may still need to be read by CodeBuddy for patching or environment-specific adjustments
• Naming requirement: All files MUST have a file extension (.py, .sh, .md, .json). Files without extensions (e.g., myscript instead of myscript.sh) will be rejected by SkillHub during upload.

References (references/)

Documentation and reference material intended to be loaded as needed into context to inform CodeBuddy's process and thinking.

• When to include: For documentation that CodeBuddy should reference while working
• Examples: references/finance.md for financial schemas, references/mnda.md for company NDA template, references/policies.md for company policies, references/api_docs.md for API specifications
• Use cases: Database schemas, API documentation, domain knowledge, company policies, detailed workflow guides
• Benefits: Keeps SKILL.md lean, loaded only when CodeBuddy determines it's needed
• Best practice: If files are large (>10k words), include grep search patterns in SKILL.md
• Avoid duplication: Information should live in either SKILL.md or references files, not both. Prefer references files for detailed information unless it's truly core to the skill—this keeps SKILL.md lean while making information discoverable without hogging the context window. Keep only essential procedural instructions and workflow guidance in SKILL.md; move detailed reference material, schemas, and examples to references files.

Assets (assets/)

Files not intended to be loaded into context, but rather used within the output CodeBuddy produces.

• When to include: When the skill needs files that will be used in the final output
• Examples: assets/logo.png for brand assets, assets/slides.pptx for PowerPoint templates, assets/frontend-template/ for HTML/React boilerplate, assets/font.ttf for typography
• Use cases: Templates, images, icons, boilerplate code, fonts, sample documents that get copied or modified
• Benefits: Separates output resources from documentation, enables CodeBuddy to use files without loading them into context

Examples (examples/)

Historical cases demonstrating typical usage scenarios and gotchas (常踩的坑).

• When to include: When the skill captures tacit knowledge—things the model wouldn't know from general training data
• Examples:
  • examples/invoice-gotchas.md — "这个表不能按 created_at 排序", "staging 返回 200 不代表成功"
  • examples/typical-cases/ — 真实文档 + 解析结果对比
• What to put here: Gotchas, edge cases, failure modes, real-world quirks. These are the most valuable part of a skill because they encode experience the model doesn't have.
• Benefits: Keeps SKILL.md focused on navigation; examples are loaded only when the model needs to understand a specific scenario

Progressive Disclosure Design Principle

Skills use a three-level loading system to manage context efficiently:

1. Metadata (name + description) – Always in context (~100 words)
2. SKILL.md body – When skill triggers (<5k words)
3. Bundled resources – As needed by CodeBuddy (Unlimited*)

*Unlimited because scripts can be executed without reading into context window.

Skill Creation Process

To create a skill, follow the "Skill Creation Process" in order, skipping steps only if there is a clear reason why they are not applicable.

Step 1: Understanding the Skill with Concrete Examples

Skip this step only when the skill's usage patterns are already clearly understood. It remains valuable even when working with an existing skill.

需求访谈 (Requirements Interview)

To create an effective skill, first conduct a structured interview with the user to clarify the skill's purpose, scope, and quality criteria. Ask these questions in order, keeping one question per message to avoid overwhelming the user:

1. 核心场景 — "这个 skill 主要用来解决什么问题？用户说一句什么话会触发它？"
2. 输入输出 — "用户会提供什么？（文件/链接/文字）期望产出什么？（文本/JSON/文件）"
3. 质量标准 — "怎样算做好？怎样算不合格？有什么常见的坑需要注意？"
4. 边界条件 — "什么情况下不应该触发？有什么限制？（文件大小/格式/语言）"

Example interview for an image-editor skill:

• "What functionality should the image-editor skill support? Editing, rotating, anything else?"
• "Can you give some examples of how this skill would be used?"
• "I can imagine users asking for things like 'Remove the red-eye from this image' or 'Rotate this image'. Are there other ways you imagine this skill being used?"
• "What would a user say that should trigger this skill?"

To avoid overwhelming users, avoid asking too many questions in a single message. Start with the most important questions and follow up as needed for better effectiveness.

Conclude this step when there is a clear sense of the functionality the skill should support.

Step 2: Planning the Reusable Skill Contents

To turn concrete examples into an effective skill, analyze each example by:

1. Considering how to execute on the example from scratch
2. Identifying what scripts, references, and assets would be helpful when executing these workflows repeatedly

Example: When building a pdf-editor skill to handle queries like "Help me rotate this PDF," the analysis shows:

1. Rotating a PDF requires re-writing the same code each time
2. A scripts/rotate_pdf.py script would be helpful to store in the skill

Example: When designing a frontend-webapp-builder skill for queries like "Build me a todo app" or "Build me a dashboard to track my steps," the analysis shows:

1. Writing a frontend webapp requires the same boilerplate HTML/React each time
2. An assets/hello-world/ template containing the boilerplate HTML/React project files would be helpful to store in the skill

Example: When building a big-query skill to handle queries like "How many users have logged in today?" the analysis shows:

1. Querying BigQuery requires re-discovering the table schemas and relationships each time
2. A references/schema.md file documenting the table schemas would be helpful to store in the skill

To establish the skill's contents, analyze each concrete example to create a list of the reusable resources to include: scripts, references, and assets.

Step 3: Initializing the Skill

At this point, it is time to actually create the skill.

Skip this step only if the skill being developed already exists, and iteration or packaging is needed. In this case, continue to the next step.

Skills can be stored in two locations depending on the intended scope:

When the intended scope is unclear, prefer a user skill — it follows you across all workspaces and is appropriate for most personal workflows. Use a project skill only when there is a clear need to share the skill with collaborators, such as team conventions, project-specific schemas, or shared workflows.

When creating a new skill from scratch, always run the init_skill.py script. The script conveniently generates a new template skill directory that automatically includes everything a skill requires, making the skill creation process much more efficient and reliable.

Usage:

scripts/init_skill.py <skill-name> [--path <output-directory>]

If --path is omitted, the skill is created under ~/.codebuddy/skills/ (user scope) by default.

The script:

• Creates the skill directory at the specified path
• Generates a SKILL.md template with proper frontmatter and TODO placeholders
• Creates example resource directories: scripts/, references/, and assets/
• Adds example files in each directory that can be customized or deleted

After initialization, customize or remove the generated SKILL.md and example files as needed.

Step 4: Edit the Skill

When editing the (newly-generated or existing) skill, remember that the skill is being created for another instance of CodeBuddy to use. Focus on including information that would be beneficial and non-obvious to CodeBuddy. Consider what procedural knowledge, domain-specific details, or reusable assets would help another CodeBuddy instance execute these tasks more effectively.

Start with Reusable Skill Contents

To begin implementation, start with the reusable resources identified above: scripts/, references/, and assets/ files. Note that this step may require user input. For example, when implementing a brand-guidelines skill, the user may need to provide brand assets or templates to store in assets/, or documentation to store in references/.

Also, delete any example files and directories not needed for the skill. The initialization script creates example files in scripts/, references/, and assets/ to demonstrate structure, but most skills won't need all of them.

Update SKILL.md

Writing Style: Write the entire skill using imperative/infinitive form (verb-first instructions), not second person. Use objective, instructional language (e.g., "To accomplish X, do Y" rather than "You should do X" or "If you need to do X"). This maintains consistency and clarity for AI consumption.

不要写废话 (Don't Repeat Common Sense): The purpose of a skill is to encode tacit knowledge (隐性知识) — things the model doesn't know from training data. Do not include:

• General platform documentation the model already knows (e.g., basic pip install commands, API fundamentals)
• Common programming knowledge (e.g., "OpenCV is a computer vision library")
• Generic troubleshooting steps without specific gotchas

Instead, focus on:

• Gotchas: "这个表不能按 created_at 排序", "staging 返回 200 不代表成功"
• Performance numbers the model wouldn't know: "LiteParse 0.9ms/页, PaddleOCR ~15s/页"
• Decision rules: "先试 A, 空结果退到 B"
• Known failure modes: "公章/签名用 Tesseract 会乱码, 必须用 PaddleOCR"

Skill = 把老师傅经验写下来。 如果一段内容在网上随便搜得到, 就不该出现在 SKILL.md 里。

To complete SKILL.md, answer the following questions:

1. What is the purpose of the skill, in a few sentences?
2. When should the skill be used?
3. In practice, how should CodeBuddy use the skill? All reusable skill contents developed above should be referenced so that CodeBuddy knows how to use them.

Step 4.5: Testing & Evaluation

Before packaging, run the evaluation framework to measure whether the skill actually improves AI output quality.

创建测试用例

Create an evals.json file in the skill directory with 2-3 typical user prompts:

{
  "meta": { "skill": "my-skill", "version": "1.0.0" },
  "tests": [
    {
      "id": "test-001",
      "prompt": "用户典型提问",
      "expected": "期望的输出行为",
      "type": "with-skill"
    }
  ],
  "baseline_tests": [
    {
      "id": "baseline-001",
      "prompt": "跟 test-001 相同输入",
      "expected": "无 skill 时的输出行为",
      "type": "baseline"
    }
  ]
}

Use the template at references/evals-template.json as a starting point.

运行评估

python scripts/run_evals.py <skill-dir>/evals.json

The script generates an evaluation report that scores each test on four dimensions:

量化对比

After filling in scores manually based on actual AI output, compare:

• with-skill 总分 vs baseline 总分
• 如果 with-skill 领先 1.0+ 分 → skill 有效, 可以发布
• 如果两者接近 → 需要优化 skill 后再发布
• 如果 baseline 更高 → skill 有副作用, 需要重新设计

完整评估方法论见 references/evaluation-framework.md。

Step 5: Packaging a Skill

Once the skill is ready, it should be packaged into a distributable zip file that gets shared with the user. The packaging process automatically validates the skill first to ensure it meets all requirements:

scripts/package_skill.py <path/to/skill-folder>

Optional output directory specification:

scripts/package_skill.py <path/to/skill-folder> ./dist

The packaging script will:

1. Validate the skill automatically, checking:
   • YAML frontmatter format and required fields (name / description / version)
   • Skill naming conventions and directory structure
   • Description completeness and quality (单行、无尖括号、≥20 字)
   • No extensionless files (SkillHub 拒绝)
   • No junk files (.git/ __pycache__/ .workbuddy/ *.pyc _skillhub_meta.json)
   • Version consistency (SKILL.md frontmatter ↔ _meta.json)
2. Package the skill if validation passes, creating a zip file named after the skill (e.g., my-skill.zip) with proper root directory (skill-name/), auto-excluding junk, then running testzip() integrity check (防"损坏 zip/文件错位"事故).

If validation fails, the script will report the errors and exit without creating a package. Fix any validation errors and run the packaging command again.

SkillHub 发布附加检查

打包通过后, 在上传 SkillHub 前, 必须额外核对以下事项：

1. 所有文件有后缀名 — SkillHub 不识别无后缀文件 (如 script ❌ → script.sh ✅)
2. Shell 脚本必须带 .sh — 无后缀的 shell 脚本会被拒绝上传
3. 排除无关文件 — 确保 .git/ __pycache__/ .workbuddy/ *.pyc _skillhub_meta.json 不在包内（package 脚本已自动排除，仍应抽查 zip 内容）
4. 版本号一致 — SKILL.md → _meta.json → CHANGELOG.md 三者版本一致（package 脚本会拦截 SKILL.md↔_meta.json 不一致）
5. 更新说明简洁 — 纯文本格式, 不超过 300 字, 分"新增"、"变更"、"修复"三类
6. zip 结构正确 — 包根目录应为技能目录名（skill-name/SKILL.md），解压后可直接被 WorkBuddy 识别
7. frontmatter 完整 — 发布 SkillHub 需 slug / displayName / summary / license / version 字段齐全

详细检查清单见 references/publishing-checklist.md。发布前必读 references/failures.md（10 条已知失败模式）回归检查——包括 userModified 防覆盖、frontmatter 硬门槛、打包错位等实战坑。建议每次打包前打开该文件逐项核对。

Step 6: Iterate

After testing the skill, users may request improvements. Often this happens right after using the skill, with fresh context of how the skill performed.

Iteration workflow:

1. Use the skill on real tasks
2. Notice struggles or inefficiencies
3. Identify how SKILL.md or bundled resources should be updated
4. Implement changes and test again

描述优化 — Description = 路由规则 (Routing Rule)

The description in frontmatter determines when AI triggers the skill. A poorly written description means the skill is never called.

核心认知：Description 不是功能介绍，而是加载路由。

AI 启动时会扫描所有 skill 的 name + description，然后根据用户当前的问题判断加载哪个 skill。所以 description 应该描述用户的意图，而不是罗列功能。

自查方法： 写完 description 后，把整个 skill 删掉，只保留这一行 description。问自己："模型看到用户的问题后，能知道什么时候该加载这个 skill 吗？" 如果不能，就需要重写。

优化步骤：

1. 测试当前描述 — 用 evals.json 的测试场景检查 AI 是否触发了 skill
2. 分析触发失败原因 — 如果 AI 没有触发, 检查:
   • description 是否覆盖了用户常用的表达方式
   • 关键词是否准确反映了用户意图而不是功能
   • 是否有更通用的描述被优先匹配
3. 迭代描述 — 将优化后的 description 和触发率变化记录在 CHANGELOG.md 中
4. 重新评估 — 再次运行 evals 确认改进有效

Editing an Already-Installed Marketplace Skill

When the user asks to edit an existing skill that they installed from the marketplace (e.g. via the "Edit" entry on a skill card, which inserts a prompt like "使用 /skill-lab 帮我编辑 /<skill-id> 技能"), follow this flow:

1. Read the existing SKILL.md (and other relevant files under the skill directory)

to understand what is there before changing anything.

1. Apply the user's requested edits with the file editing tools.
2. After successfully saving the edits, mark the skill as user-modified by

writing "userModified": true into the skill's local marketplace meta file. This prevents automatic updates from silently overwriting the user's edits.

How to mark user-modified:

Look for a marketplace meta file in the skill directory (the directory containing the edited SKILL.md). The file is named one of:

• _skillhub_meta.json (BuiltinMarket / SkillHub source)
• _knot_meta.json (Knot source)

If found, read the JSON, set "userModified": true, and write it back:

   # Pseudocode (use Read + Write tools):
   1. Read <skill-dir>/_skillhub_meta.json (or _knot_meta.json)
   2. Parse JSON → add/set "userModified": true
   3. Write the updated JSON back to the same file

If neither meta file exists, the skill was created locally (not from a marketplace) — skip this step silently, no error to surface.

1. Briefly tell the user that the edit is saved and that future marketplace

updates will ask before overwriting their changes.

Important:

• Only mark user-modified after files have actually been written. Do not do it

speculatively or before edits are saved.

• Do not mark when creating a brand-new skill — the flag is only meaningful

for marketplace-installed skills.