creating-skills

创建技能

此技能提供在 Letta Code 中创建有效技能的指南。完整的官方规范请参阅 agentskills.io。

关于技能

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

技能提供什么

1. 专业工作流——针对特定领域的多步骤流程
2. 工具集成——使用特定文件格式或 API 的说明
3. 领域专业知识——公司专属知识、架构、业务逻辑
4. 捆绑资源——用于复杂和重复任务的脚本、参考资料和资源

核心原则

简洁至关重要

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

默认假设：Letta Code Agent 已经非常强大。 只添加 Letta Code Agent 尚不具备的上下文。审视每条信息：“Letta Code Agent 真的需要这段说明吗？”以及“这一段内容值得占用这些 token 吗？”

优先使用简洁的示例，而非冗长的说明。

设定适当的自由度

根据任务的脆弱性和可变性，匹配具体程度：

高自由度（基于文本的说明）：适用于存在多种有效方法、决策取决于上下文或通过启发式方法指导操作的情况。

中自由度（伪代码或带参数的脚本）：适用于存在首选模式、允许一定变化或配置会影响行为的情况。

低自由度（特定脚本、少量参数）：适用于操作脆弱且容易出错、必须保持一致，或必须遵循特定顺序的情况。

可以把 Letta Code Agent 想象成在探索一条路径：悬崖边的窄桥需要具体的护栏（低自由度），而开阔地带则允许多种路线（高自由度）。

技能的构成

每项技能都包含一个必需的 SKILL.md 文件和可选的捆绑资源：

processing-pdfs/
├── SKILL.md (required)
│   ├── YAML frontmatter metadata (required)
│   │   ├── name: (required, must match directory name)
│   │   └── description: (required)
│   └── Markdown instructions (required)
└── Bundled Resources (optional)
    ├── scripts/          - Executable code (TypeScript/Python/Bash/etc.)
    ├── references/       - Documentation intended to be loaded into context as needed
    └── assets/           - Files used in output (templates, icons, fonts, etc.)

SKILL.md（必需）

Letta Code 中的每个 SKILL.md 都包含：

• Frontmatter（YAML）：包含 name 和 description 字段。这是 Letta Code Agent 判断何时使用该技能时读取的唯一字段，因此务必清晰、全面地描述技能的内容及其适用时机。
• 正文（Markdown）：使用该技能的说明和指导。只有在技能触发后才会加载（如果触发的话）。

捆绑资源（可选）

脚本（scripts/）

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

• 适用情况：相同代码被反复重写，或需要确定性可靠性时
• 示例：用于 PDF 旋转任务的 scripts/rotate-pdf.ts
• 优点：节省 token、结果确定，且无需加载到上下文中即可执行
• 注意：Letta Code Agent 可能仍需读取脚本，以便进行补丁修改或针对特定环境调整

参考资料（references/）

文档和参考资料，可按需加载到上下文中，为 Letta Code Agent 的流程和思考提供参考。

• 适用情况：Letta Code Agent 工作时需要查阅的文档
• 示例：references/finance.md（财务架构）、references/mnda.md（公司 NDA 模板）、references/policies.md（公司政策）、references/api_docs.md（API 规范）
• 用途：数据库架构、API 文档、领域知识、公司政策、详细的工作流指南
• 优点：让 SKILL.md 保持精简，仅在 Letta Code Agent 判断有需要时才加载
• 最佳实践：如果文件较大（超过 10k 词），请在 SKILL.md 中加入 grep 搜索模式
• 避免重复：信息应放在 SKILL.md 或参考资料文件中，而不是两者都放。除非某项信息确实是技能的核心内容，否则详细信息优先放在参考资料文件中——这样既能让 SKILL.md 保持精简，又能让信息易于查找，同时避免占用过多上下文窗口。SKILL.md 中只保留必要的操作说明和工作流指南；将详细参考资料、架构和示例移至参考资料文件。

资源文件（assets/）

不用于加载到上下文中，而是在 Letta Code Agent 生成输出时使用的文件。

• 适用情况：技能需要在最终输出中使用文件时
• 示例：assets/logo.png（品牌资源）、assets/slides.pptx（PowerPoint 模板）、assets/frontend-template/（HTML/React 样板代码）、assets/font.ttf（字体）
• 用途：模板、图像、图标、样板代码、字体、可复制或修改的示例文档
• 优点：将输出资源与文档分开，让 Letta Code Agent 无需将文件加载到上下文中即可使用

技能中不要包含的内容

技能应只包含直接支持其功能所必需的文件。请勿创建多余的文档或辅助文件，包括：

• README.md
• INSTALLATION_GUIDE.md
• QUICK_REFERENCE.md
• CHANGELOG.md
• 等等

技能只应包含 AI Agent 完成当前任务所需的信息。不要包含关于创建过程的辅助上下文、设置和测试流程、面向用户的文档等。创建额外的文档文件只会增加混乱和困惑。

渐进式披露设计原则

技能采用三级加载系统，高效管理上下文：

1. 元数据（名称 + 描述） - 始终位于上下文中（约 100 词）
2. SKILL.md 正文 - 技能触发时加载（少于 5k 词）
3. 捆绑资源 - Letta Code Agent 按需加载（无限制，因为脚本可以直接执行，无需读入上下文窗口）

渐进式披露模式

将 SKILL.md 正文精简至必要内容，并控制在 500 行以内，以尽量减少上下文膨胀。接近此限制时，将内容拆分到单独的文件中。将内容拆分到其他文件时，务必在 SKILL.md 中引用这些文件，并清楚说明何时阅读它们，确保技能的读者知道这些文件的存在以及何时使用它们。

核心原则： 当技能支持多种变体、框架或选项时，SKILL.md 中只保留核心工作流和选择指南。将特定于变体的详细信息（模式、示例、配置）移至单独的参考文件。

模式 1：高级指南与参考文件

# PDF Processing

## Quick start

Extract text with pdfplumber:
[code example]

## Advanced features

- **Form filling**: See [FORMS.md](FORMS.md) for complete guide
- **API reference**: See [REFERENCE.md](REFERENCE.md) for all methods
- **Examples**: See [EXAMPLES.md](EXAMPLES.md) for common patterns

Letta Code Agent 仅在需要时才加载 FORMS.md、REFERENCE.md 或 EXAMPLES.md。

模式 2：按领域组织

对于包含多个领域的技能，按领域组织内容，以避免加载无关上下文：

querying-bigquery/
├── SKILL.md (overview and navigation)
└── references/
    ├── finance.md (revenue, billing metrics)
    ├── sales.md (opportunities, pipeline)
    ├── product.md (API usage, features)
    └── marketing.md (campaigns, attribution)

当用户询问销售指标时，Letta Code Agent 只读取 sales.md。

同样，对于支持多个框架或变体的技能，也应按变体组织：

deploying-to-cloud/
├── SKILL.md (workflow + provider selection)
└── references/
    ├── aws.md (AWS deployment patterns)
    ├── gcp.md (GCP deployment patterns)
    └── azure.md (Azure deployment patterns)

当用户选择 AWS 时，Letta Code Agent 只读取 aws.md。

模式 3：条件式详细信息

展示基本内容，并链接至高级内容：

# DOCX Processing

## Creating documents

Use docx-js for new documents. See [DOCX-JS.md](DOCX-JS.md).

## Editing documents

For simple edits, modify the XML directly.

**For tracked changes**: See [REDLINING.md](REDLINING.md)
**For OOXML details**: See [OOXML.md](OOXML.md)

只有当用户需要相关功能时，Letta Code Agent 才会读取 REDLINING.md 或 OOXML.md。

重要指南：

• 避免多层嵌套引用——引用应与 SKILL.md 保持一层之隔。所有参考文件都应由 SKILL.md 直接链接。
• 为较长的参考文件添加结构——对于超过 100 行的文件，应在顶部添加目录，以便 Letta Code Agent 在预览时了解其完整范围。

技能创建流程

技能创建包含以下步骤：

1. 使用具体示例了解技能
2. 规划可复用的技能内容（脚本、参考文件、资源）
3. 初始化技能（运行 init-skill.ts）
4. 编辑技能（实现资源并编写 SKILL.md）
5. 打包技能（运行 package-skill.ts）
6. 根据实际使用情况迭代

请按顺序执行这些步骤，只有在有明确理由表明某一步不适用时才跳过。

步骤 1：通过具体示例了解技能

只有当技能的使用模式已明确了解时，才跳过此步骤。即使是在处理现有技能时，这一步仍然很有价值。

要创建有效的技能，必须清楚了解该技能的具体使用方式。这种了解可以来自用户直接提供的示例，也可以来自经用户反馈验证的生成示例。

例如，构建 editing-images 技能时，相关问题包括：

• “editing-images 技能应支持哪些功能？编辑、旋转，还有其他功能吗？”
• “能否举一些该技能的使用示例？”
• “我能想到用户可能会提出诸如‘去掉这张图片中的红眼’或‘旋转这张图片’之类的需求。你还能想到其他使用方式吗？”
• “用户说什么话时应该触发此技能？”

为避免让用户应接不暇，不要在一条消息中提出太多问题。先提出最重要的问题，再根据需要追问，以便更好地了解需求。

当你清楚了解该技能应支持的功能后，即可结束此步骤。

步骤 2：规划可复用的技能内容

要将具体示例转化为有效的技能，请分析每个示例：

1. 思考如何从头开始完成该示例
2. 找出在重复执行这些工作流时，有哪些脚本、参考资料和素材会派上用场

示例：创建 editing-pdfs 技能来处理“帮我旋转这个 PDF”之类的请求时，分析表明：

1. 每次旋转 PDF 都需要重新编写相同的代码
2. 可以在技能中保存一个 scripts/rotate-pdf.ts 脚本

示例：设计 building-frontend-apps 技能来处理“帮我构建一个待办事项应用”或“帮我构建一个用于追踪步数的仪表板”之类的请求时，分析表明：

1. 每次编写前端 Web 应用都需要使用相同的样板 HTML/React 代码
2. 可以在技能中保存一个 assets/hello-world/ 模板，其中包含样板 HTML/React 项目文件

示例：创建 querying-bigquery 技能来处理“今天有多少用户登录了？”之类的请求时，分析表明：

1. 每次查询 BigQuery 都需要重新查找表结构及其关系
2. 可以在技能中保存一个用于记录表结构的 references/schema.md 文件

要确定技能的内容，请分析每个具体示例，并列出要纳入的可复用资源：脚本、参考资料和素材。

步骤 3：初始化技能

现在可以开始实际创建技能了。

只有在要开发的技能已存在，且需要迭代或打包时，才跳过此步骤。此时请继续下一步。

从头创建新技能时，始终运行 init-skill.ts 脚本。该脚本会便捷地生成新的技能模板目录，并自动包含技能所需的一切，从而让技能创建过程更加高效、可靠。

用法：

npx tsx <SKILL_DIR>/scripts/init-skill.ts <skill-name> --path <output-directory>

其中，<SKILL_DIR> 是加载技能时显示的技能目录（可在注入标头中查看）。

该脚本会：

• 在指定路径创建技能目录
• 生成包含适当 frontmatter 和 TODO 占位符的 SKILL.md 模板
• 创建示例资源目录：scripts/、references/ 和 assets/
• 在每个目录中添加可自定义或删除的示例文件

初始化后，根据需要自定义或删除生成的 SKILL.md 和示例文件。

步骤 4：编辑技能

编辑（新生成或已有的）技能时，请记住，该技能是为另一个 Letta Code Agent 实例使用而创建的。请纳入对 Letta Code Agent 有帮助且不显而易见的信息。考虑哪些流程知识、特定领域的细节或可复用素材能帮助另一个 Letta Code Agent 实例更有效地完成这些任务。

了解经过验证的设计模式

根据技能需求，查阅以下实用指南：

• 多步骤流程：参阅 references/workflows.md，了解顺序工作流和条件逻辑
• 特定输出格式或质量标准：参阅 references/output-patterns.md，了解模板和示例模式

这些文件包含经过验证的最佳实践，可帮助设计出有效的技能。

从可复用的技能内容入手

开始实现时，先使用上面确定的可复用资源：scripts/、references/ 和 assets/ 文件。请注意，此步骤可能需要用户提供输入。例如，实现 brand-guidelines 技能时，用户可能需要提供品牌素材或模板，存放到 assets/ 中，或者提供文档，存放到 references/ 中。

必须实际运行新增脚本并进行测试，以确保没有错误且输出符合预期。如果有许多相似的脚本，只需测试有代表性的样本，以确认它们都能正常工作，同时兼顾完成时间。

删除技能不需要的所有示例文件和目录。初始化脚本会在 scripts/、references/ 和 assets/ 中创建示例文件以展示结构，但大多数技能不会用到所有这些文件。

更新 SKILL.md

写作指南： 始终使用祈使式或不定式。

Frontmatter

编写包含 name 和 description 的 YAML frontmatter：

name（必填）：

• 使用动名词形式：processing-pdfs、analyzing-data、creating-reports（而不是 pdf-processor）
• 只能使用小写字母、数字和连字符
• 必须与目录名称完全一致
• 最长 64 个字符

description（必填）：

• 使用第三人称撰写：“处理 PDF 文件……”（不要写“我可以帮你处理……”或“你可以用它来……”）
• 说明技能的功能以及适用场景
• 包含有助于 Agent 识别相关任务的触发关键词
• 最长 1024 个字符

示例：

---
name: processing-pdfs
description: Extracts text and tables from PDF files, fills forms, and merges documents. Use when working with PDF files or when the user mentions PDFs, forms, or document extraction.
---

注意： 规范允许使用可选字段（license、compatibility、metadata、allowed-tools），但大多数技能不需要这些字段。详情请参阅 agentskills.io/specification。

正文

编写使用技能及其捆绑资源的说明。

第 5 步：打包技能

技能开发完成后，必须将其打包成可分发的 .skill 文件并分享给用户。打包过程会先自动验证技能，确保其满足所有要求：

npx tsx <SKILL_DIR>/scripts/package-skill.ts <path/to/skill-folder>

可选的输出目录指定方式：

npx tsx <SKILL_DIR>/scripts/package-skill.ts <path/to/skill-folder> ./dist

打包脚本将：

1. 验证技能，自动检查：

   • YAML frontmatter 格式和必填字段
   • 技能命名规范和目录结构
   • 描述的完整性和质量
   • 文件组织和资源引用

2. 如果验证通过，则打包技能，创建一个以技能命名的 .skill 文件（例如，my-skill.skill），其中包含所有文件，并保留适合分发的目录结构。.skill 文件是扩展名为 .skill 的 zip 文件。

如果验证失败，脚本将报告错误并退出，不会创建软件包。修复所有验证错误后，再次运行打包命令。

第 6 步：迭代

测试技能后，用户可能会要求改进。通常，这种情况会在使用技能后立即发生，此时用户对技能的表现记忆犹新。

迭代工作流：

1. 在实际任务中使用技能
2. 留意使用中的困难或低效之处
3. 确定应如何更新 SKILL.md 或捆绑资源
4. 实施更改并再次测试