ecosystem-standards

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Ecosystem Standards Review Protocol

生态系统标准审查协议

This skill details how to perform an audit on new or existing capabilities (Skills, Plugins, Workflows, Sub-Agents, and Hooks) against authoritative ecosystem specifications to ensure they are created, installed, and structured correctly.

本Skill详细说明如何对照官方生态系统规范，对新增或现有能力（Skill、插件、工作流、子Agent、Hook）进行审计，确保其创建、安装和结构符合要求。

Instructions

操作指引

When invoked to review a codebase component or a planned extension:

Identify the Component Type: Determine if the subject is a Plugin boundary, an Agent Skill, an Antigravity Workflow/Rule, a Sub-Agent, or a Hook.
Recall the Specs: Before reviewing, read the relevant specification file found in the
```
ecosystem-authoritative-sources
```
skill library.
- Path:
```
../../references/*.md
```
Perform Rigorous Audit:
- Structure: Does the directory schema match the standard (
```
.claude-plugin/plugin.json
```
  ,
```
my-skill/SKILL.md
```
  )? Are all supporting files strictly organized into the official optional directories (
```
scripts/
```
  ,
```
references/
```
  ,
```
assets/
```
  ) rather than cluttering the skill root?
- Naming: Verify the skill name uses the gerund form (
```
verb + -ing
```
  , e.g.,
```
analyzing-spreadsheets
```
  ). Reject generic nouns. Ensure the
```
name
```
  is 1-64 lowercase alphanumeric chars/hyphens only, contains NO consecutive hyphens (
```
--
```
  ), and EXACTLY matches the parent directory name.
- Content: Does the YAML frontmatter adhere precisely to rules (
```
description
```
  1-1024 chars,
```
compatibility
```
  max 500 chars,
```
metadata
```
  strictly string-to-string keys/values)? Provide the recommendation to run
```
skills-ref validate ./my-skill
```
  to definitively catch parse errors.
- Description Viewpoint: Ensure the
```
description
```
  is written strictly in the third person ("Extracts text", not "I extract text") and isn't overly vague.
- Progressive Disclosure: For Skills, is the
```
SKILL.md
```
  file appropriately constrained (< 500 lines) with extraneous detail pushed to one-level deep reference files? Reject deeply nested reference chains.
- Reference Paths: Verify that all file references are strictly relative to the skill's root (e.g.,
```
scripts/extract.py
```
  ), avoiding absolute paths outside the plugin boundaries.
- Reference Readability: Do reference files >100 lines contain a Table of Contents for partial-read navigation?
- Script Quality: Verify python utility scripts do not punt errors back to the LLM (e.g., failing silently), but instead handle exceptions safely or emit clear
```
stderr
```
  messages. Ensure they don't use undocumented "magic numbers" (voodoo constants).
- Multi-CLI Support: When integrating agent CLI plugins, support exists for
```
claude-cli
```
  ,
```
gemini-cli
```
  , and
```
copilot-cli
```
  . Plugins must reflect the native CLI syntax in their system files.
- Anti-Patterns: Check for hardcoded credentials and Windows style paths (
```
\
```
  ).
- Connector Abstraction: If the plugin uses MCP tools, does it include a
```
CONNECTORS.md
```
  using the
```
~~category
```
  abstraction pattern instead of hardcoding specific tool names? This is required for portability. Ensure all native tool calls use the fully qualified
```
ServerName:tool_name
```
  format.
- Interaction Design Quality: For skills with user interaction, verify they use appropriate patterns:
  - Discovery phases use progressive questioning (broad → specific), not question walls
  - Decision points offer numbered option menus (3-7 items max)
  - Expensive operations have confirmation gates
  - Multi-step workflows include inline copyable checklists.
  - Skills end with next-action menus, not dead ends
  - Workflows taking long documents gracefully degrade using Document Format Agnosticism.
- Execution Safety (Plan-Validate-Execute): Do destructive or massive workflows mandate an intermediate verifiable plan file (e.g.,
```
changes.json
```
  ) before execution?
- Dual-Mode Architecture: If the skill both creates new artifacts AND improves existing ones, verify it implements the Bootstrap + Iteration dual-mode pattern with separate sections and trigger phrases.
- Output Templates: If the skill generates reports or artifacts, verify it either defines an output template or negotiates the format with the user.
- Escalation and Safety: Workflows with external risk must explicitly implement Graduated Autonomy Routing and Escalation Trigger Taxonomies rather than blanket-stopping on all issues.
- Source Transparency: Data synthesis output MUST conclude with explicit
```
Sources Checked
```
  and
```
Sources Unavailable
```
  blocks.
Produce Feedback: Provide explicit, granular feedback outlining exactly which ecosystem constraints were violated and concrete suggestions for fixing them. Ensure your feedback is actionable.

调用本Skill审查代码库组件或规划中的扩展时，请遵循以下步骤：

识别组件类型: 确定审查对象是插件边界、Agent Skill、Antigravity工作流/规则、子Agent还是Hook。
查阅规范: 审查前，请先阅读
```
ecosystem-authoritative-sources
```
Skill库中的相关规范文件。
- 路径:
```
../../references/*.md
```
执行严格审计:
- 结构: 目录模式是否符合标准（
```
.claude-plugin/plugin.json
```
  、
```
my-skill/SKILL.md
```
  ）？所有支持文件是否严格归类到官方指定的可选目录（
```
scripts/
```
  、
```
references/
```
  、
```
assets/
```
  ）中，而非杂乱放置在Skill根目录下？
- 命名: 验证Skill名称使用动名词形式（
```
动词 + -ing
```
  ，例如
```
analyzing-spreadsheets
```
  ），拒绝通用名词。确保
```
name
```
  字段仅包含1-64位小写字母、数字或连字符，不含连续连字符（
```
--
```
  ），且与父目录名称完全一致。
- 内容: YAML frontmatter是否严格遵循规则（
```
description
```
  长度1-1024字符，
```
compatibility
```
  最长500字符，
```
metadata
```
  严格为字符串键值对）？建议运行
```
skills-ref validate ./my-skill
```
  来精准捕获解析错误。
- 描述视角: 确保
```
description
```
  严格使用第三人称编写（例如"Extracts text"，而非"I extract text"），且内容不过于模糊。
- 渐进式信息披露: 对于Skill，
```
SKILL.md
```
  文件是否控制在合理长度（< 500行），无关细节是否下沉到一级深度的参考文件中？禁止使用深度嵌套的引用链。
- 引用路径: 验证所有文件引用严格相对于Skill根目录（例如
```
scripts/extract.py
```
  ），避免使用超出插件边界的绝对路径。
- 参考文件可读性: 超过100行的参考文件是否包含目录，支持部分读取导航？
- 脚本质量: 验证Python实用脚本不会将错误抛回给LLM（例如静默失败），而是安全处理异常或输出清晰的
```
stderr
```
  消息。确保脚本未使用未记录的"魔术数字"（无意义常量）。
- 多CLI支持: 集成Agent CLI插件时，需支持
```
claude-cli
```
  、
```
gemini-cli
```
  和
```
copilot-cli
```
  。插件必须在其系统文件中遵循原生CLI语法。
- 反模式检查: 检查是否存在硬编码凭据和Windows风格路径（
```
\
```
  ）。
- 连接器抽象: 如果插件使用MCP工具，是否包含
```
CONNECTORS.md
```
  文件，使用
```
~~category
```
  抽象模式而非硬编码特定工具名称？这是可移植性的要求。确保所有原生工具调用使用完全限定的
```
ServerName:tool_name
```
  格式。
- 交互设计质量: 带有用户交互的Skill，需验证其使用了合理的设计模式:
  - 探索阶段使用渐进式提问（从宽泛到具体），而非一次性抛出大量问题
  - 决策点提供编号选项菜单（最多3-7项）
  - 高成本操作设置确认门槛
  - 多步骤工作流包含可直接复制的内联检查清单。
  - Skill末尾提供后续操作菜单，而非无后续引导
  - 处理长文档的工作流遵循文档格式无关性原则，优雅降级适配
- 执行安全（计划-验证-执行）: 破坏性或大规模操作的工作流是否要求在执行前生成中间可验证计划文件（例如
```
changes.json
```
  ）？
- 双模式架构: 如果Skill既支持创建新产物也支持优化现有产物，需验证其实现了引导+迭代双模式，包含独立的模块和触发关键词。
- 输出模板: 如果Skill生成报告或产物，需验证其要么预定义了输出模板，要么会与用户协商输出格式。
- 上报与安全: 存在外部风险的工作流必须明确实现分级自治路由和上报触发分类机制，而非遇到所有问题都直接停止。
- 来源透明度: 数据合成输出必须在末尾明确包含
```
Sources Checked
```
  和
```
Sources Unavailable
```
  模块。
输出反馈: 提供明确、细粒度的反馈，准确说明违反了哪些生态系统约束，并给出具体的修复建议。确保反馈具备可操作性。