把 .NET 项目规范封装成按需加载的技能

AI 能按团队规范写出一次代码，却经常在下一次对话里忘掉目录结构、返回类型和架构约定。作者给出的办法是：把反复解释的任务流程做成 Skills，随项目保存，需要时再加载。

这篇内容的价值，在于区分了「项目共同约定」和「某类任务的操作步骤」。不过，提供的原文只展开了 Skill 的基本结构与触发机制，没有给出效率实测，也没有展开标题预告中的完整 .NET 实践。

哪些规则该写进 Skill

作者遇到的问题很具体：每次新开对话，都得重新告诉 AI，项目不使用 Repository 模式、偏好充血领域模型，Handler 和 Service 返回 Result<T>。

这些要求分属两个层次。架构选择是项目的共同约定；创建接口时先建什么文件、实现哪个接口、如何处理失败结果，则是一套可重复执行的流程。

原文把前者交给 CLAUDE.md，把后者交给 Skill。作者建议 CLAUDE.md 控制在 100 行以内，用于记录项目事实和整体架构。这里的 100 行应理解为作者的写作建议，原文没有证明它是工具的强制限制。

值得固化成 Skill 的，是团队已经认可、会反复执行的任务流程。

例如，原文的 create-endpoint 技能要求：把接口放到 Features/<UseCase>/<UseCase>.Endpoint.cs，实现 IApiEndpoint，从 RouteConsts 映射路由，调用 Handler，再用 ToProblem() 转换失败的 Result<T>。

这些名字并不构成通用的 ASP.NET Core 标准，而是在表达这个项目选择的组织方式。Skill 的用途，就是让 AI 继续沿用这些选择。

为什么装了很多 Skill，也不必一次读完

按照原文描述，Skill 采用渐进式披露（progressive disclosure）：Claude 先看到技能名称和描述，判断当前任务是否匹配；匹配后读取完整的 SKILL.md；需要更细的资料时，再打开附带文件。

可以把它理解成先看目录，再读对应章节，最后查附录。

因此，技能的 description 不只是给人看的简介，还承担任务匹配的职责。作者的接口示例把触发范围写成：用户要求新增 endpoint、route 或 API operation 时使用。

描述太窄，用户换个表达可能匹配不上；描述太宽，不相关任务也可能读入这套规则。这是按原文机制可以推导出的风险，但作者没有提供触发准确率、误触发案例或测试结果。

正文同样需要克制。作者建议 SKILL.md 最多保持在几百行左右，长篇编码规范、API 参考和边界情况放入独立文件。加载方式决定了这种拆分有意义：模型只在需要时读取细节，主流程也更容易被看清。

不过，「支持按需读取」并不能证明每次都能选对资料。原文没有给出上下文消耗或执行成功率的对照数据。

一个 Skill 文件夹应该怎么拆

原文给出的完整目录，展示了如何把操作步骤、参考资料和可执行内容分开：

create-feature/
├── SKILL.md            (required: instructions + when to use)
├── references/         (optional: detailed docs loaded on demand)
│   └── architecture.md
├── scripts/            (optional: scripts Claude can run)
│   └── scaffold.ps1
└── assets/             (optional: files used in the output)
    └── Endpoint.template.cs

要注意第一行文件：只有 SKILL.md 是必需的，其余目录都可选，不必为了形式完整先建一套空架子。

SKILL.md 顶部使用 YAML frontmatter，重点是 name 和 description。前者采用 create-feature 这样的 kebab-case 命名，后者说明技能做什么、什么时候使用。下面的 Markdown 正文再写步骤、规则、示例和禁忌。

三个可选目录各有用途：

• references/ 保存按需查阅的说明，例如 architecture.md。
• scripts/ 保存可以直接执行的程序，例如负责创建目录的 scaffold.ps1。
• assets/ 保存输出时使用的素材，例如 Endpoint.template.cs、Dockerfile 或 .cshtml 模板。

脚本负责确定性的操作，模板负责稳定的文件骨架，文字负责解释选择和约束。这样组织，比要求模型每次重新生成全部细节更容易检查和维护。

原文给出的仓库路径是 .claude/skills/*，并称 Skills 也适用于 OpenAI Codex agent。但提供的内容没有交代 Codex 对应的存放路径、配置方式或兼容边界，不能直接把 Claude 的路径当成所有工具的统一约定。

我的判断

我认同作者把重复提示变成版本化项目文件的方向。团队成员能共享同一套流程，规则修改也能进入代码审查，比每个人维护自己的聊天开场白更方便。

但它成立有一个前提：团队本来就知道正确流程是什么。目录规范还在争论、错误处理方式尚未统一时，Skill 只能把暂定方案重复执行，不能替团队完成架构决策。

与普通文档相比，Skill 多了任务匹配和按需读取的入口；与脚手架相比，它可以容纳需要判断的步骤。但固定文件生成仍适合交给脚本，代码格式仍适合交给格式化工具，不能指望文字规则承担所有约束。

作者把 Skill 描述成写一次、以后每次遵循，这个承诺需要打折看。原文没有提供团队规模、采用周期或代码质量对照，现阶段更适合视为工作流经验。

另外，原文虽然预告了 Skill Creator、Claude Code、Desktop、CoWork，以及 gRPC、GraphQL、messaging 和 Microsoft 发布的 .NET Skills，提供的正文并未展开这些内容。不能据此判断它们的具体用法和效果。

能拿来做什么

• 从一个反复出现的任务开始，例如创建 ASP.NET Core Minimal API endpoint，把目录、接口、路由来源和失败处理写成一条完整流程，再检查生成结果是否遵守。
• 前端或 Node 团队可以借用这种拆分方式，把项目共同约定放在常驻说明里，把新增接口等重复任务放进独立 Skill；具体 API 和目录必须换成自己的真实规范。
• 已有脚手架就继续复用，把执行入口放进 scripts/，让 Skill 说明何时运行、需要哪些输入，以及生成后检查什么。
• 用不同措辞试跑同一个技能，同时尝试一个不相关任务，检查它是否该触发时触发、无关时保持安静，再决定是否推广给团队。