HVE Core skill-hygiene结构检查指南每个SKILL.md的质检关卡【免费下载链接】hve-coreA refined collection of Hypervelocity Engineering components (instructions, prompts, agents, and skills) to start your project off right, or upgrade your existing projects to get the most out of GitHub Copilot项目地址: https://gitcode.com/GitHub_Trending/hv/hve-corehve-core 的skill-hygiene是一套面向SKILL.md的结构质检工具集它通过vally lint对.github/skills/下的每个技能执行快速、确定性的静态检查零 token 成本在 CI 中作为权威关卡拦截格式不合规的技能文件。本指南带你理解这套 SKILL.md 质检关卡查什么、怎么跑、与行为评测如何分工。为什么 SKILL.md 需要一道质检关卡在 Copilot 的渐进式加载模型中每个技能的name和description字段在启动时就会被读入上下文每个技能约 100 tokenSKILL.md正文在语义匹配后加载建议低于 5000 token。这意味着格式坏 成本白花一个description写得不规范的技能要么永远匹配不上任务要么被错误加载浪费宝贵的上下文预算引用失效 技能不可移植技能包会被分发到 CLI、扩展、插件等多种目录结构下任何指向技能目录之外或 404 的链接都会在分发后断掉孤儿文件 包体臃肿目录里堆着没被SKILL.md引用的文件只会让技能越来越大、越来越难审查。技能质量不是感觉好不好而是可以量化观测的。上图为 hve-core 文档中 Copilot OpenTelemetry 监控示例见 docs/customization/copilot-otel-metrics.md当 agent 会话的 token 消耗和调用量出现异常时技能定义不规范往往是嫌疑对象之一。而 skill-hygiene 正是把技能是否良构这个最基础的问题在消耗任何 token 之前就拦下来。skill-hygiene 到底检查哪些关卡skill-hygiene 是evals/下五个测试套件中唯一通过vally lint而非vally eval交付的套件——它不启动模型、不运行执行器只做文件系统级的快速静态读取。权威说明见 evals/skill-hygiene/README.md。当前扫过.github/skills/下全部 20 个技能分布在 8 个集合目录核心评分器grader分工如下评分器状态检查内容orphan-files✅ 启用标记技能目录内未被SKILL.md引用的孤儿文件valid-refs✅ 启用标记逃逸出技能目录或 404的 markdown 引用spec-compliance⚡ 自动运行检查 frontmatter 与结构合规性上游注册随 lint 报告自动输出skill-size⏸️ 暂缓体积检查规划中WI-08随 Phase 15 自定义 grader 插件工作启用一个容易踩的坑不要给这个目录添加eval.yaml。Vally 的 eval 评分器注册表不暴露orphan-files、valid-refs这类结构型评分器强行编写会在运行时抛出 Unknown grader type。vally lint子命令本身就是为这个契约设计的发现技能 → 运行静态评分器 → 输出逐技能通过/失败报告。三步运行 skill-hygiene 结构检查第一步本地一条命令复现 CI脚本定义在 package.json核心就是包裹一行vally lintnpm run ci:eval:lint:skills→ 等价于vally lint .github/skills/无需改任何配置新增技能放在.github/skills/collection/slug/SKILL.md后会被自动发现不需要更新任何清单文件。第二步理解 CI 门禁逻辑CI 中由eval-lint任务的 Run skill hygiene lint 步骤执行其特点是按需触发仅当变更清单changed-artifact manifest中至少包含一条kind: skill条目时才运行——改别的文件不会白白消耗这套检查权威阻塞非零退出码直接阻止 Pull Request合并禁止软化工作流文档明确反对给该步骤加continue-on-error: true这套关卡是权威的authoritative。第三步本地预检配套结构校验在提 PR 之前还有一道更细的本地结构校验npm run validate:skills→ 执行 scripts/linting/Validate-SkillStructure.ps1-WarningsAsErrors模式检查技能目录是否只包含认可的子目录scripts、references、assets、examples、tests、templates、frontmatter 是否合法等结果写入logs/skill-validation-results.json完整提交前清单见 docs/contributing/skills.md 的 Validation Checklist 一节。skill-hygiene 与其他质检套件的分工hve-core 的evals/目录把技能质量拆成了不同层级的关卡总览见 evals/README.md理解分工可以避免重复建设套件机制回答的问题成本skill-hygienevally lint静态技能是否良构0 token秒级skill-qualityvally evalcopilot-sdk 执行器3 次运行技能被调用后给出的指导是否准确消耗 token见 evals/skill-quality/eval.yamlagent-behaviorvally eval模型在环agent 的非确定性输出是否达标消耗 token设计哲学很清晰能静态判断的绝不请模型出手。skill-hygiene 只回答内环问题 is the skill well-formed?把模型预算留给真正需要语义判断的评测。上图这类 agent 调用趋势监控源图见 docs/customization/copilot-otel-metrics.md则提供了外层视角结构关卡保证了每个技能出厂合格遥测数据持续验证它们在生产中是否被正确加载与调用两者构成静态质检 动态观测的闭环。提交技能前的速查清单 提交技能前按顺序过一遍npm run ci:eval:lint:skills本地跑通每个技能都 PASSSKILL.md中所有文件引用都落在技能目录内./scripts/...而非仓库根相对路径目录中没有忘记引用的孤儿文件只使用了认可的子目录name与目录名一致npm run validate:skills无警告CI 以-WarningsAsErrors运行没有给evals/skill-hygiene/添加eval.yaml没有修改 CI 步骤的触发条件更多技能编写标准frontmatter 字段、调用控制矩阵、脚本与测试要求参考 docs/contributing/skills.md整体测试架构背景见 docs/architecture/testing.md。小结skill-hygiene 是 hve-core 技能生态的第一道确定性质检关卡零 token、秒级反馈、CI 权威阻塞。它用orphan-files、valid-refs和自动运行的spec-compliance三个静态评分器回答技能是否良构把模型评测的昂贵预算留给行为质量。对新手来说记住一句话就够先过 lint再谈 eval——结构不合格的技能连进入语义加载的资格都没有。【免费下载链接】hve-coreA refined collection of Hypervelocity Engineering components (instructions, prompts, agents, and skills) to start your project off right, or upgrade your existing projects to get the most out of GitHub Copilot项目地址: https://gitcode.com/GitHub_Trending/hv/hve-core创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考