如何写好 Skill：一份终极实战经验手册

📌 一句话摘要

本文系统性地总结了编写 AI 编程助手 Skill（技能包）的完整方法论，从基础概念、结构设计到高级技巧、安全规范与工程化评估，是一份面向开发者的实战手册。

📝 详细摘要

文章由腾讯技术工程团队撰写，旨在帮助开发者系统性地掌握为 AI 编程助手（如 Claude Code、CodeBuddy）编写 Skill 的方法。全文从 Skill 的基本概念（是什么、为什么、怎么运作）入手，通过一个 5 分钟快速上手的例子让读者建立直观认识。核心部分详细阐述了编写高质量 Skill 的关键技巧，包括精准的 Description 编写、清晰的指令与上下文、Before/After 对比示例、Few-Shot 示例的重要性、以及如何利用表格和流程图提升指令的准确性。针对复杂场景，文章提出了模块化拆分策略，并给出了主 Skill 编排子 Skill 的实践方法。进阶部分涵盖了脚本化复杂检查、多方案适配、易错点标注和 FAQ 的编写。文章还深入对比了 MCP 与 HTTP 两种外部服务集成方式的选型与使用场景，并专门用一章强调安全意识，包括避免硬编码、危险操作确认、数据库备份和防范 Prompt 注入。最后，介绍了 Anthropic 官方的 Skill Creator 工具及其工程化评估能力。全文以 Go 语言为主要示例，但原则适用于所有编程语言。

💡 主要观点

- Skill 的本质是结构化的 Prompt Engineering，用于将领域知识转化为 AI 可执行的指令集。 Skill 通过标准文件格式（SKILL.md）封装指令、上下文和工具，解决知识分散、重复劳动和新人上手慢等痛点，其加载机制分为元数据、主体和按需引用三层，需关注 Token 成本。

编写高质量 Skill 的核心在于精准的 Description、清晰的指令和丰富的示例。 Description 决定了 AI 的触发时机，需具体且可测试；指令应使用祈使句并解释原因；Before/After 对比和 Few-Shot 示例能显著提升 AI 输出的稳定性和准确性。

复杂 Skill 应遵循模块化设计，拆分为单一职责的子 Skill 并编排执行流程。 当 SKILL.md 超过 500 行或包含多个独立工作流时，应拆分。主 Skill 负责编排，子 Skill 可独立使用，需明确依赖关系和检查点。

集成外部服务时，优先使用 MCP 协议，简单场景可用 HTTP 脚本，两者可混合使用。 MCP 是专为 AI Agent 设计的标准化工具协议，支持上下文感知和跨平台复用；HTTP 适用于简单一次性调用。选择依据是复用性、安全管控需求和改造成本。

编写 Skill 必须将安全意识放在首位，防范密钥泄露、数据丢失和 Prompt 注入。 禁止硬编码敏感信息，危险操作需用户确认，数据库操作先备份，并严格区分指令与数据以防范 Prompt 注入。

💬 文章金句

- Skill 不是免费的——每加载一个 Skill 都会占用上下文窗口。

• Rule 是'底线'，Skill 是'技能'。
• 与其一堆'MUST'，不如讲清楚为什么。
• 核心原则：区分'指令'和'数据'。Skill 中的步骤是指令，从外部读取的内容是数据。数据永远不应该被当成指令来执行。

📊 文章信息

AI 初评：90

来源：腾讯技术工程

作者：腾讯技术工程

分类：软件编程

语言：中文

阅读时间：87 分钟

字数：21651

标签： AI 编程, Prompt Engineering, 开发者工具, 工程实践, AI Agent

阅读完整文章