plugin-dev

1. 使命

此元技能确保AI生态系统的完整技术治理：设计、创建并持续优化共享的技能（.agents/skills/）、黄金规则与永久指令（.agents/rules/），以及对包知识的持续沉淀（[NomPkg]_IA_CONTEXT.md）。

不可违背的基本原则：

• 单一事实来源 (SSOT)： 所有规则、规范或指令必须存在于唯一的权威位置。严禁在多个文件中重复指令。
• DRY (Don't Repeat Yourself)： 绝不重写或复制现有指令。任何技能或文档均须通过简单引用或链接来利用现有规则。
• 系统应用 Anthropic 参考模式（feature-dev、claude-code-setup、pr-review-toolkit），确保规则不矛盾，记录新工作流，并以 YAML 事件报告形式捕获反馈。

2. 触发与限制

• 何时激活：
  • 会话结束/会话回顾： 通过 /plugin-dev 调用，为所处理的包以及所调用的技能提出丰富 [NomPkg]_IA_CONTEXT.md 的方案，记录会话期间的发现、陷阱和学到的机制。
  • 请求创建新技能（“创建一个管理自动化测试的技能”、“添加一个设计-架构技能”）。
  • 根据经验反馈优化或修正现有技能（“修改 feature-dev 技能以禁止 X”）。
  • 创建、更新或审计行为规则（“添加一条规则，显示已使用的技能”、“修改 critical-rules.md 中关于迁移的关键规则”）。
  • 记录新工作流。
  • 审计技能合规性、指令一致性、消除重复（DRY/SSOT）以及 SemVer 控制。
• 何时不激活：
  • 编写或简化教程 ➔ 使用 tutorial-writer。
  • 开发 Jekyll 组件或样式 ➔ 使用 dev-jekyll。
  • 同步共享技术基础（核心主题） ➔ 使用 sync-theme。
  • 代理初始化或项目诊断 ➔ 使用 project-setup。

3. 输入与需要加载的资源

• 优先级 1： .agents/skills/plugin-dev/resources/anthropic-skill-patterns.md（封装的 Anthropic 官方模式）。
• 优先级 2： 规则文件：
  • .agents/rules/critical-rules.md（不可变的关键规则）。
  • .agents/rules/*.md（执行和样式指令）。
• 优先级 3： .agents/templates/generic-skill.md（10节模板）和 .agents/templates/workflow-blueprint.md（流程模型）。
• 优先级 4： 全局中心的 catalog.yaml 和 CHANGELOG.md 注册表。

4. 约束与不可违背的规则

• SSOT（单一事实来源）与 DRY 核心原则：
  • 任何约定、指令或规范必须只存在于一个位置。
  • 行为规则位于 .agents/rules/[名称].md。技能绝不能复制这些规则的文本，而应直接引用它们。
• 包上下文文件的标准格式：
  • 任何包上下文文件必须命名为 modules/[NomPkg]/[NomPkg]_IA_CONTEXT.md（例如：PkgRealisationTache_IA_CONTEXT.md）。
• .agents/references/ 的严格简洁性（单一技能封装）：
  • 跨域目录 .agents/references/ 必须包含最少数量的文件，仅保留至少被两个技能共享的约定和标准。
  • 任何仅被单个技能使用的方法论文件、指南、目录或模板必须被移动并封装到 <skill>/resources/ 中（Anthropic 的渐进式披露原则）。
• 必须包含 inspiration 块： 任何创建或修改的技能必须在其 YAML frontmatter 中包含元数据 inspiration:，注明其来源、参考插件和模式。
• 严格遵循 10 节结构： 任何技能若缺少 10 节标准结构中的任意一节，则不得发布。
• 规则层次结构与非矛盾性：
  • 本地规则（.agents/rules/）优先于一般建议，但不得违反安全关键规则（critical-rules.md），除非经过明确仲裁。
  • 每条规则必须简洁、明确，并包含明确的触发器（trigger: always_on 或条件性）。
• 自动验证： 任何技能修改必须通过 node scripts/validate-skills.js 验证。
• YAML 事件报告： 代理错误导致的任何修复必须在 tests/feedbacks/INC-xxx.yaml 中生成报告。

5. 逐步流程（设计与优化工作流）

路径 A：创建新技能

1. 第 1 步：需求分析与 Anthropic 模式匹配：
   • 查阅 resources/anthropic-skill-patterns.md 选择最接近的模式（feature-dev、setup、review 等）。
2. 第 2 步：编写 SKILL.md：
   • 按照 10 节模板填写。
   • 以第三人称编写描述，清晰说明激活与排除场景。
   • 填写 YAML inspiration 块。
   • 将技能特有的任何辅助资源封装在其 resources/ 子目录中。
3. 第 3 步：确定性检查：
   • 执行 node scripts/validate-skills.js。
4. 第 4 步：注册到目录：
   • 在 catalog.yaml 中添加条目，并在 CHANGELOG.md 中记录。

路径 B：优化现有技能

1. 第 1 步：诊断与 YAML 报告：
   • 创建 tests/feedbacks/INC-[NUM].yaml，包含上下文、观察到的行为以及预期的修正。
2. 第 2 步：精准修正：
   • 将规则添加到第 #4 节（约束）或将二元测试添加到第 #8 节（检查清单）。
3. 第 3 步：SemVer 增量：
   • 更新版本（例如 1.0.1）并在 CHANGELOG.md 中记录。

路径 C：创建或修改规则

1. 第 1 步：规则级别分类：
   • 全局工程/安全规则 ➔ 添加到 .agents/rules/critical-rules.md 或 .agents/rules/general-principles.md。
   • 项目代理行为规则 ➔ 添加到 .agents/rules/[规则名称].md。
2. 第 2 步：简洁且不可违背的撰写：
   • 使用清晰的命令式语言（“代理必须...”、“严格禁止...”）。
   • 提供直接格式示例。
   • 遵守 SSOT 原则：如果规则已存在，绝不重复。
3. 第 3 步：同步与通知：
   • 将修改反映到中心或本地项目，并在 CHANGELOG.md 中记录变更。

路径 D：会话结束时的持续知识沉淀（/plugin-dev）

1. 第 1 步：回顾与发现识别：
   • 识别最近会话中处理的包。
   • 提取代理必须调查或推断的具体机制：
     • 涉及的表和模型、关系及业务钩子。
     • ViewStateService 或表过滤器的特殊性。
     • 新引入的时间服务、任务或观察者。
     • 已解决的陷阱或边界情况（例如，因省略父过滤器而导致的计算错误）。
2. 第 2 步：文档差距评估：
   • 将这些发现与 modules/[NomPkg]/[NomPkg]_IA_CONTEXT.md 的现有内容进行比较。
   • 检查技能（feature-dev）或规则是否可以从额外指令中受益。
3. 第 3 步：提出丰富方案：
   • 向设计者提交清晰、结构化的方案，详细说明建议的添加内容：
     • 针对 [NomPkg]_IA_CONTEXT.md（新服务、关键过滤器、陷阱与建议部分）。
     • 如适用，针对技能。
4. 第 4 步：验证后执行：
   • 一旦验证，丰富 [NomPkg]_IA_CONTEXT.md，以便任何未来的维护会话都能立即利用这些沉淀的知识。

6. 模糊性处理与决策

• 资源位置仲裁（技能 vs 代理）：
  • 如果资源仅由特定技能使用（例如，编辑器的编辑模板、专有技术目录） ➔ 强制位置：<skill>/resources/[文件].md（在技能第 3 节中按需加载）。
  • 如果资源定义了由两个或更多技能共享的跨领域工程标准 ➔ 位置：.agents/references/conventions/ 或 .agents/references/architecture/。
• 技能 vs 规则仲裁：
  • 如果指令是永久约束或跨领域防护措施（例如，显示技能、响应样式、禁止迁移） ➔ 创建规则（.agents/rules/）。
  • 如果指令描述了带有工具、请求触发、输入、逐步逻辑和可交付成果的序列 ➔ 创建技能（SKILL.md）。
• 如果请求的规则特定于 Solicode LMS：不要修改全局中心标准，而是将其写入 .agents/rules/ 和 .agents/references/conventions/project-conventions.md。

7. 输出格式与可交付成果

• 完整的 SKILL.md 文件或规则文件（.agents/rules/*.md）。
• 更新后的 catalog.yaml 和 CHANGELOG.md。
• validate-skills.js 脚本的执行结果（0 错误）。

8. 质量控制（二元检查清单）

• 技能的 YAML frontmatter 是否包含完整的 inspiration 块（来源、插件、模式）？
• 描述是否以第三人称编写，并明确说明何时激活及何时不激活？
• 10 节标准结构是否全部存在并填写？
• SSOT（单一事实来源）原则和 DRY 规则是否得到遵守（文件之间没有重复的指令）？
• .agents/references/ 目录是否最小化且不含任何单一技能资源？
• 单一技能资源是否严格封装在 <skill>/resources/ 中？
• 如果是规则，是否简洁、不与 critical-rules 矛盾，并附有清晰示例？
• node scripts/validate-skills.js 脚本是否成功通过？

9. 常见错误处理

典型错误	原因	立即解决方案
将特定资源放置在代理级别	封装粒度不足	将文件移动到 <skill>/resources/ 下并作为内部资源引用
为简单的被动规则创建技能	混淆规则与工具化流程	将指令转移到 .agents/rules/
忘记 inspiration 元数据	疏忽	在 frontmatter 中系统添加 inspiration 块
与中心标准冲突的本地规则	缺乏前期审计	在正式化规则前审计 .agents/rules/critical-rules.md

10. 具体示例（少量示例）

示例调用 A（技能）： “创建 tutorial-writer 技能，灵感来源于 content-authoring。” 行为： 代理加载 anthropic-skill-patterns.md，提取结构化写作模式，编写包含 inspiration: { plugin: "content-authoring" } 的 10 节内容，将教学模板隔离在 tutorial-writer/resources/ 中，并在 catalog.yaml 中注册该技能。

示例调用 B（规则）： “添加一条规则，强制在每次消息末尾显示已使用的技能。” 行为： 代理应用 plugin-dev 的路径 C，编写 .agents/rules/affichage-skills.md，更新 .agents/rules/critical-rules.md，并立即应用要求的格式。