Skill Creator

Agent 技能创建标准

优先级：P0（关键）

编写高密度 Agent 技能的严格指南。通过渐进式披露和策略性内容组织，在最大限度降低 token 消耗的同时提高信息密度。

核心原则

优先考虑 token 经济性 ⚡

每个词都会消耗 token。设计技能时，应最大化信息/token 比率：

• 渐进式加载：初始仅加载必要内容
• 延迟引用：将详细示例移至 references/ 文件夹
• 祈使式精简：使用动词、缩写和项目符号
• 关注上下文窗口：针对不同 Agent 的 4k-32k token 限制进行设计

三级加载系统

Level 1: Metadata (100 words) → Always loaded
Level 2: SKILL.md Body (100 lines) → When triggered
Level 3: References/Scripts/Assets → As needed

目录结构

skills/
└── {category}/                     # e.g., "flutter" (lowercase)
    └── {skill-name}/               # e.g., "bloc-state-management" (kebab-case)
        ├── SKILL.md                # Core Logic (High Density, <100 lines)
        ├── scripts/                # Executable code (Deterministic tasks)
        │   └── automation.py
        ├── references/             # Heavy Examples (Lazy loaded)
        │   ├── patterns.md
        │   └── examples.md
        └── assets/                 # Output templates (Never loaded)
            └── template.json

编写规则（针对 token 优化）

1. 祈使式精简：以动词开头。不要使用“请/你应该”。

   • 冗余：“你应该使用 BLoC 进行状态管理。”（8 个词）
   • 精简：“使用 BLoC 进行状态管理。”（5 个词）

2. token 经济性：最大化信息/token 比率。

   • 在不影响可读性的前提下省略冠词（“the”“a”）
   • 使用标准缩写（cfg、param、impl）
   • 项目符号 > 段落（密度提高 3 倍）

3. 渐进式披露：先提供必要信息，按需提供详细内容。

   • 在 SKILL.md 中放入核心工作流
   • 在 references/ 中放入复杂示例
   • 不加载模板/资源

4. 上下文感知设计：不同 Agent 的限制各不相同。

   • Cursor：约 100k 个 token
   • Claude：约 200k 个 token
   • Windsurf：约 32k 个 token

内容章节（按 token 预算）

SKILL.md 中必须包含以下章节：

1. Frontmatter（必填）：用于触发的元数据（最多 100 个词）

   ---
   name: Skill Name
   description: What it does + when to use it (triggers activation)
   metadata:
     labels: [tag1, tag2]
     triggers:
       files: ['**/*.ext']
       keywords: [term1, term2]
   ---
   

2. 优先级：P0（关键）、P1（标准）或 P2（可选）

3. 结构：预期文件布局的 ASCII 树形图

4. 指南：以“这样做”为主题的项目符号列表（祈使式）

5. 反模式：以“不要这样做”为主题的项目符号列表

6. 参考链接：指向 references/ 文件的链接（延迟加载）

大小限制（严格）

元素	限制	超出限制时的处理方式
SKILL.md 总计	100 行	提取至 references/
内联代码块	10 行	移至 references/
反模式条目	15 个词	精简为祈使句
Priority 后的说明	0 行	删除（使用 frontmatter）
表格	8 行	提取至 references/
解释性章节	10 行	提取至 references/

资源组织（节省 token）

scripts/ - 可执行代码

适用场景：确定性、重复性任务
优点：不会加载到上下文中，可直接执行
示例：代码生成器、格式化程序、验证器

references/ - 文档

适用场景：详细示例、API 文档、复杂模式
优点：仅在需要时加载，保持 SKILL.md 精简
示例：实现模式、错误处理指南

assets/ - 输出模板

适用场景：样板文件、图像、配置
优点：不会加载，需要时复制到输出中
示例：项目模板、配置文件、图标

技能创建生命周期

阶段 1：理解（token 审计）

1. 定义具体用例
2. 识别重复模式
3. 计算每个 Agent 的 token 预算

阶段 2：规划（资源策略）

1. 核心工作流 → SKILL.md
2. 复杂示例 → references/
3. 重复代码 → scripts/
4. 模板 → assets/

阶段 3：实现（精简）

1. 编写祈使式指南
2. 将示例精简至必要内容
3. 测试是否适配上下文窗口

阶段 4：验证（token 测试）

1. 验证加载效率
2. 在不同 Agent 中进行测试
3. 衡量 token 消耗

验证清单

完成前，请检查：

• SKILL.md ≤100 行（理想长度：40-60 行）
• 内联代码不超过 10 行
• 未重复 frontmatter 内容
• 反模式符合严格格式（见下文）
• 复杂示例位于 references/
• 超过 8 行的表格已移至 references/
• Priority 后没有重复描述

反模式（浪费令牌的写法）

• 冗长解释：“这很重要，因为……” → 删除
• 冗余上下文：不要在多个位置重复相同信息
• 大型内联代码：将超过 10 行的代码移至 references/
• 对话式风格：“我们来看看如何……” → “执行此操作：”
• 过度设计：简单的 skill 不要使用复杂结构
• 冗余描述：不要在 ## Priority 后重复 frontmatter 中的 description
• 超大 Skill：SKILL.md 超过 100 行 → 提取到 references/
• 嵌套格式：避免使用 **粗体**：\更多粗体``，以免造成视觉干扰
• 冗长的反模式：参见下方的严格格式

反模式格式（严格）

格式：**No X**: Do Y[, not Z]. [Optional context, max 15 words total]

示例：

❌ Verbose (24 words):

- **No Manual Emit**: `**Avoid .then()**: Do not call emit() inside Future.then; always use await or emit.forEach.`

✅ Compressed (11 words):

- **No .then()**: Use `await` or `emit.forEach()` to emit states.

❌ Verbose (18 words):

- **No UI Logic**: `**Logic in Builder**: Do not perform calculations or data formatting inside BlocBuilder.`

✅ Compressed (9 words):

- **No Logic in Builder**: Perform calculations in BLoC, not UI.

渐进式披露清单

在以下情况下，提取到 references/：

• 代码示例超过 10 行
• 表格超过 8 行
• 说明性章节超过 10 行
• 存在多个代码变体或替代方案
• 有详细的性能基准
• 有分步教程

参考资料与示例

使用以下增强模板来生成新的 skill： references/TEMPLATE.md

获取全面的生命周期指南： references/lifecycle.md

获取资源组织模式： references/resource-organization.md