人工智能AI Agent代码智能体Agent 编排CLIAI 应用【免费下载链接】gsd-2A powerful meta-prompting, context engineering and spec-driven development system that enables agents to work for long periods of time autonomously without losing track of the big picture项目地址https://gitcode.com/gh_mirrors/gs/gsd-2点击查看免费下载导读在 GSD-2GitHub 加速计划 / gs / gsd-2项目中技能Skill是以文件系统为基础的模块化能力单元通过SKILL.md的 YAML frontmatter 与纯 XML 结构向 Agent 提供领域专家知识。当技能文件逐渐增多、结构日渐复杂时如何系统化地评估一个技能的健康度、发现结构性问题并给出可执行的修复建议就成为一个高频工程需求。本文以create-skill技能中内置的 Audit a Skill 工作流 为骨架完整讲解从技能枚举、逐项核对审计清单、生成审计报告到按需修复的整套流程并结合仓库源码说明审计标准背后的实现依据帮助你掌握一套可复制的、可量化的技能质量审计方法论。一、审计工作流在技能体系中的定位1.1 create-skill 技能的整体结构create-skill是 GSD-2 仓库中内置的核心技能之一位于 src/resources/skills/create-skill/。它本身采用路由模式Router Pattern组织create-skill/ ├── SKILL.md # 路由 核心原则始终加载 ├── workflows/ # 分步操作流程FOLLOW ├── references/ # 领域知识READ └── templates/ # 输出结构模板COPY FILL其中workflows/目录下共包含 9 个流程文件audit-skill.md正是其中之一。SKILL.md 的路由表将审计、复查、检查Audit, review, check类用户意图直接映射到workflows/audit-skill.md将校验内容是否仍然准确Verify content is current映射到workflows/verify-skill.md——前者关注结构质量与最佳实践符合度后者关注内容时效性两者职责互补。1.2 为什么审计技能是必要环节从 create-skill 的 routing 部分 可以看到create-skill明确声明一个结构良好的技能需要满足有效的 YAML frontmatter、纯 XML 结构正文无 markdown 标题、核心原则内联在 SKILL.md、能根据用户意图直接路由到对应 workflow、SKILL.md 不超过 500 行、仅在真正必要时才提问澄清、且经过真实使用测试。技能是长周期自治系统如 GSD-2 所强调的让 Agent 长时间自主工作而不丢失大局观中锦上添花的知识资产任何一次随意的追加、一次错误的标记符嵌套、一个指向不存在文件的引用都会在后续真实任务中转化为上下文浪费或行为偏差。审计工作流提供的就是一套确定性的检查清单把这个技能写得好不好从主观感受变成可打分、可复盘的客观结论。二、审计前的准备理解技能的两级存放目录audit-skill.md明确指出审计时不要使用 AskUserQuestion因为技能可能有很多。在开始审计前首先要理解 GSD-2 中技能的两级存放约定这一点在 gsd-skill-ecosystem.md 中有详细说明目录作用域特点~/.agents/skills/用户级全局每个 GSD 会话都可用与工作目录无关.agents/skills/项目级本地仅当 GSD 在项目目录内运行时可用可提交到版本控制让团队成员共享同一套技能两个目录中的技能遵循相同的SKILL.md格式与路由模式约定。GSD 会在会话启动时自动枚举两个目录中的全部技能并将其名称与描述以available_skills形式注入系统提示词在 auto-mode 下skill-discovery.ts会在每个单元边界对技能目录做快照比对发现的新技能通过newly_discovered_skillsXML 块注入无需/reload即可被 LLM 感知。这一点也意味着审计时枚举出来的技能列表通常与系统提示词中available_skills的列表是一致的审计结果可以直接反哺会话上下文质量。三、Step 1枚举可用技能不依赖交互询问审计流程的第一步是全面枚举用户环境中的技能命令如下echo Global skills ls ~/.agents/skills/ 2/dev/null || echo (none) echo Project-local skills ls .agents/skills/ 2/dev/null || echo (none)说明2/dev/null || echo (none)用于在目录不存在时输出占位符而不是报错保证命令在任何环境下都能给出确定输出。随后将结果以两级分组的形式呈现给用户例如Available skills: Global (~/.agents/skills/): 1. create-skill 2. manage-stripe ... Project-local (.agents/skills/): 3. project-deploy ...然后询问Which skill would you like to audit?enter number or name。为什么禁用 AskUserQuestion审计面对的技能集合可能很大逐项交互式询问既不高效也不符合长周期自治原则。工作流特别强调DO NOT use AskUserQuestion。这背后其实是 create-skill 自身核心原则 中只问最小必要的澄清问题且一次只问一轮的体现——技能审计的目标是快速定位问题而不是让用户陷入反复的菜单选择。四、Step 2完整读取技能结构用户选定目标技能后进入完整阅读阶段# Read main file cat {skill-path}/SKILL.md # Check for workflows and references ls {skill-path}/ ls {skill-path}/workflows/ 2/dev/null ls {skill-path}/references/ 2/dev/null审计原则必须完整阅读。在 GSD-2 中技能一旦被调用SKILL.md是始终加载的见 recommended-structure.md 的关键洞察SKILL.md is always loaded. Use this guarantee.。因此审计绝不能只看目录列表而要对SKILL.md、每个 workflow 文件、每个 reference 文件逐一读取确认实际内容而非路径存在性。这也与审计 checklist 中Broken references文件被提及但不存在的检查项直接呼应。五、Step 3逐项执行审计清单Checklist5.1 YAML Frontmatter 检查--- name: skill-name # lowercase-with-hyphens且与目录名一致 description: ... # 说明它做什么以及何时使用第三人称 ---根据 skill-structure.md 中的name_field校验规则审计时应核对name最长 64 字符仅允许小写字母、数字、连字符name必须与目录名完全一致目录facebook-ads配name: facebook-ads-manager即为反例不得包含 XML 标签不得使用保留字anthropic、claude命名遵循动宾约定create-*、manage-*、setup-*、generate-*、build-*。description校验规则非空最长 1024 字符无 XML 标签必须是第三人称✅ Processes Excel files and generates reports❌ I can help you process Excel files必须同时说明做什么与何时使用例如 Use when working with PDF files or when the user mentions PDFs, forms, or document extraction。仓库中的 SKILL.md 本体 就是一个合规范本name: create-skill description: Expert guidance for creating, writing, building, and refining GSD skills. Use when working with SKILL.md files, authoring new skills, improving existing skills, or understanding skill structure and best practices.5.2 结构检查SKILL.md 小于 500 行这是渐进式披露Progressive Disclosure的硬性上限防止单体技能膨胀纯 XML 结构正文中不允许出现 markdown 标题#、##、###必须用语义化 XML 标签替代所有 XML 标签正确闭合必备标签objective或essential_principles至少其一外加success_criteria。关于 XML 标签体系的完整定义可参考 use-xml-tags.md必备标签为objective、quick_start、success_criteria或when_successful条件标签包括context、workflow/process、advanced_features、validation、examples、anti_patterns、security_checklist、testing、common_patterns、reference_guides等按技能复杂度递进选用。该参考文档还给出了 XML 优于 markdown 标题的理由token 消耗更低、语义内建、边界无歧义、可程序化解析、全生态结构一致。5.3 路由模式检查针对复杂技能如果目标技能是路由模式需检查核心原则必须内联在 SKILL.md而非单独文件——这是 recommended-structure.md 强调的Context gets skipped问题的对策关键原则放在独立文件里Claude 可能根本不读放在 SKILL.md 中则随技能调用自动加载有 intake 问题入门澄清问题有路由表routing table将意图映射到 workflow所有被引用的 workflow 文件真实存在所有被引用的 reference 文件真实存在。5.4 Workflow 检查若存在每个 workflow 文件应包含三段式结构对照 recommended-structure.md 的 workflow 模板required_reading段声明执行前必须立即阅读的 reference 文件process段分步操作流程success_criteria段完成判据。同时校验required_reading中引用的文件真实存在。5.5 内容质量检查原则可执行actionable而非空洞套话如be careful这类含糊表述步骤具体specific不是do the thing式的虚指成功标准可验证verifiable而不是User is satisfied这类不可测表述文件之间无冗余内容——同一信息在多处重复出现会增加维护负担与 token 消耗。六、Step 4生成审计报告审计结束后按固定模板输出报告## Audit Report: {skill-name} ### Passing - [list passing items] ### Issues Found 1. **[Issue name]**: [Description] → Fix: [Specific action] 2. **[Issue name]**: [Description] → Fix: [Specific action] ### Score: X/Y criteria passing这份模板刻意设计了两个强约束每个问题都必须附带→ Fix:具体修复动作——报告不仅诊断还给出下一步必须给出量化分数X/Y criteria passing——让技能健康度可横向比较、可追踪改进。七、Step 5提供修复选项发现问题后询问用户Would you like me to fix these issues?并提供三个选项Fix all— 一次性应用所有推荐修复Fix one by one— 逐项审阅修复方案后再应用Just the report— 仅保留报告不做任何改动。若用户选择修复工作流要求每次修改后立即校验文件有效性Verify file validity after each change修复完成后再汇报改动了什么。这与 skill-structure.md 的 validation_checklist 形成闭环修改后要重新验证 YAML frontmatter、XML 标签闭合、必备标签存在性、文件路径使用正斜杠、引用是否可达等。八、审计中应重点标记的反模式Anti-Patterns工作流内置了audit_anti_patterns区块审计时优先识别以下常见问题反模式描述Skippable principles核心原则放在独立文件而非内联导致可能被跳过Monolithic skill单一文件超过 500 行Mixed concerns操作步骤与领域知识混在同一文件中Vague steps如Handle the error appropriately这类无具体指令的步骤Untestable criteria如User is satisfied这类无法验证的完成标准Markdown headings in body正文用#而非 XML 标签Missing routing复杂技能缺少 intake/routing 机制Broken references提及了实际不存在的文件Redundant content同一信息在多处重复这九类反模式中Markdown headings in body与Broken references属于可程序化检测的确定性错误Vague steps与Untestable criteria属于语义质量问题需要结合 be-clear-and-direct.md 与 core-principles.md 等原则类参考文档进行主观判断。audit-skill.md的价值在于把这些判断从随意的印象转化为有据可查的清单逐项核对。九、与 GSD 运行时机制的结合审计并非孤立动作。GSD-2 为技能提供了完整的运行时观测与健康监控体系见 gsd-skill-ecosystem.md审计时可以交叉引用这些数据源技能发现会话启动时枚举两个目录并注入available_skillsauto-mode 下skill-discovery.ts在单元边界做目录快照比对新技能通过newly_discovered_skills注入/reload可手动重扫。技能遥测skill-telemetry.ts记录每个技能的读取次数、最后使用时间戳、pass/fail 率数据存储在~/.gsd/metrics.json闲置 60 天的技能会被标记为 stale。技能健康度skill-health.ts汇总遥测数据当成功率低于 70%、token 消耗趋势上升或闲置超过 60 天时给出旗标/doctor命令会在系统诊断中呈现技能健康问题。这意味着一次完整的技能审计除了工作流内置的结构化清单外还可以结合/doctor输出的健康旗标成功率、token 趋势、staleness来判断结构合规但行为退化的技能——例如一个结构完美但长时间未被使用的技能可能已偏离实际业务需求。十、审计工作流的完成判据audit-skill.md的success_criteria定义了审计完成的标准技能被完整阅读并分析Skill fully read and analyzed所有清单项均被评估All checklist items evaluated报告已呈现给用户Report presented to user修复已按需应用Fixes applied if requested用户对技能健康度有清晰认知User has clear picture of skill health注意第四条是按需应用if requested即审计工作流本身不强制修改是否修复完全由用户决定——这保证了审计是一个低侵入性的诊断流程适合在技能交付前、交付后以及技能长期无人维护等任意时间点执行。十一、动手实践用审计工作流复查一个真实技能以仓库内置的create-skill自身为例你可以用它来验证审计流程是否真的能发现好技能长什么样枚举技能目录确认create-skill出现在.agents/skills/项目级或~/.agents/skills/全局级在 GSD 中它通过 system-context.ts 的BUNDLED_SKILL_TRIGGERS表注册触发词为 Author or refine a GSD skill — SKILL.md structure, frontmatter, and best practices读取其 SKILL.md逐项核对 YAML frontmattername: create-skill与目录名一致、description为第三人称且同时说明做什么与何时用——均通过检查结构正文全部使用essential_principles、routing、quick_reference、reference_index、workflows_index、yaml_requirements、success_criteria等 XML 标签无 markdown 标题——通过检查路由routing中包含完整的意图到 workflow 映射表workflows/下 9 个文件全部存在且与workflows_index一一对应references 目录 12 个参考文件与reference_index一一对应——通过最终得分应为X/X criteria passing该技能可作为审计其他技能时的黄金基准。仓库中的回归测试 bundled-skill-triggers.test.ts 还验证了BUNDLED_SKILL_TRIGGERS中包括create-skill在内的内置技能均已被正确注册且 trigger/skill 字段非空、skill id 唯一。这意味着审计的对象不仅是文件系统里的目录还包括运行时注册表——一个技能即使文件结构合规若未在触发表中注册也无法被系统自动唤起这应被视为一种运行时层面的 Broken reference。结语audit-skill.md虽然只是一个 150 行左右的 workflow 文件但它浓缩了一套完整的技能质量保障方法论从两级目录枚举、五类清单核对frontmatter / 结构 / 路由模式 / workflow / 内容质量、结构化报告与评分到按需修复与二次校验。在 GSD-2 的长周期自治语境下这套审计工作流让技能健康度从模糊的主观感受变成了可打分、可修复、可追踪的工程实践而仓库中create-skill自身、skill-structure.md、use-xml-tags.md、recommended-structure.md、gsd-skill-ecosystem.md以及遥测/健康检查机制则共同构成了审计标准从何而来的完整答案。掌握这套审计方法后你可以随时为自己的技能库建立体检机制确保每一个 SKILL.md 都处于结构合规、内容可执行、引用可达的健康状态。赞分享人工智能AI Agent代码智能体Agent 编排CLIAI 应用【免费下载链接】gsd-2A powerful meta-prompting, context engineering and spec-driven development system that enables agents to work for long periods of time autonomously without losing track of the big picture项目地址https://gitcode.com/gh_mirrors/gs/gsd-2点击查看免费下载相关推荐智慧职教刷课脚本职业教育学习效率提升的智能解决方案智慧职教刷课脚本职业教育学习效率提升的智能解决方案 在职业教育在线学习日益普及的今天学生们常常面临课程任务繁重、学习时间有限的挑战。智慧职教刷课脚本作为一款人工智能AI 安全治理红蓝对抗AI Agent模型安全Gumroad 开源仓库 Issue 起草指南基于 create-issue Skill 的标准化工作流Gumroad 开源仓库 Issue 起草指南基于 create issue Skill 的标准化工作流 导读 本指南围绕 Gumroad 开源仓库中面向 A后端前端电商Ekko Agent Skill 创作指南基于 skill-creator 的设计、创建、维护与验证全流程Ekko Agent Skill 创作指南基于 skill creator 的设计、创建、维护与验证全流程 Ekko Agent位于本仓库 packagesAI 应用人工智能AI Agent本地部署前端后端工作流自动化上一篇xv6-riscv文件系统性能优化缓存策略改进下一篇Go 語言流程控制與函式設計以 build-web-application-with-golang 第 2.3 節為核心的實戰指南创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考