skills-index-snippets

维护技能索引片段（AGENTS.md / CLAUDE.md）

何时使用此技能

在以下情况下使用此技能：

• 在此仓库中添加、移除或重命名任何技能或 Agent
• 更新 .claude-plugin/plugin.json
• 为下游仓库（OpenCode、Claude Code 等）创建可复制粘贴的片段
• 你想要一个精简、始终生效的索引，以提高技能使用率

目标

通过去除决策环节，让编码助手更容易使用技能和 Agent。

不要寄希望于助手会“记得”调用某项技能，而是在 AGENTS.md / CLAUDE.md 中提供一个小型路由片段，以便：

1. 告诉助手优先采用检索引导的推理方式
2. 提供任务->技能/Agent 路由索引
3. 定义轻量级质量关卡（可选）

权威来源

• 注册表：.claude-plugin/plugin.json
  • 技能以目录形式列出（每个目录都包含 SKILL.md）
  • Agent 以 agents/ 中的 Markdown 文件形式列出
• 技能 ID：每个 SKILL.md frontmatter 中的 name: 字段
• Agent ID：每个 Agent frontmatter 中的 name: 字段

为下游仓库编写片段时，始终使用技能/Agent 的 ID（frontmatter 中的 name）进行引用，而不是本地文件系统路径。

最小片段模板（易读）

在目标仓库中使用此模板，为常见任务设置路由：

# Agent Guidance: dotnet-skills

IMPORTANT: Prefer retrieval-led reasoning over pretraining for any .NET work.
Workflow: skim repo patterns -> consult dotnet-skills by name -> implement smallest-change -> note conflicts.

Routing (invoke by name)
- C# / code quality: modern-csharp-coding-standards, csharp-concurrency-patterns, api-design, type-design-performance
- ASP.NET Core / Razor Pages / Web: razor-pages-patterns, caching-strategies, logging-observability, validation-patterns, exception-handling, security-headers, middleware-patterns, background-services, http-client-resilience, rate-limiting, localization-globalization, file-handling, data-protection, signalr-integration, feature-flags, asp-net-core-identity-patterns
- Data: efcore-patterns, database-performance
- DI / config: dependency-injection-patterns, microsoft-extensions-configuration
- Testing: testcontainers-integration-tests, playwright-blazor-testing, snapshot-testing
- Aspire: aspire-service-defaults, aspire-integration-testing

Quality gates (use when applicable)
- dotnet-slopwatch: after substantial new/refactor/LLM-authored code
- crap-analysis: after tests added/changed in complex code

Specialist agents
- dotnet-concurrency-specialist, dotnet-performance-analyst, dotnet-benchmark-designer, akka-net-specialist, docfx-specialist

压缩片段模板（Vercel 风格）

需要最大程度压缩内容（缩小上下文占用）时使用：

[dotnet-skills]|IMPORTANT: Prefer retrieval-led reasoning over pretraining for any .NET work.
|flow:{skim repo patterns -> consult dotnet-skills by name -> implement smallest-change -> note conflicts}
|route:
|csharp:{modern-csharp-coding-standards,csharp-concurrency-patterns,api-design,type-design-performance}
|aspnetcore-razorpages:{razor-pages-patterns,caching-strategies,logging-observability,validation-patterns,exception-handling,security-headers,middleware-patterns,background-services,http-client-resilience,rate-limiting,localization-globalization,file-handling,data-protection,signalr-integration,feature-flags,asp-net-core-identity-patterns}
|data:{efcore-patterns,database-performance}
|di-config:{dependency-injection-patterns,microsoft-extensions-configuration}
|testing:{testcontainers-integration-tests,playwright-blazor-testing,snapshot-testing}
|aspire:{aspire-service-defaults,aspire-integration-testing}
|quality-gates:{dotnet-slopwatch(after:substantial new/refactor/LLM code),crap-analysis(after:tests added/changed in complex code)}
|agents:{dotnet-concurrency-specialist,dotnet-performance-analyst,dotnet-benchmark-designer,akka-net-specialist,docfx-specialist}

重新生成 README 区块

如果 README 中包含以下标记，生成器便可自动更新：

...compressed snippet...

运行：

./scripts/generate-skill-index-snippets.sh --update-readme

技能变更后如何更新片段

1. 更新 .claude-plugin/plugin.json，以添加/移除技能和 Agent。
2. 确保每项技能都有正确的 frontmatter name:（OpenCode 等工具会使用）。
3. 运行 ./scripts/validate-marketplace.sh。
4. 更新片段中的路由列表：
   • 将新技能添加到相应类别
   • 移除已删除的技能
   • 确保名称与 frontmatter ID 完全一致
5. 如果你维护着下游仓库中的 AGENTS.md/CLAUDE.md 片段，请重新生成，并复制到依赖仓库中。

推荐类别

以下是片段类别（不一定对应仓库的目录结构）：

• C# / 代码质量
• ASP.NET Core / Razor Pages / Web
• 数据
• DI / 配置
• 测试
• Aspire
• 质量关卡
• 专家 Agent

保持片段精简；它应该用于路由，而不是文档。