skill-creator

Files (4)

• SKILL.md
• init_skill.py · scripts/
• package_skill.py · scripts/
• quick_validate.py · scripts/

SKILL.md (first lines)

# 技能创建者

此技能为创建高效技能提供指导。

## 关于技能

技能是模块化、独立的包，通过提供专业知识、工作流和工具来扩展 Agent 的能力。可以将它们视为特定领域或任务的“入职指南”——它们将通用代理转变为具备任何模型都无法完全拥有的程序性知识的专用 Agent。

### 技能提供什么

1.  **专业工作流** - 特定领域的多步骤程序
2.  **工具集成** - 使用特定文件格式或 API 的说明
3.  **领域专业知识** - 公司特定的知识、架构、业务逻辑
4.  **配套资源** - 用于复杂和重复任务的脚本、参考文档和静态资源

## 核心原则

### 简洁是关键

上下文窗口是一种公共资源。技能与 Agent 需要访问的其他所有内容共享上下文窗口：系统提示词、对话历史、其他技能的元数据以及实际的用户请求。

**默认假设：Agent 已经非常聪明。** 只添加 Agent 尚未拥有的上下文。评估每一条信息：“Agent 真的需要这个解释吗？”以及“这一段值得它的 token 成本吗？”

与其使用冗长的解释，不如使用简洁的示例。

### 设置适当的自由度

将具体程度与任务的脆弱性和多变性相匹配：

**高自由度（基于文本的说明）**：当多种方法都有效、决策取决于上下文或由启发式方法指导时使用。

**中等自由度（伪代码或带参数的脚本）**：当存在首选模式、可接受某些变化或配置影响行为时使用。

**低自由度（特定脚本，少量参数）**：当操作脆弱且容易出错、一致性至关重要或必须遵循特定顺序时使用。

把 Agent 想象成在探索一条路径：狭窄的悬崖桥梁需要特定的护栏（低自由度），而开阔的田野允许许多路线（高自由度）。

### 技能组成结构

每个技能都包含一个必需的 `SKILL.md` 文件和可选的配套资源：

```
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
    └── assets/           - Files used in output (templates, icons, fonts, etc.)
```

#### SKILL.md (必需)

每个 `SKILL.md` 包含：

-   **Frontmatter** (YAML)：包含 `name` 和 `description` 字段。这是 Agent 读取以确定何时使用技能的唯一字段，因此清楚全面地描述技能是什么以及何时使用它非常重要。
-   **正文** (Markdown)：使用技能的说明 and 指导。仅在技能触发后加载（如果有的话）。

#### 配套资源 (可选)

##### 脚本 (`scripts/`)

用于需要确定性可靠性或重复重写的任务的可执行代码（Python/Bash 等）。

-   **何时包含**：当相同的代码被重复重写或需要确定性可靠性时
-   **示例**：用于 PDF 旋转任务的 `scripts/rotate_pdf.py`
-   **好处**：Token 高效、确定性、可以在不加载到上下文中的情况下执行
-   **注意**：脚本可能仍需要被 Agent 读取以进行修补或特定环境的调整。

##### 参考文档 (`references/`)

旨在根据需要加载到上下文中以通知 Agent 的过程和思考的文档和参考材料。

-   **何时包含**：用于 Agent 在工作时应参考的文档
-   **示例**：用于财务架构的 `references/finance.md`，用于公司 NDA 模板的 `references/mnda.md`，用于公司政策的 `references/policies.md`，用于 API 规范（OpenAPI/Swagger 等）的 `references/api_docs.md`
-   **用例**：数据库架构、API 文档、领域知识、公司政策、详细工作流指南
-   **好处**：保持 `SKILL.md` 精简，仅在 Agent 确定需要时加载
-   **最佳实践**：如果文件很大（>10k 词），请在 `SKILL.md` 中包含 grep 搜索模式
-   **避免重复**：信息应存在于 `SKILL.md` 或参考文件中，而不是两者都存在。除非它是技能真正的核心，否则倾向于将详细信息放在参考文件中——这保持了 `SKILL.md` 的精简，同时使信息可被发现而不占用上下文窗口。在 `SKILL.md` 中仅保留必要的程序说明和工作流指导；将详细的参考材料、架构和示例移动到参考文件中。

##### 静态资源 (`assets/`)

不打算加载到上下文中，而是在 Agent 生成的输出中使用的文件。

-   **何时包含**：当技能需要将在最终输出中使用的文件时
-   **示例**：用于品牌视觉的 `assets/logo.png`，用于演示文稿的 `assets/slides.pptx`，用于代码框架的 `assets/frontend-template/`，用于排版的 `assets/font.ttf`
-   **用例**：模板、图像、图标、脚手架代码、字体、被复制或修改的示例文档
-   **好处**：将输出资源与文档分离，使 Agent 能够使用文件而不将它们加载到上下文中

#### 技能中不应包含的内容

技能应仅包含直接支持其功能的必要文件。不要创建无关的文档或辅助文件，包括：

-   README.md
-   INSTALLATION_GUIDE.md
-   QUICK_REFERENCE.md
-   CHANGELOG.md
-   等

技能应仅包含 Agent 完成手头工作所需的信息。它不应包含关于创建过程、设置和测试程序、面向用户的文档等的辅助上下文。创建额外的文档文件只会增加混乱和困惑。

### 渐进式披露设计原则

技能使用三级加载系统来有效地管理上下文：

1.  **元数据 (名称 + 描述)** - 始终在上下文中（~100 词）
2.  **SKILL.md 正文** - 当技能触发时 (<5k 词)
3.  **配套资源** - 根据 Agent 的需要（无限制，因为脚本可以在不读入上下文窗口的情况下执行）

#### 渐进式披露模式

保持 `SKILL.md` 正文为必需内容且在 500 行以内，以最小化上下文膨胀。接近此限制时将内容拆分到单独的文件中。当将内容拆分到其他文件时，务必在 `SKILL.md` 中引用它们并清楚地描述何时读取它们，以确保技能的读者知道它们的存在以及何时使用它们。

**关键原则：** 当一个技能支持多种变体、框架或选项时，在 `SKILL.md` 中仅保留核心工作流和选择指导。将特定于变体的细节（模式、示例、配置）移动到单独的参考文件中。

**模式 1：带参考的高级指南**

From chuanyue98/CodeAgent, MIT.

More from chuanyue98/CodeAgent