企业官网建设流程全解析

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-core

hve-core 的skill-hygiene是一套面向SKILL.md的结构质检工具集：它通过vally lint对.github/skills/下的每个技能执行快速、确定性的静态检查，零 token 成本，在 CI 中作为权威关卡拦截"格式不合规"的技能文件。本指南带你理解这套 SKILL.md 质检关卡查什么、怎么跑、与行为评测如何分工。

为什么 SKILL.md 需要一道质检关卡

在 Copilot 的渐进式加载模型中，每个技能的name和description字段在启动时就会被读入上下文（每个技能约 100 token），SKILL.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）分工如下：

一个容易踩的坑：不要给这个目录添加eval.yaml。Vally 的 eval 评分器注册表不暴露orphan-files、valid-refs这类结构型评分器，强行编写会在运行时抛出 "Unknown grader type"。vally lint子命令本身就是为这个契约设计的：发现技能 → 运行静态评分器 → 输出逐技能通过/失败报告。

三步运行 skill-hygiene 结构检查

第一步：本地一条命令复现 CI

脚本定义在 package.json，核心就是包裹一行vally lint：

• npm run ci:eval:lint:skills→ 等价于vally lint .github/skills/

无需改任何配置：新增技能放在.github/skills/<collection>/<slug>/SKILL.md后会被自动发现，不需要更新任何清单文件。

第二步：理解 CI 门禁逻辑

CI 中由eval-lint任务的 "Run skill hygiene lint" 步骤执行，其特点是：

1. 按需触发：仅当变更清单（changed-artifact manifest）中至少包含一条kind: skill条目时才运行——改别的文件不会白白消耗这套检查；
2. 权威阻塞：非零退出码直接阻止 Pull Request合并；
3. 禁止软化：工作流文档明确反对给该步骤加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-hygiene 只回答内环问题 "is the skill well-formed?"，把模型预算留给真正需要语义判断的评测。

上图这类 agent 调用趋势监控（源图见 docs/customization/copilot-otel-metrics.md）则提供了外层视角：结构关卡保证了每个技能"出厂合格"，遥测数据持续验证它们在生产中是否被正确加载与调用，两者构成"静态质检 + 动态观测"的闭环。

提交技能前的速查清单

🧹 提交技能前，按顺序过一遍：

• npm run ci:eval:lint:skills本地跑通，每个技能都 PASS
• SKILL.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