Skills 是一组指令和资源的文件夹，Kiro 可以自动发现并使用它们来更准确地处理任务。每个 Skill 存放在一个 SKILL.md 文件中，文件头部（frontmatter）包含名称和描述信息。

描述信息是 Kiro 决定是否使用该 Skill 的依据。当你要求 Kiro 审查一个 PR 时，它会将你的请求与所有可用的 Skill 描述进行匹配，找到相关的那个。Kiro 读取你的请求，将其与所有可用的 Skill 描述进行比较，然后激活匹配的 Skill。

以下是 Skill 的 frontmatter 示例：

--- name: pr-review description: Reviews pull requests for code quality. Use when reviewing PRs or checking code changes. --- 

在 frontmatter 下方，你编写实际的指令——你的审查清单、格式偏好，或者 Kiro 完成该任务所需的任何信息。

Skills 遵循开放的 Agent Skills 标准，可以在不同工具和团队之间共享。

你可以根据使用范围将 Skills 存放在不同位置：

• 工作区 Skills 存放在项目根目录的 .kiro/skills/ 中。任何克隆该仓库的人都会自动获得这些 Skills。这里适合存放团队标准，比如公司的品牌指南、编码规范等。
• 全局 Skills 存放在 ~/.kiro/skills/（你的主目录）。这些 Skills 会跟随你在所有项目中使用——你的提交信息风格、文档格式、你喜欢的代码审查方式等。

当工作区 Skills 和全局 Skills 同名时，工作区 Skills 优先。这允许你定义通用的全局 Skills，同时为特定项目进行覆盖。

工作区 Skills 会随代码一起提交到版本控制系统，因此整个团队都能共享。

Kiro 有多种自定义行为的方式。以下是它们的对比：

• Skills 是遵循开放标准的可移植指令包。它们按需加载，可以包含脚本。适用于你想要共享或从他人处导入的可复用工作流。
• Steering 是 Kiro 特有的上下文，用于塑造 agent 行为。支持 always、auto、fileMatch 和 manual 模式。适用于项目标准和约定。
• Powers 将 MCP 工具与知识和工作流打包在一起。它们根据上下文动态激活。适用于需要工具和指导的集成场景。

提示：Steering 文件中的 auto 模式与 Skills 的工作方式类似——Kiro 使用描述来决定何时加载。但 Skills 是跨工具可移植的开放标准，而 Steering 是 Kiro 特有的。

Skills 最适合用于针对特定任务的专业知识：

• 团队遵循的代码审查标准
• 你偏好的提交信息格式
• 组织的品牌指南
• 特定类型文档的模板
• 特定框架的调试清单

经验法则很简单：如果你发现自己反复向 Kiro 解释同样的事情，那就是一个等待被编写的 Skill。

• Skills 是一组指令文件夹，Kiro 可以自动发现并使用它们来更准确地处理任务。每个 Skill 存放在一个 SKILL.md 文件中，文件头部包含名称和描述
• Kiro 使用描述来匹配 Skills 与请求。当你要求 Kiro 做某事时，它会将你的请求与可用的 Skill 描述进行比较，并激活匹配的那些
• 全局 Skills 存放在 ~/.kiro/skills/，跟随你在所有项目中使用。工作区 Skills 存放在项目内的 .kiro/skills/ 中，与克隆仓库的所有人共享
• Skills 按需加载——只有在 Kiro 识别到相关场景时才自动激活，不会占满上下文窗口
• 如果你发现自己反复向 Kiro 解释同样的事情，那就是一个等待被编写的 Skill

我们将构建一个全局 Skill，教会 Kiro 如何以一致的格式编写 PR 描述。由于这是全局 Skill，它存放在你的主目录中，可在所有项目中使用。

首先，在 skills 文件夹内为你的 Skill 创建一个目录。目录名应与你的 Skill 名称一致：

mkdir -p ~/.kiro/skills/pr-description 

然后在该目录内创建一个 SKILL.md 文件。文件由 frontmatter 分隔线分为两部分：

--- name: pr-description description: Writes pull request descriptions. Use when creating a PR, writing a PR, or when the user asks to summarize changes for a pull request. ---  When writing a PR description:  1. Run `git diff main...HEAD` to see all changes on this branch 2. Write a description following this format:   What One sentence explaining what this PR does.   Why Brief context on why this change is needed   Changes - Bullet points of specific changes made - Group related changes together - Mention any files deleted or renamed 

name 标识你的 Skill。description 告诉 Kiro 何时使用它——这是匹配条件。第二组分隔线之后的所有内容是 Kiro 在 Skill 被激活时遵循的指令。

除了手动创建，你还可以通过 Kiro 面板导入 Skill：

1. 打开 Kiro 面板中的 Agent Steering & Skills 区域
2. 点击 + 并选择 Import a skill
3. 选择来源：
   • GitHub ——从公开仓库 URL 导入。你可以粘贴指向 Skill 文件夹或直接指向 SKILL.md 文件的 URL。URL 必须指向仓库中的子目录，而不是仓库根目录。
   • Local folder ——从本地文件系统导入

导入的 Skills 会被复制到你的 skills 目录中，并立即可用。

默认 agent 会自动从两个位置加载 Skills，无需额外配置。你可以通过以下方式验证 Skill 是否可用：

• 在 Kiro IDE 中，查看 Agent Steering & Skills 面板
• 在 Kiro CLI 中，直接询问 Kiro “有哪些可用的 Skills”

要测试它，在一个分支上做一些更改，然后说类似"为我的更改写一个 PR 描述"的话。Kiro 会提示它正在使用 PR 描述 Skill，检查你的 diff，并按照你的模板编写描述——每次格式都一样。

当 Kiro 启动时，它会扫描 Skills 目录，但只加载名称和描述——不加载完整内容。这是一个重要的细节。

当你发送请求时，Kiro 会将你的消息与所有可用 Skills 的描述进行比较。一旦找到匹配，Kiro 加载完整的 SKILL.md 文件并遵循其指令。

Skills 基于你的请求自动激活，无需斜杠命令来调用它们。Kiro 通过将你的请求与 Skill 描述进行匹配来决定何时使用某个 Skill。

注意：在 Kiro IDE 中，你也可以在聊天输入框中输入 / 来查看可用的 Skills 作为斜杠命令，手动选择加载。

当工作区 Skills 和全局 Skills 同名时，工作区 Skills 优先。这允许你定义通用的全局 Skills，同时为特定项目进行覆盖。

注意：Kiro 的优先级体系为两级（工作区 → 全局），不同于 Claude Code 的四级体系。Kiro 不支持 Enterprise 和 Plugins 级别的 Skills。

为避免冲突，请使用描述性名称。不要只用 “review”，而是使用类似 “frontend-review” 或 “backend-review” 这样的名称。

要更新 Skill，编辑其 SKILL.md 文件。要删除 Skill，删除其目录。更改后 Skills 会立即生效。

• Skill 是一个包含 SKILL.md 文件的目录，文件头部有元数据（名称、描述），下方是指令内容
• Kiro 在启动时只加载 Skill 的名称和描述，然后使用语义匹配将传入的请求与这些描述进行比较
• 名称冲突时的优先级：工作区（Workspace）→ 全局（Global）
• 要更新 Skill，编辑其 SKILL.md。要删除 Skill，删除其目录

Agent Skills 开放标准在 SKILL.md 的 frontmatter 中支持多个字段：

注意：Claude Code 支持的 allowed-tools 和 model 字段在 Kiro 中不受支持。allowed-tools 在 Agent Skills 开放标准中标注为实验性（Experimental），Kiro 官方文档未列出此字段。model 是 Claude Code 专有字段，不在开放标准中。

指令要明确。如果有人告诉你"你的工作是帮忙写文档"，你不知道该做什么——Kiro 也是一样。

一个好的描述需要回答两个问题：

1. 这个 Skill 做什么？
2. Kiro 应该在什么时候使用它？

如果你的 Skill 没有在预期时触发，试着添加更多与你实际表述方式匹配的关键词。描述是 Kiro 用来判断 Skill 是否相关的依据，因此措辞很重要。

好的描述示例：

description: Review pull requests for security vulnerabilities and test coverage. Use when reviewing PRs or preparing code for review. 

不好的描述示例：

description: Helps with code review 

Skills 与你的对话共享 Kiro 的上下文窗口。当 Kiro 激活一个 Skill 时，它会将该 SKILL.md 的内容加载到上下文中。但有时你需要 Skill 依赖的参考资料、示例或工具脚本。

将所有内容塞进一个 2,000 行的文件有两个问题：它会占用大量上下文窗口空间，而且维护起来很痛苦。

渐进式披露解决了这个问题。将核心指令保留在 SKILL.md 中，将详细的参考资料放在单独的文件中，Kiro 仅在需要时才读取。

开放标准建议按以下方式组织你的 Skill 目录：

my-skill/ ├── SKILL.md # 必需：元数据 + 指令 ├── scripts/ # 可选：可执行代码 ├── references/ # 可选：附加文档 └── assets/ # 可选：模板、资源 

然后在 SKILL.md 中，链接到支持文件并明确说明何时加载它们：

For ECS deployments, follow the guide in `references/ecs-guide.md`. 

Kiro 仅在指令引导时才加载参考文件。

经验法则：将 SKILL.md 保持在 500 行以内。如果超过了，考虑是否应该将内容拆分到单独的参考文件中。

已知问题：截至目前，全局 Skills（~/.kiro/skills/）中的相对文件引用可能无法正确解析。这是因为 Skill 内容被注入时不包含 Skill 目录的路径上下文。工作区 Skills 通常不受此影响。详见 GitHub Issue #6955。

Skill 目录中的脚本可以在不将其内容加载到上下文中的情况下运行。脚本执行后，只有输出会消耗 token。在 SKILL.md 中需要包含的关键指令是告诉 Kiro 运行脚本，而不是读取它。

这对以下场景特别有用：

• 环境验证
• 需要保持一致性的数据转换
• 作为经过测试的代码比生成代码更可靠的操作

• name 和 description 是必填字段——license、compatibility、metadata 是可选补充
• Kiro 不支持 allowed-tools 和 model 字段
• 一个好的描述需要回答两个问题：这个 Skill 做什么？Kiro 应该在什么时候使用它？
• 渐进式披露：将 SKILL.md 保持在 500 行以内，链接到支持文件（references、scripts、assets），Kiro 仅在需要时才读取
• 脚本执行时不会将其内容加载到上下文中——只有输出消耗 token，保持上下文高效

Steering 是 Kiro 特有的上下文机制，通过 .kiro/steering/ 下的 Markdown 文件为 Kiro 提供持久化的项目知识。

Steering 的加载模式：

• always（默认）——加载到每一次对话中
• auto——基于描述匹配自动加载（与 Skills 类似）
• fileMatch——当操作匹配特定文件模式时加载
• manual——通过 #steering-file-name 手动引用加载

使用 Steering 的场景：

• 始终适用的项目级标准
• 约束条件，如"永远不要修改数据库 schema"
• 框架偏好和编码风格
• 项目标准和约定

使用 Skills 的场景：

• 针对特定任务的专业知识
• 需要跨工具共享的可移植工作流
• 包含脚本和参考文件的复杂指令包

关键区别：Skills 遵循开放的 Agent Skills 标准，可以在 Kiro、Claude Code、Codex、Cursor 等工具之间共享。Steering 是 Kiro 特有的，不可移植。

Kiro 支持通过 AGENTS.md 标准提供 Steering 指令。AGENTS.md 文件采用 Markdown 格式，类似于 Kiro 的 Steering 文件，但不支持加载模式配置，始终被加载。

你可以将 AGENTS.md 文件放在全局 Steering 目录（~/.kiro/steering/）或工作区根目录中，Kiro 会自动识别。

注意：Kiro 不支持 Claude Code 的 CLAUDE.md 文件。如果你从 Claude Code 迁移，需要将 CLAUDE.md 的内容转换为 Kiro 的 Steering 文件或 AGENTS.md。

Hooks 基于事件触发。一个 Hook 可能在 Kiro 每次保存文件时运行 linter，或在某些工具调用之前验证输入。它们是事件驱动的。

Skills 是请求驱动的。它们基于你的请求内容激活。

使用 Hooks 的场景：

• 每次文件保存时都应运行的操作
• 特定工具调用之前的验证
• Kiro 操作的自动化副作用

使用 Skills 的场景：

• 影响 Kiro 如何处理请求的知识
• 影响 Kiro 推理过程的指南

Powers 将 MCP 工具与知识和工作流打包在一起。它们根据上下文动态激活。

使用 Powers 的场景：

• 需要外部工具集成的场景（如 AWS、Figma 等）
• 需要工具和指导同时提供的集成

使用 Skills 的场景：

• 纯指令和知识，不需要外部工具
• 需要跨工具可移植的工作流

一个典型的 Kiro 配置可能包括：

• Steering ——始终生效的项目标准和约定
• Skills ——按需加载的特定任务专业知识（跨工具可移植）
• Hooks ——由事件触发的自动化操作
• Powers ——MCP 工具与知识的打包集成

每个功能处理各自的专长。不要在另一个选项更合适时把所有东西都塞进 Skills——而且你可以同时使用多个功能。

• Steering 是 Kiro 特有的上下文机制，支持 always/auto/fileMatch/manual 四种加载模式。Skills 遵循开放标准，按需加载
• Kiro 支持 AGENTS.md 标准（始终加载），但不支持 CLAUDE.md
• Hooks 是事件驱动的（在文件保存、工具调用时触发）。Skills 是请求驱动的（基于你的请求内容激活）
• Powers 提供 MCP 工具集成——与 Skills 是不同的类别
• 每个功能处理各自的专长——将它们组合使用，而不是把所有东西都塞进一种方式

最简单的共享方式是将 Skills 直接提交到你的仓库。将它们放在 .kiro/skills/ 中，任何克隆该仓库的人都会自动获得这些 Skills——无需额外安装。

当你推送更新时，所有人在下次拉取时都会获得更新。这种方式适用于：

• 团队编码标准
• 项目特定的工作流
• 引用你的代码库结构的 Skills

.kiro 目录包含你的 steering、skills、hooks 和 settings——全部通过正常的 Git 工作流进行版本控制并与团队共享。

Kiro 支持直接从 GitHub 公开仓库导入 Skills：

1. 打开 Kiro 面板中的 Agent Steering & Skills 区域
2. 点击 + 并选择 Import a skill
3. 选择 GitHub，粘贴指向 Skill 文件夹或 SKILL.md 文件的 URL

导入的 Skills 会被复制到你的 skills 目录中，立即可用。

由于 Skills 遵循开放的 Agent Skills 标准，你可以从任何兼容工具（Claude Code、Codex、Cursor 等）的社区中导入 Skills。

虽然 Kiro 不支持企业级 Skills 托管，但你可以通过全局 Steering 实现团队级标准共享：

• 团队 Steering 文件可以通过 MDM 解决方案或组策略推送到用户的电脑
• 或者用户从中央仓库下载并放入 ~/.kiro/steering 文件夹

在 Kiro CLI 中，自定义 agents 可以通过 resources 字段显式加载 Skills：

{  "name": "my-agent",  "description": "A custom agent for my workflow",  "tools": ["read", "write"],  "allowedTools": ["read"],  "resources": [  "file://README.md",  "file://.kiro/steering//*.md",  "skill://.kiro/skills//SKILL.md",  "skill://~/.kiro/skills//SKILL.md"  ],  "prompt": "You are a helpful coding assistant",  "model": "claude-sonnet-4-6" } 

skill:// URI 方案支持特定路径、glob 模式和主目录展开。

需要注意的重要区别：

• 默认 agent 会自动从工作区和全局两个位置发现并加载 Skills，无需配置
• 自定义 agents 默认不加载 Skills——你需要在 resources 字段中显式添加 skill:// URI

已知问题：截至目前，自定义 agents 可能不会自动发现 ~/.kiro/skills/ 中的 Skills。详见 GitHub Issue #6888。

• .kiro/skills/ 中的工作区 Skills 通过 Git 自动共享——任何克隆仓库的人都会获得它们
• Kiro 支持从 GitHub 和本地文件系统导入 Skills，兼容 Agent Skills 开放标准的社区生态
• 团队级标准可通过全局 Steering 文件（~/.kiro/steering/）共享
• 自定义 agents 需要在 resources 字段中显式添加 skill:// URI 来加载 Skills
• 默认 agent 自动发现并加载所有 Skills，无需额外配置

本章内容整理自 Agent Skills 官方文档 - For Skill Creators 系列，涵盖**实践、描述优化、效果评估和脚本使用。

创建 Skill 时一个常见的陷阱是让 LLM 在没有领域特定上下文的情况下生成 Skill——仅依赖 LLM 的通用训练知识。结果往往是模糊、泛泛的流程（“适当处理错误”、“遵循认证**实践”），而不是真正有价值的特定 API 模式、边界情况和项目约定。

(1) 从实际任务中提取

在与 agent 的对话中完成一个真实任务，沿途提供上下文、纠正和偏好。然后将可复用的模式提取为 Skill。关注以下几点：

• 成功的步骤——导致成功的操作序列
• 你做的纠正——你引导 agent 调整方向的地方（如"用库 X 而不是 Y"、“检查边界情况 Z”）
• 输入/输出格式——数据进出时的样子
• 你提供的上下文——agent 本身不知道的项目特定事实、约定或约束

(2) 从现有项目资料中综合

当你有大量现有知识时，可以将其输入 LLM 并要求它综合生成一个 Skill。关键是使用项目特定的材料，而不是通用参考。

好的素材来源包括：

• 内部文档、运维手册和风格指南
• API 规范、Schema 和配置文件
• 代码审查评论和 Issue 跟踪器（捕获反复出现的关注点）
• 版本控制历史，特别是补丁和修复（通过实际变更揭示模式）
• 真实的故障案例及其解决方案

Skill 的初稿通常需要改进。用真实任务运行 Skill，然后将结果——所有结果，不仅仅是失败的——反馈到创建过程中。问自己：什么触发了误报？什么被遗漏了？什么可以删减？

即使只做一轮"执行-修改"循环，也能明显提高质量。复杂领域通常需要多轮迭代。

提示：阅读 agent 的执行轨迹，而不仅仅是最终输出。如果 agent 在无效步骤上浪费时间，常见原因包括：指令太模糊（agent 尝试多种方法才找到有效的）、指令不适用于当前任务（agent 仍然遵循了）、或者提供了太多选项而没有明确的默认值。

Skill 激活后，其完整的 SKILL.md 内容会加载到 agent 的上下文窗口中，与对话历史、系统上下文和其他活跃的 Skills 共存。Skill 中的每个 token 都在与窗口中的其他内容竞争 agent 的注意力。

(1) 添加 agent 缺少的，省略它已知的

专注于 agent 没有你的 Skill 就不会知道的内容：项目特定的约定、领域特定的流程、不明显的边界情况，以及要使用的特定工具或 API。你不需要解释什么是 PDF、HTTP 如何工作或数据库迁移是什么。

 
         提取 PDF 文本  PDF（便携式文档格式）文件是一种常见的文件格式...   
         提取 PDF 文本  使用 pdfplumber 进行文本提取。对于扫描文档，回退到 pdf2image + pytesseract。 

对每段内容问自己：“没有这条指令，agent 会做错吗？“如果答案是否，就删掉它。

(2) 设计内聚的单元

决定一个 Skill 应该覆盖什么，就像决定一个函数应该做什么：你希望它封装一个内聚的工作单元，能与其他 Skills 良好组合。范围太窄会迫使多个 Skills 为单个任务加载；范围太宽则难以精确激活。

(3) 追求适度的详细程度

过于全面的 Skills 可能弊大于利——agent 难以提取相关内容，可能被不适用于当前任务的指令引入歧途。简洁的、逐步的指导加上一个可用的示例，通常优于详尽的文档。

以下是构建 Skill 内容的可复用技巧。不是每个 Skill 都需要所有这些——使用适合你任务的那些。

(1) Gotchas（陷阱）章节

许多 Skills 中最有价值的内容是一个陷阱列表——违反合理假设的环境特定事实：

 Gotchas  - `users` 表使用软删除。查询必须包含 `WHERE deleted_at IS NULL`，否则结果会包含已停用的账户。 - 用户 ID 在数据库中是 `user_id`，在认证服务中是 `uid`，在计费 API 中是 `accountId`。三者指向同一个值。 - `/health` 端点只要 Web 服务器在运行就返回 200，即使数据库连接断开。使用 `/ready` 检查完整的服务健康状态。 

提示：当 agent 犯了一个你必须纠正的错误时，将纠正内容添加到 Gotchas 章节。这是迭代改进 Skill 最直接的方式之一。

(2) 输出格式模板

当你需要 agent 以特定格式产出时，提供一个模板。这比用文字描述格式更可靠，因为 agent 擅长对具体结构进行模式匹配：

 报告结构  使用此模板，根据具体分析调整各章节：  # [分析标题]   执行摘要 [关键发现的一段概述]   主要发现 - 发现 1 及支持数据 - 发现 2 及支持数据   建议 1. 具体可操作的建议 2. 具体可操作的建议 

(3) 多步骤工作流的检查清单

显式的检查清单帮助 agent 跟踪进度并避免跳过步骤，特别是当步骤有依赖关系或验证关卡时：

 表单处理工作流  进度： - [ ] 步骤 1：分析表单（运行 `scripts/analyze_form.py`） - [ ] 步骤 2：创建字段映射（编辑 `fields.json`） - [ ] 步骤 3：验证映射（运行 `scripts/validate_fields.py`） - [ ] 步骤 4：填充表单（运行 `scripts/fill_form.py`） - [ ] 步骤 5：验证输出（运行 `scripts/verify_output.py`） 

(4) 验证循环

指示 agent 在继续之前验证自己的工作。模式是：做工作 → 运行验证器 → 修复问题 → 重复直到验证通过：

 编辑工作流  1. 进行编辑 2. 运行验证：`python scripts/validate.py output/` 3. 如果验证失败：  - 查看错误信息  - 修复问题  - 再次运行验证 4. 只有验证通过后才继续 

(5) 提供默认值，而非菜单

当多种工具或方法都可行时，选择一个默认值并简要提及替代方案，而不是将它们作为同等选项呈现：

 
        你可以使用 pypdf、pdfplumber、PyMuPDF 或 pdf2image...   
        使用 pdfplumber 进行文本提取。 对于需要 OCR 的扫描 PDF，改用 pdf2image + pytesseract。 

description 字段承担了触发的全部责任。如果描述没有传达 Skill 何时有用，agent 就不知道该使用它。

(1) 编写有效描述的原则

• 使用祈使句——将描述框架为对 agent 的指令：“当…时使用此 Skill”，而不是"此 Skill 做…”
• 聚焦用户意图，而非实现——描述用户试图实现什么，而不是 Skill 的内部机制
• 宁可主动一些——显式列出 Skill 适用的场景，包括用户没有直接提到领域的情况：“即使他们没有明确提到 ‘CSV’ 或 ‘分析’”
• 保持简洁——几句话到一小段通常就够了。规范强制限制最多 1024 个字符

优化前后对比：

# 优化前 description: Process CSV files.  # 优化后 description: >  Analyze CSV and tabular data files — compute summary statistics,  add derived columns, generate charts, and clean messy data. Use this  skill when the user has a CSV, TSV, or Excel file and wants to  explore, transform, or visualize the data, even if they don't  explicitly mention "CSV" or "analysis." 

(2) 设计触发评估查询

要系统地测试触发效果，你需要一组评估查询——标注了是否应该触发你的 Skill 的真实用户提示。

[  {  "query": "我有一个 ~/data/q4_results.xlsx 的电子表格，C 列是收入，D 列是支出——能加一个利润率列并高亮低于 10% 的吗？",  "should_trigger": true  },  {  "query": "把这个 JSON 文件转成 YAML 最快的方法是什么",  "should_trigger": false  } ] 

目标约 20 个查询：8-10 个应该触发的，8-10 个不应该触发的。

应该触发的查询要在以下维度上变化：

• 措辞：正式的、随意的、有拼写错误的
• 明确程度：有的直接提到领域（“分析这个 CSV”），有的间接描述需求（“老板要一个数据图表”）
• 详细程度：混合简短和详细的提示
• 复杂度：单步任务和多步工作流

不应该触发的查询最有价值的是"近似命中”——与你的 Skill 共享关键词但实际需要不同东西的查询。

(3) 优化循环

1. 在训练集和验证集上评估当前描述
2. 识别训练集中的失败：哪些应该触发的没触发？哪些不应该触发的触发了？
3. 修改描述——聚焦于泛化，避免为特定失败查询添加关键词（那是过拟合）
4. 重复步骤 1-3，直到所有训练集查询通过或不再有明显改善
5. 根据验证集通过率选择**迭代版本

通常 5 轮迭代就足够了。

提示：skill-creator Skill 可以端到端自动化这个循环：拆分评估集、并行评估触发率、使用 LLM 提出描述改进建议，并生成实时 HTML 报告。

你写了一个 Skill，试了一个提示，看起来有效。但它是否可靠——在不同提示下、在边界情况中、比没有 Skill 时更好？运行结构化评估（evals）可以回答这些问题，并为你提供系统改进 Skill 的反馈循环。

(1) 设计测试用例

一个测试用例有三个部分：

• Prompt：真实的用户消息
• Expected output：成功的人类可读描述
• Input files（可选）：Skill 需要处理的文件

将测试用例存储在 Skill 目录的 evals/evals.json 中：

{  "skill_name": "csv-analyzer",  "evals": [  {  "id": 1,  "prompt": "我有一个月度销售数据 CSV 在 data/sales_2025.csv。能找出收入最高的 3 个月并做一个柱状图吗？",  "expected_output": "一个柱状图图片，显示收入最高的 3 个月，带有标注的坐标轴和数值。",  "files": ["evals/files/sales_2025.csv"]  }  ] } 

编写好测试提示的建议：

• 从 2-3 个测试用例开始，不要在看到第一轮结果之前过度投入
• 变化提示的措辞、详细程度和正式程度
• 覆盖边界情况——至少包含一个测试边界条件的提示
• 使用真实上下文——文件路径、列名、个人背景

(2) 运行评估

核心模式是对每个测试用例运行两次：一次有 Skill，一次没有 Skill（或使用之前的版本）。这给你一个基线来对比。

每次运行应从干净的上下文开始——没有之前运行或 Skill 开发过程的残留状态。

(3) 编写断言（assert）

断言是关于输出应该包含或实现什么的可验证声明。在看到第一轮输出后再添加它们：

好的断言：

• “输出文件是有效的 JSON”——可编程验证
• “柱状图有标注的坐标轴”——具体且可观察
• “报告包含至少 3 条建议”——可计数

弱的断言：

• “输出很好”——太模糊
• “输出使用了确切的短语 ‘Total Revenue: $X’"——太脆弱

{  "assertions": [  "输出包含一个柱状图图片文件",  "图表显示恰好 3 个月",  "两个坐标轴都有标注",  "图表标题或说明提到了收入"  ] } 

(4) 评分和聚合结果

评分意味着对每个断言评估实际输出并记录 PASS 或 FAIL，附带具体证据。完成后计算汇总统计：

{  "run_summary": {  "with_skill": {  "pass_rate": { "mean": 0.83 },  "tokens": { "mean": 3800 }  },  "without_skill": {  "pass_rate": { "mean": 0.33 },  "tokens": { "mean": 2100 }  },  "delta": {  "pass_rate": 0.50,  "tokens": 1700  }  } } 

delta 告诉你 Skill 的成本（更多时间、更多 token）和收益（更高的通过率）。一个增加 13 秒但将通过率提高 50 个百分点的 Skill 可能是值得的。一个将 token 使用量翻倍但只提高 2 个百分点的 Skill 可能不值得。

(5) 迭代改进循环

评分和审查后，你有三个信号来源：

• 失败的断言指向具体的差距
• 人工反馈指向更广泛的质量问题
• 执行轨迹揭示为什么出了问题

迭代循环：

1. 将评估信号和当前 SKILL.md 交给 LLM，要求它提出改进建议
2. 审查并应用更改
3. 在新的 iteration- / 目录中重新运行所有测试用例
4. 评分并聚合新结果
5. 人工审查。重复。

当你对结果满意、反馈持续为空、或迭代之间不再有明显改善时停止。

Skills 可以指示 agent 运行 shell 命令并在 scripts/ 目录中打包可复用脚本。

(1) 一次性命令

当现有包已经能满足需求时，可以在 SKILL.md 指令中直接引用，无需 scripts/ 目录。许多生态系统提供在运行时自动解析依赖的工具：

# Python（使用 uvx） uvx ruff@0.8.0 check .  # Node.js（使用 npx） npx eslint@9.0.0 . 

建议：

• 固定版本（如 npx eslint@9.0.0），确保命令行为一致
• 在 SKILL.md 中声明前置条件（如"需要 Node.js 18+"），而不是假设 agent 的环境已具备

(2) 自包含脚本

当你需要可复用逻辑时，在 scripts/ 中打包一个声明自身依赖的脚本。以 Python 的 PEP 723 内联依赖声明为例：

# /// script # dependencies = [ # "beautifulsoup4", # ] # ///  from bs4 import BeautifulSoup  html = ' 
Welcome
 
This is a test.
 ' print(BeautifulSoup(html, "html.parser").select_one("p.info").get_text()) 

使用 uv run scripts/extract.py 运行——uv run 会创建隔离环境、安装声明的依赖并运行脚本。

(3) 为 Agent 使用设计脚本

当 agent 运行你的脚本时，它读取 stdout 和 stderr 来决定下一步做什么。以下设计原则让脚本更易于 agent 使用：

• 避免交互式提示——agent 在非交互式 shell 中运行，无法响应 TTY 提示。通过命令行参数、环境变量或 stdin 接受所有输入
• 提供 --help 文档——这是 agent 了解脚本接口的主要方式
• 编写有用的错误信息——说明什么出了错、期望什么、以及该尝试什么
• 使用结构化输出——优先使用 JSON、CSV 等格式，而非自由文本
• 支持幂等性——agent 可能重试命令，“如果不存在则创建"比"创建并在重复时失败"更安全
• 支持 dry-run——对于破坏性操作，--dry-run 标志让 agent 预览将要发生什么

• 从真实专业知识出发创建 Skill，而不是让 LLM 凭空生成泛泛的指令
• 通过真实执行迭代改进——即使一轮"执行-修改"循环也能明显提高质量
• 高效使用上下文：添加 agent 缺少的，省略它已知的，保持 SKILL.md 在 500 行以内
• 使用 Gotchas 章节、输出模板、检查清单和验证循环等模式构建有效指令
• 系统地优化描述：设计评估查询集，使用训练/验证拆分避免过拟合，通常 5 轮迭代足够
• 通过结构化评估（evals）测试 Skill 输出质量：设计测试用例、编写断言、对比有/无 Skill 的结果
• 脚本应避免交互式提示、提供 --help、使用结构化输出、支持幂等性

你的 Skill 存在，但 Kiro 在你期望时没有使用它。原因几乎总是描述。

Kiro 使用语义匹配，因此你的请求需要与描述的含义有重叠。如果重叠不够，就不会匹配。以下是解决方法：

• 检查你的描述是否与你实际的表述方式一致
• 添加用户实际会说的触发短语
• 用不同的表述进行测试，如"帮我分析性能”、“为什么这么慢？"、“让它更快”
• 如果任何变体未能触发，将这些关键词添加到你的描述中

如果你的 Skill 没有出现在可用列表中，检查以下结构要求：

• SKILL.md 文件必须在一个命名目录内，而不是在 skills 根目录下
• 文件名必须严格为 SKILL.md——“SKILL” 全大写，“md” 小写
• frontmatter 的 YAML 语法必须正确
• name 字段必须与文件夹名一致

验证方式：

• 在 Kiro IDE 中，查看 Agent Steering & Skills 面板确认 Skill 是否被列出
• 在 Kiro CLI 中，使用 /context show 命令查看已加载的 Skills

如果 Kiro 使用了错误的 Skill 或在 Skills 之间混淆，你的描述可能太相似了。让它们更加明确。尽可能具体不仅帮助 Kiro 决定何时使用你的 Skill——还能防止与其他听起来相似的 Skills 冲突。

如果你的全局 Skill 被忽略了，可能是工作区中有一个同名的 Skill 覆盖了它。

你的选择：

• 将你的 Skill 重命名为更独特的名称
• 检查工作区 .kiro/skills/ 中是否有同名 Skill

如果你使用自定义 agent 但看不到 Skills，检查 agent 配置文件中是否包含 skill:// URI：

{  “resources”: [  “skill://.kiro/skills//SKILL.md”,  “skill://~/.kiro/skills//SKILL.md”  ] } 

注意：skill:// 路径需要从 .kiro/ 开始，相对路径可能无法正确解析。

Skill 加载了但在执行过程中失败。几个常见原因：

• 缺少依赖：如果你的 Skill 使用外部包，它们必须已安装。在 Skill 描述中添加依赖信息，让 Kiro 知道需要什么。
• 权限问题：脚本需要执行权限。对你的 Skill 引用的任何脚本运行 chmod +x。
• 路径分隔符：在所有地方使用正斜杠，即使在 Windows 上也是如此。
• 相对路径引用：全局 Skills 中的相对文件引用可能无法正确解析（已知问题）。

• 没有触发？ 改进你的描述并添加触发短语。
• 没有加载？ 检查路径、文件名和 YAML 语法。
• 使用了错误的 Skill？ 让描述之间更加不同。
• 被覆盖了？ 检查工作区是否有同名 Skill。
• 自定义 Agent 找不到？ 在 resources 中添加 skill:// URI。
• 运行时失败？ 检查依赖、权限和路径。

• 如果 Skill 没有触发，原因几乎总是描述——添加与你实际表述方式匹配的触发短语
• 如果 Skill 没有加载，检查 SKILL.md 是否在一个命名目录内（而不是在 skills 根目录下），且文件名严格为 SKILL.md
• 如果使用了错误的 Skill，你的描述太相似了——让它们更加不同
• 自定义 agents 需要在 resources 字段中显式配置 skill:// URI
• 对于运行时错误，检查依赖、文件权限（chmod +x）和路径分隔符（在所有地方使用正斜杠）

当 Skills 不工作时，问题通常属于以下几类之一：Skill 没有触发、没有加载、存在冲突或运行时失败。好消息是大多数修复都相当简单。

• Kiro Skills 官方文档（IDE）
• Kiro Skills 官方文档（CLI）
• Kiro Steering 官方文档
• Kiro Custom Agents 官方文档
• Agent Skills 开放标准规范
• Agent Skills - Skill 创建快速入门
• Agent Skills - **实践
• Agent Skills - 优化描述
• Agent Skills - 评估 Skill 质量
• Agent Skills - 在 Skill 中使用脚本
• Anthropic 官方示例 Skills
• Agent Skills GitHub Issues（Kiro）

本文基于以下 Anthropic 官方视频教程适配编写：

• Part 1 - What are skills?
• Part 2 - Creating your first skill
• Part 3 - Configuration and multi-file skills
• Part 4 - Skills vs. other Claude Code features
• Part 5 - Sharing skills
• Part 6 - Troubleshooting skills

 
  
    
    
 
     
最后修改于 2026-04-22