Agent Skills 笔记-编程实验室

更多的是在工程概念上的革新，而不是功能上的革新。

Agent Skills 规范是 Anthropic 在 Claude Code 落地的标准化概念（2025-10），目前作为跨平台开放标准（2025-12）。

可迁移：通用标准规范，适配不同 Agent。
抽象化：解决需要为每个专用领域微调对应模型的问题，将专业技能抽象为可被提取到外部的脚手架能力，适配当前多模态 LLM 的发展趋势（MCP、Skill）。
可预测：支持可重复的工作流程，提供清晰的任务和指令，让 Agent 流程规范化建设。
可组合：多个 Skill 之间可以组合成工作流完成复杂任务。
渐进式披露：在开始时只会加载 SKILL.md 名称（name）和描述（description）到上下文中，只有当名称和描述符合 AI 调用需求时，才会去读取 SKILL.md 主体内容进行分析。
按需加载：外部资源时按需加载；脚本执行时在独立上下文中执行，不会引入额外内容污染上下文。

最佳实践

Skill 标准会逐步演进，所以下面的内容可能会过期。
目前感觉各家编程助手对 Skills 的理解规范都不一致，这里是参考了 Claude Code 的教程规范。

在.claude/skills或.cursor/skills目录下定义 skill。
以 Cursor 为例，定义成功后可以在 Cursor Setting 中看到 skill 信息

使用方式和 Command 指令一样，通过/skill-name调用

SKILL.md 元信息（Front Formatter）

名称（name）：

最大 64 个字符。
只包含小写字符、数字、连字符（hyphens）。
不要把连字符作为开始和结束符号。
必须匹配目录名称。
使用动名词形式（gerund form，即 ing 结尾）。

描述（description）：

最大 1024 字符且非空。
描述能做什么（what）、什么时候使用（when）。
包含关键词，帮助编程助手理解能处理的相关任务。

其他 Front Formatter（适配中）：

版权文件（license）：提供版权名称（MIT、BSD 等）或描述版权信息的文件。
兼容性（compatibility）：最大 500 字符，描述环境要求。
元数据（metadata）：任意键值对信息。
允许内置工具（allowed-tools）：通过分隔符列出的允许使用的内置工具（如 BASH、WRITE、READ）。

SKILL.md 主体内容

格式：无固定格式要求，根据自己需要编写（Markdown）。

推荐编写内容：

执行步骤：Step1、Step2，步骤尽量切割清晰。（步骤）。
输入输出格式，或给出输入输出示例（样例）。
常见边界条件和情况（Common edge cases，约束条件）。

内容结构：

内容尽量精简：建议 500 字符以内；具体细节放到单独 Markdown 文件中，SKILL.md 只展示基础信息、链接与领域相关内容（domain-specific content）。
单层引用：存在多层级引用时，SKILL.md 只保留一级文档的引用；二级由一级文档内部引入，不写在 SKILL.md 中。

# 这里是文档引用层级，不是目录结构 SKILL.md # 核心文件：记录技能清单 ├─ JS.md # SKILL.md 引用（一级） │ └─ ES6.md # JS.md 引用（二级） └─ React.md # SKILL.md 引用（一级） └─ Hooks.md # React.md 引用（二级）

保持 SKILL.md 简洁（clear and concise）、术语一致性（consistent terminology）。
所有系统下文件路径均使用正斜杠（forward slashes）。
保证执行步骤尽量可预测，即用户输入信息可以得到想要的输出结构。

内容主题

自由度考量

高自由度（High freedom）：基于文本的通用指令，多种实现方法均有效。
中自由度（Medium freedom）：指令包含可自定义的伪代码、代码示例或代码模式；存在推荐模式，但允许一定变体。
低自由度（Low freedom）：指令指向特定脚本，须遵循固定执行顺序。

复杂度考量

文档切分、步骤切分，保证流程清晰。
保留技能单一整洁，通过工作流模式来构建整体业务。

script（需执行的脚本）：
- 脚本结构整洁，依赖树清晰，可以在脚本开头添加注释信息。
- 执行异常时，给出有用的错误输出。
references（可阅读的文档引用）：
- 尽量引入个人文档，文档内可以包含可参考的其他文档。
- 单份文档超过 100 行时，可在文件开头编写目录，便于 AI 快速获取相关信息，也可以在开头添加概览，便于 AI 快速理解文档的作用。
assets（资源文件）：
- 模板：文档模板、配置模板，通过参数与注释补充使用说明。
- 图片：logo、各类图片资源。
- 数据集：参数、数据表等。

.claude/skills/my-task-agent/ ├── SKILL.md # 技能的身份标签（Meta & Trigger） ├── scripts/ # 可执行逻辑 - 按需执行 │ ├── main.py │ └── helper.sh ├── assets/ # 可使用资源 - 按需加载 │ ├── config_template.yaml │ ├── logo.png │ └── prompt_snippet.txt └── references/ # 可参考的文档 - 局部 RAG 按需读取 └── style_guide.md # 代码或文案风格参考