ForgeCode Skill 创作实战指南：从 SKILL.md 结构到渐进式上下文披露的完整方法论

人工智能AI Agent代码智能体AI 应用CLI开发工具【免费下载链接】forgecodeAI enabled pair programmer for Claude, GPT, O Series, Grok, Deepseek, Gemini and 300 models项目地址https://gitcode.com/gh_mirrors/forge39/forgecode点击查看免费下载本篇指南围绕 ForgeCode 仓库内置的 create-skill 技能文档展开系统讲解如何为 AI 编程助手设计、创建与迭代一个高效技能Skill你将掌握技能的核心价值定位、SKILL.md 的目录解剖结构、scripts/references/assets 三类捆绑资源的使用边界、渐进式披露Progressive Disclosure的上下文管理原则以及从需求理解到初始化、实现、迭代的完整五步创建流程同时结合 技能仓库实现 的源码理清技能加载、优先级覆盖与触发机制让创建的技能真正可被 ForgeCode 识别、加载并高效复用。一、理解 Skills模块化的能力扩展包Skills 是模块化、自包含的软件包通过提供专门的知识、工作流和工具来扩展 AI Agent 的能力。可以把它们理解为特定领域或任务的上岗引导手册——它们将通用型 Agent 转变为具备程序化知识的专家型 Agent而这些程序化知识是任何模型都无法凭空完整具备的。Skills 能提供什么专业化工作流Specialized workflows面向特定领域的多步骤流程工具集成Tool integrations针对特定文件格式或 API 的使用说明领域专长Domain expertise公司特有知识、数据模式、业务逻辑捆绑资源Bundled resources面向复杂与重复任务的脚本、参考资料和资产。在 ForgeCode 中这一理念的落地可以直接观察仓库内置了create-skill、execute-plan、github-pr-description三个技能分别承载创建技能、执行结构化计划与生成 PR 描述的领域流程。例如 execute-plan 技能 通过任务状态标记[ ]PENDING、[~]IN_PROGRESS、[x]DONE、[!]FAILED驱动一个可跟踪的执行循环github-pr-description 技能 则封装了校验前置条件 → 分析变更 → 生成描述的完整工作流。这三个技能共同演示了把重复流程沉淀为可复用知识包这一核心思想。二、核心设计原则简洁为王Concise is Key上下文窗口context window是一种公共资源。技能与系统提示词、对话历史、其他技能的元数据以及用户的真实请求共享同一个上下文窗口。默认假设你Agent已经具备相当强的能力。只添加你尚不具备的上下文。对每一条信息都应发起追问我真的需要这段解释吗这段文字值得它消耗的 token 成本吗优先使用简洁的示例而不是冗长的解释。从 ForgeCode 的实现看这一原则贯穿始终技能加载后其描述description与正文command会进入系统上下文而捆绑资源只有在按需获取时才进入——详见后文渐进式披露与技能加载机制小节。三、设定适当的自由度Degrees of Freedom自由度的设定要与任务的脆弱性和可变性相匹配高自由度基于文本的指令当多种做法都可行、决策依赖具体上下文、或由启发式规则引导时使用。就像一片开阔的原野允许多种路线。中自由度带参数化的伪代码或脚本当存在一个首选模式、允许一定变体、或配置会影响行为时使用。低自由度具体的脚本、少量参数当操作脆弱且容易出错、一致性至关重要、或必须严格遵循特定顺序时使用。就像一座悬崖边的窄桥需要明确的护栏。核心隐喻把自己想象成在探索一条路径——带悬崖的窄桥需要具体的护栏低自由度而开阔的原野允许许多路线高自由度。四、技能的解剖结构Anatomy of a Skill每个技能由一个必需的 SKILL.md 文件与若干可选的捆绑资源组成skill-name/ ├── SKILL.md (required) │ ├── YAML frontmatter metadata (required) │ │ ├── name: (required) │ │ └── description: (required) │ └── Markdown instructions (required) └── Bundled Resources (optional) ├── scripts/ - Executable code (Python/Bash/etc.) ├── references/ - Documentation intended to be loaded into context as needed └── assets/ - Files used in output (templates, icons, fonts, etc.)SKILL.md必需每个 SKILL.md 由两部分组成FrontmatterYAML包含name和description两个字段。这两个字段是判断技能何时被使用的唯一依据因此清晰且全面地描述技能是什么、何时该用至关重要。正文Markdown使用技能的说明与指导。只有在技能触发之后如果触发的话才会被加载。捆绑资源可选Scriptsscripts/——需要确定性可靠或反复重写的可执行代码何时包含同一段代码被反复重写、或需要确定性可靠时示例PDF 旋转任务的scripts/rotate_pdf.sh收益节省 token、结果确定、可以在不载入上下文的情况下直接执行注意脚本仍可能需要被 Agent 读取以便打补丁或做环境相关的调整。Referencesreferences/——按需载入上下文的文档与参考资料何时包含需要边工作边参考的文档示例财务模式的references/finance.md、公司 NDA 模板references/mnda.md、公司政策references/policies.md、API 规范references/api_docs.md适用场景数据库模式、API 文档、领域知识、公司政策、详细工作流指南收益保持 SKILL.md 精简仅在判断需要时才加载最佳实践如果文件很大超过 1 万词应在 SKILL.md 中提供 grep 搜索模式避免重复信息应只存在于 SKILL.md 或 references 文件之一而非两者。除非是技能真正核心的内容否则优先把详细信息放入 references 文件——这既能让 SKILL.md 保持精简又让信息在不占用上下文窗口的情况下可被发现。SKILL.md 中只保留必要的程序性指令和工作流指引详细的参考资料、模式和示例移入 references 文件。Assetsassets/——用于输出而非载入上下文的文件何时包含技能需要将在最终输出中使用的文件时示例品牌资产的assets/logo.png、PPT 模板assets/slides.pptx、HTML/React 脚手架assets/frontend-template/、字体assets/font.ttf适用场景会被复制或修改的模板、图片、图标、样板代码、字体、示例文档收益将输出资源与文档分离可以在不载入上下文的情况下使用这些文件。技能中不应包含什么一个技能只应包含直接支撑其功能的核心文件不要创建多余的文档或辅助文件包括README.mdINSTALLATION_GUIDE.mdQUICK_REFERENCE.mdCHANGELOG.md等等技能只需包含 AI Agent 完成手头工作所需的信息。它不应包含创建过程的辅助上下文、搭建与测试流程、面向用户的使用文档等——创建额外文档只会增加杂乱与困惑。源码侧的数据模型印证从仓库数据结构看技能被建模为一个包含name名称、path文件路径、command从 Markdown 文件加载的正文/提示词、description描述与resources技能目录下的资源文件列表的Skill结构体见 Skill 数据模型。加载时通过 extract_skill 解析函数 使用gray_matter解析 YAML frontmatter当name与description同时存在时生成完整技能若 frontmatter 缺失或字段不完整则会回退为以目录名作为技能名、描述为空的技能或在元数据不完整时直接返回 None。仓库中的测试 test_extract_skill_with_valid_metadata 与 test_extract_skill_with_incomplete_metadata 精确验证了这一行为——这再次说明name 与 description 是两个不可或缺的字段。五、渐进式披露设计原则Progressive Disclosure技能使用三级加载系统来高效管理上下文元数据name description——始终在上下文中约 100 词SKILL.md 正文——技能触发时加载5000 词捆绑资源——按需加载脚本可以直接执行而不占用上下文窗口因此近乎无限。渐进式披露模式保持 SKILL.md 正文精简控制在 500 行以内以减少上下文膨胀。接近此上限时就拆分内容到独立文件。拆分时必须从 SKILL.md 中明确引用这些文件并清楚说明何时读取它们确保技能使用者知道这些文件存在以及何时使用。关键原则当一个技能支持多种变体、框架或选项时SKILL.md 中只保留核心工作流与选择指引将变体专属细节模式、示例、配置移入独立的 reference 文件。模式 1高层指南 引用文件# PDF Processing ## Quick start Extract text with pdfplumber: [code example] ## Advanced features - **Form filling**: See FORMS.md for complete guide - **API reference**: See REFERENCE.md for all methods - **Examples**: See EXAMPLES.md for common patterns只有需要时才加载 FORMS.md、REFERENCE.md 或 EXAMPLES.md。模式 2按领域组织对于包含多个领域的技能按领域组织内容以避免加载无关上下文bigquery-skill/ ├── SKILL.md (overview and navigation) └── reference/ ├── finance.md (revenue, billing metrics) ├── sales.md (opportunities, pipeline) ├── product.md (API usage, features) └── marketing.md (campaigns, attribution)当用户询问销售指标时只读取 sales.md。类似地对于支持多个框架或变体的技能按变体组织cloud-deploy/ ├── SKILL.md (workflow provider selection) └── references/ ├── aws.md (AWS deployment patterns) ├── gcp.md (GCP deployment patterns) └── azure.md (Azure deployment patterns)当用户选择 AWS 时只读取 aws.md。模式 3条件式细节展示基础内容链接到高级内容# DOCX Processing ## Creating documents Use docx-js for new documents. See DOCX-JS.md. ## Editing documents For simple edits, modify the XML directly. **For tracked changes**: See REDLINING.md **For OOXML details**: See OOXML.md仅当用户需要这些功能时才读取 REDLINING.md 或 OOXML.md。重要指导原则避免深层嵌套的引用——引用层级应保持从 SKILL.md 出发的一层深度所有 reference 文件都应直接从 SKILL.md 链接组织较长的引用文件——超过 100 行的文件应在顶部加入目录table of contents以便预览时快速了解全貌。触发与按需加载的源码佐证ForgeCode 将获取技能实现为一个独立工具SkillFetch。从 工具定义 看它接收技能名称并返回技能详情工具服务实现 中ForgeSkillFetch通过fetch_skill(name)精确命中技能、list_skills()列出全部可用技能并用OnceCell做会话级缓存避免重复加载。工具描述明确要求Only invoke skills that are listed in the available skills section. Do not invoke a skill that is already active.即只能触发可用技能列表中声明的技能且不得重复触发已激活技能——这与渐进式披露中元数据常驻上下文、正文触发后才加载的设计完全吻合。技能正文只在触发后进入上下文这正是 SKILL.md 必须保持精简的底层原因。六、Skill 创建流程技能创建包含以下步骤用具体示例理解技能规划可复用的技能内容scripts、references、assets初始化技能编辑技能实现资源并编写 SKILL.md基于真实使用情况迭代。按顺序执行这些步骤仅在有明确理由时才跳过。Step 1用具体示例理解技能Understanding the Skill with Concrete Examples仅当技能的用法模式已经非常清晰时才跳过此步。即使是在既有技能上工作这一步也依然有价值。要创建有效的技能必须清晰理解技能将被如何使用这种理解可来自用户的直接示例或来自经用户反馈验证的生成示例。例如构建一个图像编辑技能edit-image时相关问题包括这个编辑图像技能应支持什么功能编辑、旋转还有其他吗你能给出一些这个技能会被如何使用示例吗我可以想象用户会要求诸如去除这张图片的红眼或旋转这张图片。你还想象得到其他使用方式吗用户会说什么话来触发这个技能为避免给用户造成负担避免在单条消息中提出过多问题。从最重要的问题开始根据需要再跟进补充。当对技能应支持的功能有清晰认识时本步骤即可结束。Step 2规划可复用的技能内容Planning the Reusable Skill Contents要将具体示例转化为有效技能需要逐一分析每个示例考虑如何从零开始执行该示例识别在反复执行这些工作流时哪些脚本、引用和资产会有所帮助。示例一构建处理帮我旋转这个 PDF这类查询的edit-pdf技能分析显示旋转 PDF 需要每次重写同样的代码一个scripts/rotate_pdf.sh脚本很适合放进技能中。示例二设计处理帮我构建一个 todo 应用或构建一个追踪步数的仪表盘这类查询的build-frontend-webapp技能分析显示编写前端 Web 应用每次都需要同样的 HTML/React 样板代码一个包含样板 HTML/React 项目文件的assets/hello-world/模板很适合放进技能中。示例三构建处理今天有多少用户登录了这类查询的query-bigquery技能分析显示查询 BigQuery 每次都需要重新发现表结构与关系一个记录表结构的references/schema.md文件很适合放进技能中。通过分析每个具体示例建立应包含的可复用资源清单scripts、references 和 assets从而确定技能的内容构成。Step 3初始化技能Initializing the Skill此时就到了真正创建技能的时刻。仅当技能已经存在、需要迭代或打包时才跳过此步——这种情况下直接进入下一步。技能命名规范始终使用动词式名称以清晰传达技能执行的动作✅ 好execute-plan、create-report、analyze-logs、deploy-app❌ 差plan-executor、report-creator、log-analyzer、app-deployer动词优先的命名让技能的作用一目了然并与技能指令中通篇使用的祈使/不定式形式保持一致。技能位置默认除非用户明确要求全局技能否则创建项目本地技能。从零创建新技能时在项目本地技能目录中创建项目本地默认{{local_skills_path}}/skill-name/——技能仅作用于当前项目不影响其他项目。对大多数技能而言这是安全默认值全局仅在明确要求时{{global_skills_path}}/skill-name/——技能对所有项目可用。仅当用户明确要求全局技能、或技能确实跨项目可复用时才使用此位置。结构应包含带 YAML frontmattername、description和 Markdown 正文的SKILL.md存放可执行代码的scripts/目录如process.sh、validate.sh存放按需加载文档的references/目录存放输出用文件的assets/目录。初始化示例默认项目本地mkdir -p {{local_skills_path}}/edit-pdf/{scripts,references,assets} cat {{local_skills_path}}/edit-pdf/SKILL.md EOF --- name: edit-pdf description: TODO - Describe what this skill does and when to use it --- # Edit PDF TODO - Add skill instructions here EOF cat {{local_skills_path}}/edit-pdf/scripts/rotate.sh EOF #!/bin/bash # Rotate PDF using pdftk pdftk $1 cat 1-endright output $2 EOF chmod x {{local_skills_path}}/edit-pdf/scripts/rotate.sh如果用户明确要求全局技能则使用mkdir -p {{global_skills_path}}/edit-pdf/{scripts,references,assets} cat {{global_skills_path}}/edit-pdf/SKILL.md EOF --- name: edit-pdf description: TODO - Describe what this skill does and when to use it --- # Edit PDF TODO - Add skill instructions here EOF cat {{global_skills_path}}/edit-pdf/scripts/rotate.sh EOF #!/bin/bash # Rotate PDF using pdftk pdftk $1 cat 1-endright output $2 EOF chmod x {{global_skills_path}}/edit-pdf/scripts/rotate.sh初始化完成后按需定制生成的各个文件。模板变量如何被解析上述命令中的{{local_skills_path}}、{{global_skills_path}}以及{{agents_skills_path}}并非占位符摆设——ForgeCode 在加载技能时会对它们做真实路径替换。从 render_skill 渲染函数 可见技能正文中的这些模板变量会被替换为运行环境解析出的实际目录路径{{global_skills_path}}→ 全局技能目录见 环境路径解析{{agents_skills_path}}→ Agent 技能目录~/.agents/skills见 env.rs{{local_skills_path}}→ 项目本地技能目录即当前工作目录下的.forge/skills见 env.rs。因此文档中的初始化命令可以原样照搬到 ForgeCode 环境执行实际路径会在技能加载时被自动解析。Step 4编辑技能Edit the Skill编辑新建或既有的技能时请记住这个技能是为另一个 AI Agent 实例使用的。要包含有价值且非显而易见的信息——思考哪些程序性知识、领域细节或可复用资产能帮助另一个 Agent 实例更高效地执行这些任务。学习经过验证的设计模式根据技能需求参考以下指南多步骤流程参考 workflows.md 中的顺序工作流与条件逻辑特定输出格式或质量标准参考 output-patterns.md 中的模板与示例模式。这些文件包含经过验证的有效技能设计最佳实践。注按文档约定此类设计模式指南应放在技能的 references 目录中与上文避免信息重复的准则一致。从可复用的技能内容开始实现时先从上面识别出的可复用资源开始scripts/、references/和assets/文件。注意此步骤可能需要用户输入——例如实现brand-guidelines技能时用户可能需要提供品牌资产或模板存入assets/或提供文档存入references/。新增脚本必须实际运行测试确保没有 bug 且输出符合预期。若存在许多相似脚本只需测试具有代表性的一部分样本在保证整体可信的同时平衡完成时间。技能不需要的示例文件和目录应删除。更新 SKILL.md写作规范始终使用祈使/不定式形式。Frontmatter编写包含name和description的 YAML frontmattername技能名称description这是技能的主要触发机制帮助判断何时使用技能。既要说明技能做什么也要包含具体的触发场景/上下文何时使用把所有何时使用的信息放在这里——不要放在正文中。正文只在触发后才加载因此正文里的When to Use This Skill章节没有意义一个docx技能的 description 示例Comprehensive document creation, editing, and analysis with support for tracked changes, comments, formatting preservation, and text extraction. Use when you need to work with professional documents (.docx files) for: (1) Creating new documents, (2) Modifying or editing content, (3) Working with tracked changes, (4) Adding comments, or any other document tasks不要在 YAML frontmatter 中写入任何其他字段。正文编写使用技能及其捆绑资源的指令。加载新技能技能完成后建议用户开启新会话来加载新创建的技能。技能在每个会话开始时加载因此新技能在当前会话中不可用。开启新会话可确保技能被正确注册并可用。Step 5迭代Iterate技能测试后用户可能会提出改进要求。这种情况常发生在刚使用过技能之后——此时对技能的表现有着最新鲜的上下文。迭代工作流在真实任务上使用技能留意困难或低效之处确定 SKILL.md 或捆绑资源应如何更新实施修改并再次测试。七、深入机制ForgeCode 的技能加载、优先级与覆盖了解技能的运行环境有助于写出符合平台预期的技能。从 ForgeSkillRepository 实现 的文档注释看ForgeCode 从四个来源加载技能内置技能Built-in内嵌在应用二进制中例如create-skill、execute-plan、github-pr-description三个技能即通过include_str!编译进应用路径形如forge://skills/name/SKILL.md见 load_builtin_skills全局自定义技能~/forge/skills/目录Agent 技能~/.agents/skills/目录项目本地技能当前工作目录下的.forge/skills/目录。优先级规则当不同来源存在同名技能时优先级为项目本地CWD Agent~/.agents/skills 全局自定义 内置这意味着项目本地技能可以覆盖 Agent 技能Agent 技能可以覆盖全局技能全局技能可以覆盖内置技能。resolve_skill_conflicts 通过保留同名技能的最后一次出现实现这一覆盖语义测试 test_resolve_skill_conflicts 对此做了明确验证同名skill1最终保留 CWD 版本。目录扫描与资源收集加载时仓库会遍历技能目录下每个子目录若存在SKILL.md则读取其内容并递归收集该目录内除 SKILL.md 之外的所有文件作为资源见 load_skills_from_dir。目录不存在时会被优雅跳过不影响其他来源的加载。测试 test_load_skills_from_dir 使用 skills_with_resources 测试夹具 验证了子目录中的嵌套资源如foo/bar/file_3.txt会被正确收集而SKILL.md永远不会被当作资源。这也解释了为什么技能目录结构约定如此重要——任何放入技能目录的文件都会被平台识别为可引用资源。为什么何时使用必须写进 description从加载链路看Agent 在一个会话开始时只会拿到每个技能的name与description元数据常驻上下文正文command必须通过 SkillFetch 工具按名获取。因此只有 description 写得足够清晰、覆盖了全部触发场景Agent 才能在面对相关任务时想起来调用该技能。这与 create-skill 文档反复强调的description 是主要触发机制互为印证。八、从内置技能学习一个可对照的范例仓库内置的三个技能本身就是渐进式披露与精炼写作的活教材create-skill本文所依据的文档frontmatter 的 description 明确写出应何时使用用户要创建新技能或更新既有技能时正文按原则 → 结构 → 流程组织全程祈使语气execute-plandescription 精确到触发格式plans/{current-date}-{task-name}-{version}.md正文用编号步骤定义执行循环并用表格化的状态标记规范输出格式——典型的低自由度设计github-pr-descriptiondescription 列举了完整触发词create a PR、generate a PR description、make a pull request 等正文以###分节给出可逐条执行的 shell 命令——中低自由度的实操型技能。对照这些范例检查自己的技能可以快速验证 description 是否覆盖全部触发场景、正文是否控制在 500 行以内、指令是否全部采用祈使形式。结语一个优秀的技能 精准的触发描述 精简的 SKILL.md 正文 按需加载的捆绑资源 动词式命名。把握上下文窗口是公共资源这一根本原则用渐进式披露让元数据常驻、正文按触发加载、资源按需取用再配合 ForgeCode 的四级加载与优先级覆盖机制你创建的技能就能在正确的时间以最小的 token 成本出现在正确的 Agent 面前真正把重复劳动沉淀为可复用的专家能力。赞分享人工智能AI Agent代码智能体AI 应用CLI开发工具【免费下载链接】forgecodeAI enabled pair programmer for Claude, GPT, O Series, Grok, Deepseek, Gemini and 300 models项目地址https://gitcode.com/gh_mirrors/forge39/forgecode点击查看免费下载相关推荐knowledge-catalog 的 Agent Skill 生成从语义模型到 SKILL.md 的渐进式披露实战解析knowledge catalog 的 Agent Skill 生成从语义模型到 SKILL.md 的渐进式披露实战解析 导读 本文以 Google Clou数据目录AI Agent人工智能知识管理示例工程Gemini CLI 技能工厂skill-creator 内置技能全解——从 SKILL.md 结构、渐进式披露到打包安装的完整工程实践Gemini CLI 技能工厂skill creator 内置技能全解——从 SKILL.md 结构、渐进式披露到打包安装的完整工程实践 Gemini CLI人工智能AI Agent交互助手CLIMCP ClientsAntigravity Skills 实战指南用 SKILL.md 为 AI Agent 构建渐进式披露的知识包Antigravity Skills 实战指南用 SKILL.md 为 AI Agent 构建渐进式披露的知识包 本指南基于当前仓库 .agent/ 目录下的前端开发工具上一篇猫抓浏览器插件一站式网页资源嗅探与下载解决方案下一篇MKS Robin Nano固件升级从零到精通解锁彩色触控界面的3D打印新体验创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考