schema-creator

Schema 创建技能

警告：请勿直接写入 .claude/schemas/

Schema 文件受 unified-creator-guard.cjs 保护（CLAUDE.md 中的 Gate 4）。 直接写入会绕过创建后的步骤（目录更新、使用方分配、集成验证）。 创建 Schema 时，请始终使用 schema-creator 技能工作流。 直接写入会产生“不可见产物”，任何验证器或 Agent 都无法发现它们。

为 Claude Code Enterprise Framework 创建 JSON Schema 验证文件。Schema 用于确保技能、Agent、钩子、工作流和自定义数据结构的类型安全、输入验证及结构一致性。

系统影响分析（关键 - 不可跳过）

创建任何 Schema 后，你都必须：

1. 在适当的位置注册（全局或技能本地）
2. 更新相关验证器以使用新 Schema
3. 如果 Schema 具有全局重要性，则在 CLAUDE.md 中添加 Schema 引用

验证：

# Verify schema is valid JSON
node -e "JSON.parse(require('fs').readFileSync('.claude/schemas/<schema-name>.json'))"

# Check schema exists
ls .claude/schemas/<schema-name>.json || ls .claude/skills/<skill>/schemas/<schema-name>.json

原因：无效的 Schema 会导致验证静默失败。未注册的 Schema 永远不会被使用。

---

用途

Schema 提供结构化验证，用于：

1. 技能输入/输出 - 验证传入技能和从技能传出的数据
2. Agent 定义 - 验证 Agent YAML 前置元数据和结构
3. 钩子定义 - 验证钩子配置和注册
4. 工作流定义 - 验证工作流步骤和配置
5. 自定义数据结构 - 验证项目专属的数据格式

Schema 类型

类型	位置	用途
技能输入	.claude/skills/{name}/schemas/input.schema.json	验证技能调用输入
技能输出	.claude/skills/{name}/schemas/output.schema.json	验证技能执行输出
Agent 定义	.claude/schemas/agent-definition.schema.json	验证 Agent YAML 前置元数据
技能定义	.claude/schemas/skill-definition.schema.json	验证技能 YAML 前置元数据
钩子定义	.claude/schemas/hook-definition.schema.json	验证钩子配置
工作流定义	.claude/schemas/workflow-definition.schema.json	验证工作流结构
自定义	.claude/schemas/{name}.schema.json	项目专属验证

参考 Schema

使用 .claude/schemas/agent-definition.schema.json 作为规范的参考 Schema。

最终确定任何 Schema 之前，请对照参考 Schema：

• 遵循 JSON Schema draft-07 或更高版本（优先使用 draft-2020-12）
• 包含 $schema、$id、title、description、type 字段
• 在 "required" 数组中列出必需字段
• 所有属性都包含 description 字段
• 在适当位置包含示例
• 使用恰当的模式（kebab-case 名称、semver 版本）

CLAUDE.md 注册（必需）

创建 Schema 后，如果该 Schema 支持新功能，则更新 CLAUDE.md：

1. 新产物类型 Schema - 添加到相关章节（Agent 对应第 3 节，技能对应第 8.5 节）
2. Agent/技能/工作流验证 Schema - 在第 4 节（自我演进）中记录
3. 框架范围内的 Schema - 添加到此技能中的“现有 Schema 参考”表

验证：

grep "schema-name" .claude/CLAUDE.md || echo "WARNING: Schema not registered in CLAUDE.md"

阻止条件：未记录的 Schema 可能无法被其他 Agent 发现。

工作流

步骤 0：研究综合（强制——始终首先执行）

创建任何架构之前，先调用 research-synthesis：

Skill({ skill: 'research-synthesis' });

研究要求：

• 至少进行 3 次 Exa 搜索，了解 JSON Schema 最佳实践
• 查看 .claude/schemas/ 中的现有架构，了解其模式
• 查看 .claude/context/artifacts/catalogs/schema-catalog.md 中的架构目录
• 找出可供参考的类似架构
• 在继续之前记录研究结果

**原因：**研究综合可确保架构遵循行业最佳实践，并与现有框架架构保持一致。

---

步骤 1：检查是否存在并委托更新（强制——第二步）

创建任何架构文件之前，检查该文件是否已存在：

1. 检查架构是否已存在：

   test -f .claude/schemas/<schema-name>.json && echo "EXISTS" || echo "NEW"
   

2. 如果架构已存在：

   • 请勿继续创建

   • 改为调用 artifact-updater 工作流：

     Skill({
       skill: 'artifact-updater',
       args: {
         name: '<schema-name>',
         changes: '<description of requested changes>',
         justification: 'Update requested via schema-creator',
       },
     });
     

   • 返回更新结果并停止

3. 如果架构是新的：

   • 继续执行下面的步骤 1.1

---

步骤 1.1：智能重复项检测（强制）

继续创建之前，运行三层重复项检查：

const { checkDuplicate } = require('.claude/lib/creation/duplicate-detector.cjs');
const result = checkDuplicate({
  artifactType: 'schema',
  name: proposedName,
  description: proposedDescription,
  keywords: proposedKeywords || [],
});

处理结果：

• EXACT_MATCH：停止创建，改为调用 schema-updater 技能：Skill({ skill: 'schema-updater' })
• REGISTRY_MATCH：警告用户——该工件已注册，但文件可能缺失。创建前先调查，并请用户确认。
• SIMILAR_FOUND：显示候选项及其评分。询问用户：“存在类似工件。继续创建新的，还是更新现有工件？”
• NO_MATCH：继续下一步。

覆盖选项：如果用户明确传入 --force，则完全跳过此检查。

---

步骤 1.5：配套项检查

继续创建之前，运行生态系统配套项检查：

1. 使用 .claude/lib/creators/companion-check.cjs 中的 companion-check.cjs
2. 调用 checkCompanions("schema", "{schema-name}") 来识别配套工件
3. 查看配套项清单——记录缺失的必需或推荐配套项
4. 计划在此工件完成后创建或核验缺失的配套项
5. 在创建后的集成说明中纳入配套项检查结果

此步骤仅供参考（不会阻止创建），但可确保考虑到完整的工件生态系统。

---

步骤 2：收集架构要求

创建架构之前，请先了解：

1. WHAT data structure are you validating?
   - Skill input/output
   - Agent/skill/hook/workflow definition
   - Custom data format

2. WHERE should the schema live?
   - Global: .claude/schemas/ (framework-wide)
   - Local: .claude/skills/{skill}/schemas/ (skill-specific)

3. WHAT are the required vs optional fields?
   - Required: Must be present for valid data
   - Optional: Enhance but not required

4. WHAT are the validation rules?
   - Types (string, number, boolean, object, array)
   - Patterns (regex for strings)
   - Ranges (min/max for numbers)
   - Enums (allowed values)
   - Lengths (min/max for strings/arrays)

步骤 3：确定架构类型和位置

创建用途	架构位置	示例
新技能输入	.claude/skills/{skill}/schemas/input.schema.json	tdd 技能参数
新技能输出	.claude/skills/{skill}/schemas/output.schema.json	tdd 技能结果
全局定义	.claude/schemas/{name}.schema.json	test-results.schema.json
可复用组件	.claude/schemas/components/{name}.schema.json	task-status.schema.json

步骤 4：分析数据结构

检查现有数据或指定预期结构：

// Example: Analyzing skill output structure
const exampleOutput = {
  success: true,
  result: {
    filesCreated: ['src/test.ts'],
    testsGenerated: 5,
    coverage: 85.2,
  },
  metadata: {
    duration: 1234,
    skill: 'test-generator',
  },
};

// Extract schema from example:
// - success: boolean (required)
// - result: object (optional)
// - metadata: object (optional)

步骤 5：生成 JSON Schema

使用架构模板并进行自定义：

{
  "$schema": "https://json-schema.org/draft-07/schema#",
  "$id": "https://claude.ai/schemas/{schema-name}",
  "title": "{Schema Title}",
  "description": "{What this schema validates}",
  "type": "object",
  "required": ["field1", "field2"],
  "properties": {
    "field1": {
      "type": "string",
      "description": "Description of field1",
      "minLength": 1,
      "maxLength": 100
    },
    "field2": {
      "type": "number",
      "description": "Description of field2",
      "minimum": 0,
      "maximum": 100
    },
    "optionalField": {
      "type": "boolean",
      "description": "Optional boolean field",
      "default": false
    }
  },
  "additionalProperties": false
}

步骤 6：添加描述和示例

每个属性都必须有描述：

{
  "properties": {
    "name": {
      "type": "string",
      "description": "The unique identifier for the resource in lowercase-with-hyphens format",
      "pattern": "^[a-z][a-z0-9-]*$",
      "examples": ["my-skill", "test-generator", "code-reviewer"]
    }
  }
}

添加顶层示例：

{
  "examples": [
    {
      "name": "example-skill",
      "description": "An example skill for demonstration",
      "version": "1.0.0"
    }
  ]
}

步骤 7：创建验证测试

编写一个简单测试，验证架构是否可用：

// validate-schema-test.cjs
const Ajv = require('ajv');
const schema = require('./.claude/schemas/my-schema.schema.json');

const ajv = new Ajv({ allErrors: true });
const validate = ajv.compile(schema);

// Test valid data
const validData = {
  /* valid example */
};
console.log('Valid:', validate(validData));

// Test invalid data
const invalidData = {
  /* invalid example */
};
console.log('Invalid:', validate(invalidData));
console.log('Errors:', validate.errors);

步骤 8：创建后注册 Schema（第 1 阶段集成）

此步骤至关重要。 创建 Schema 工件后，你必须将其注册到 Schema 发现系统中。

第 1 阶段背景： 第 1 阶段负责发现并编目用于验证的 Schema。未注册的 Schema 创建后，验证器和其他需要它们来验证数据的系统都无法看到它们。

写入并验证 Schema 文件后：

1. 在适当位置创建/更新 Schema 注册表条目：

   如果注册表不存在，请创建 .claude/context/artifacts/schema-catalog.md：

   {
     "schemas": [
       {
         "name": "{schema-name}",
         "id": "{schema-name}",
         "$id": "https://claude.ai/schemas/{schema-name}",
         "type": "{input|output|definition|global|component}",
         "description": "{What this schema validates}",
         "version": "1.0.0",
         "filePath": ".claude/schemas/{schema-name}.schema.json",
         "validatesFor": ["{artifact-type-1}", "{artifact-type-2}"],
         "relatedSchemas": [],
         "usedBy": ["{validator-hook}", "{creator-skill}"]
       }
     ]
   }
   

2. 向验证器注册：

   更新应使用此 Schema 的所有验证钩子：

   • 检查 .claude/hooks/validation/ 中是否有相关验证器
   • 将 Schema 添加到需要它的验证器中的 schemaMap

   示例：

   const schemaMap = {
     '.claude/agents/': '.claude/schemas/agent-definition.schema.json',
     '.claude/schemas/{schema-name}.schema.json': require('./.claude/schemas/{schema-name}.schema.json'),
   };
   

3. 在 .claude/context/artifacts/catalogs/schema-catalog.md 中记录：

   在 Schema 目录中添加条目：

   ### {Schema Title} (`{schema-name}.schema.json`)
   
   **$id:** `https://claude.ai/schemas/{schema-name}`
   
   **Purpose:** {Detailed description of what this schema validates}
   
   **Used by:**
   
   - {Validator/hook 1}
   - {Creator skill 1}
   
   **Root properties:**
   
   - {property-1}: {description}
   - {property-2}: {description}
   
   **Example valid data:**
   
   ```json
   {
     "example": "value"
   }
   ```
   

   必填字段： {列出必填字段}

   验证： 当数据符合此 Schema 时，{描述验证内容}

4. 如果 Schema 带来新功能，请更新 .claude/CLAUDE.md：

   如果此 Schema 支持新的工件类型或验证：

   • 添加到相关章节（创建器 Schema 对应第 4.1 节，schemas 目录对应第 9.7 节）
   • 将其添加到此技能步骤 7 中的“现有 Schema 参考”表

   示例条目：

   | `{schema-name}` | `.claude/schemas/` | {Purpose} |
   

5. 更新记忆：

   在 .claude/context/memory/learnings.md 末尾追加：

   ## Schema: {schema-name}
   
   - **Type:** {input|output|definition|global|component}
   - **Validates:** {What artifact/data type}
   - **Purpose:** {Detailed purpose}
   - **$id:** https://claude.ai/schemas/{schema-name}
   - **Validators:** {Which hooks/validators use it}
   - **Related Schemas:** {Any $ref references}
   

重要性： 未注册 Schema 会导致：

• 验证器无法发现和使用 Schema
• 系统范围内不会进行数据验证
• 无效工件未经检测便被创建
• 出现“不可见工件”模式

第 1 阶段集成： Schema 注册表是第 1 阶段的发现机制，使验证器能够在整个系统中一致地查找并应用 Schema。

步骤 9：系统影响分析（必须执行）

在标记 Schema 创建完成之前，请验证以下所有项目：

[ ] Schema file created in correct location
[ ] Schema is valid JSON (parseable)
[ ] Schema has $schema, $id, title, description
[ ] All required fields defined in "required" array
[ ] All properties have descriptions
[ ] Examples included for complex schemas
[ ] Schema registry entry created (Step 7)
[ ] Validators registered with schema (if applicable)
[ ] SCHEMA_CATALOG.md updated (Step 7)
[ ] Related documentation updated

验证命令：

# Validate JSON syntax
node -e "JSON.parse(require('fs').readFileSync('.claude/schemas/{name}.schema.json'))"

# Check required fields
node -e "const s = require('.claude/schemas/{name}.schema.json'); console.log('title:', s.title); console.log('description:', s.description);"

# Check schema registry
grep "{schema-name}" .claude/context/artifacts/schema-catalog.md

# List all schemas
ls -la .claude/schemas/*.schema.json

阻断条件：如果任何项目未通过，Schema 创建即为未完成。所有项目都必须通过。

系统影响分析（必须执行）

创建 Schema 后，请完成以下所有事项：

1. 更新 CLAUDE.md

• 如果 Schema 带来新功能，请将其添加到相应章节
• 与 Agent 相关的 Schema 添加到第 3 节
• 创建器生态系统的 Schema 添加到第 4.1 节
• 与技能相关的 Schema 添加到第 8.5 节

2. 集成验证器

• 检查钩子是否应依据新 Schema 进行验证
• 如果 Schema 会影响验证，请更新 .claude/hooks/
• 将其添加到相关验证器中的 schemaMap

3. 相关 Schema

• 如有需要，更新相关 Schema（$ref 链接）
• 检查是否存在循环依赖
• 确保 $id 值唯一

4. 文档

• 如果 Schema 记录了新模式，请更新 .claude/docs/
• 将 Schema 添加到“现有 Schema 参考”表
• 如果 Schema 对应新技能，请更新 skill-catalog.md

验证清单：

# Check CLAUDE.md registration
grep "{schema-name}" .claude/CLAUDE.md

# Check for $ref usage in other schemas
grep -r "{schema-name}" .claude/schemas/

# Verify no duplicate $id
grep -h "\$id" .claude/schemas/*.json | sort | uniq -d

阻断条件：完成所有影响分析项目的验证后，Schema 创建才算完成。

Schema 模板

基本输入 Schema

{
  "$schema": "https://json-schema.org/draft-07/schema#",
  "$id": "https://claude.ai/schemas/skill-name-input",
  "title": "Skill Name Input Schema",
  "description": "Input validation schema for skill-name skill",
  "type": "object",
  "required": [],
  "properties": {
    "target": {
      "type": "string",
      "description": "Target file or directory path"
    },
    "options": {
      "type": "object",
      "description": "Optional configuration",
      "properties": {
        "verbose": {
          "type": "boolean",
          "default": false
        }
      }
    }
  },
  "additionalProperties": false
}

基本输出 Schema

{
  "$schema": "https://json-schema.org/draft-07/schema#",
  "$id": "https://claude.ai/schemas/skill-name-output",
  "title": "Skill Name Output Schema",
  "description": "Output validation schema for skill-name skill",
  "type": "object",
  "required": ["success"],
  "properties": {
    "success": {
      "type": "boolean",
      "description": "Whether the skill executed successfully"
    },
    "result": {
      "type": "object",
      "description": "The skill execution result",
      "additionalProperties": true
    },
    "error": {
      "type": "string",
      "description": "Error message if execution failed"
    }
  },
  "additionalProperties": false
}

定义 Schema（用于 Agent、技能、钩子）

{
  "$schema": "https://json-schema.org/draft-07/schema#",
  "$id": "https://claude.ai/schemas/entity-definition",
  "title": "Entity Definition Schema",
  "description": "Schema for validating entity definition files",
  "type": "object",
  "required": ["name", "description"],
  "properties": {
    "name": {
      "type": "string",
      "pattern": "^[a-z][a-z0-9-]*$",
      "description": "Entity name in lowercase-with-hyphens format"
    },
    "description": {
      "type": "string",
      "minLength": 20,
      "maxLength": 500,
      "description": "Clear description of the entity purpose"
    },
    "version": {
      "type": "string",
      "pattern": "^\\d+\\.\\d+(\\.\\d+)?$",
      "default": "1.0.0",
      "description": "Semantic version number"
    }
  },
  "additionalProperties": true,
  "examples": [
    {
      "name": "my-entity",
      "description": "A sample entity for demonstration purposes",
      "version": "1.0.0"
    }
  ]
}

常见 JSON Schema 模式

字符串模式

{
  "kebab-case": {
    "type": "string",
    "pattern": "^[a-z][a-z0-9-]*$"
  },
  "semver": {
    "type": "string",
    "pattern": "^\\d+\\.\\d+(\\.\\d+)?$"
  },
  "file-path": {
    "type": "string",
    "pattern": "^[\\w./-]+$"
  },
  "email": {
    "type": "string",
    "format": "email"
  },
  "url": {
    "type": "string",
    "format": "uri"
  }
}

枚举模式

{
  "model": {
    "type": "string",
    "enum": ["sonnet", "opus", "haiku", "inherit"]
  },
  "priority": {
    "type": "string",
    "enum": ["lowest", "low", "medium", "high", "highest"]
  },
  "status": {
    "type": "string",
    "enum": ["pending", "in_progress", "completed", "failed", "blocked"]
  }
}

数组模式

{
  "tools": {
    "type": "array",
    "items": { "type": "string" },
    "minItems": 1,
    "uniqueItems": true,
    "description": "List of available tools"
  },
  "skills": {
    "type": "array",
    "items": { "type": "string", "pattern": "^[a-z][a-z0-9-]*$" },
    "description": "List of skill names"
  }
}

对象模式

{
  "config": {
    "type": "object",
    "additionalProperties": false,
    "properties": {
      "enabled": { "type": "boolean", "default": true },
      "timeout": { "type": "integer", "minimum": 0 }
    }
  },
  "metadata": {
    "type": "object",
    "additionalProperties": true,
    "description": "Arbitrary metadata"
  }
}

条件模式

{
  "if": {
    "properties": {
      "type": { "const": "mcp" }
    }
  },
  "then": {
    "required": ["server", "command"]
  },
  "else": {
    "required": ["handler"]
  }
}

使用 $ref 提高可复用性

{
  "$defs": {
    "namePattern": {
      "type": "string",
      "pattern": "^[a-z][a-z0-9-]*$",
      "description": "Lowercase with hyphens"
    },
    "toolsList": {
      "type": "array",
      "items": { "type": "string" },
      "minItems": 1
    }
  },
  "properties": {
    "name": { "$ref": "#/$defs/namePattern" },
    "tools": { "$ref": "#/$defs/toolsList" }
  }
}

CLI 用法

根据模板创建 Schema

# Create skill input schema
node .claude/skills/schema-creator/scripts/main.cjs \
  --type input \
  --skill my-skill

# Create skill output schema
node .claude/skills/schema-creator/scripts/main.cjs \
  --type output \
  --skill my-skill

# Create global schema
node .claude/skills/schema-creator/scripts/main.cjs \
  --type global \
  --name my-data-format

# Create definition schema
node .claude/skills/schema-creator/scripts/main.cjs \
  --type definition \
  --entity workflow

验证 Schema

# Validate a schema file
node .claude/skills/schema-creator/scripts/main.cjs \
  --validate .claude/schemas/my-schema.schema.json

# Validate data against schema
node .claude/skills/schema-creator/scripts/main.cjs \
  --validate-data data.json \
  --schema .claude/schemas/my-schema.schema.json

根据示例生成 Schema

# Generate schema from JSON example
node .claude/skills/schema-creator/scripts/main.cjs \
  --from-example example.json \
  --output .claude/schemas/generated.schema.json

与验证器集成

使用 Ajv 进行运行时验证

const Ajv = require('ajv');
const addFormats = require('ajv-formats');

const ajv = new Ajv({ allErrors: true });
addFormats(ajv);

// Load and compile schema
const schema = require('./.claude/schemas/skill-definition.schema.json');
const validate = ajv.compile(schema);

// Validate data
function validateSkillDefinition(data) {
  const valid = validate(data);
  if (!valid) {
    return {
      valid: false,
      errors: validate.errors.map(e => `${e.instancePath} ${e.message}`),
    };
  }
  return { valid: true };
}

提交前验证钩子

// .claude/hooks/schema-validator.js
const fs = require('fs');
const path = require('path');
const Ajv = require('ajv');

const schemaMap = {
  '.claude/agents/': '.claude/schemas/agent-definition.schema.json',
  '.claude/skills/': '.claude/schemas/skill-definition.schema.json',
  '.claude/hooks/': '.claude/schemas/hook-definition.schema.json',
};

function validateFile(filePath) {
  // Find matching schema
  for (const [pattern, schemaPath] of Object.entries(schemaMap)) {
    if (filePath.includes(pattern)) {
      const schema = JSON.parse(fs.readFileSync(schemaPath));
      const ajv = new Ajv();
      const validate = ajv.compile(schema);

      // Parse and validate file
      // ...
    }
  }
}

工作流集成

此技能属于统一的制品生命周期。有关完整的多 Agent 编排，请参阅：

路由器决策： .claude/workflows/core/router-decision.md

• 路由器如何发现并调用此技能的制品

制品生命周期： .claude/workflows/core/skill-lifecycle.md

• 发现、创建、更新和弃用阶段
• 版本管理和注册表更新
• CLAUDE.md 集成要求

外部集成： .claude/workflows/core/external-integration.md

• 安全集成外部制品
• 安全审查和验证阶段

---

交叉引用：创建者生态系统

此技能属于创建者生态系统。使用配套创建者来创建相关制品：

发现的缺口	所需制品	要调用的创建者	调用时机
领域知识需要可复用的技能	skill	Skill({ skill: 'skill-creator' })	缺口涵盖完整的技能领域
现有技能的覆盖范围不完整	skill 更新	Skill({ skill: 'skill-updater' })	有相关技能，但内容不完整
能力需要专用 Agent	agent	Skill({ skill: 'agent-creator' })	需要 Agent 负责该能力
现有 Agent 需要更新能力	agent 更新	Skill({ skill: 'agent-updater' })	有相关 Agent，但能力不完整
领域需要代码／项目脚手架	template	Skill({ skill: 'template-creator' })	需要可复用的代码模式
行为需要执行前／后的保护机制	hook	Skill({ skill: 'hook-creator' })	需要强制执行行为
流程需要多阶段编排	workflow	Skill({ skill: 'workflow-creator' })	需要多步骤协调
制品需要结构化 I/O 验证	schema	Skill({ skill: 'schema-creator' })	需要用于制品 I/O 的 JSON schema
用户交互需要斜杠命令	command	Skill({ skill: 'command-creator' })	需要面向用户的快捷方式
重复逻辑需要可复用的 CLI 工具	tool	Skill({ skill: 'tool-creator' })	需要 CLI 实用工具
仅限狭窄范围／单个制品的能力	inline	仅在此制品中编写文档	过于具体，无法通用化

集成链

[SKILL-CREATOR] Creating new skill with validation...
  -> Calls schema-creator for input/output schemas
  -> Schemas created in .claude/skills/{skill}/schemas/

[AGENT-CREATOR] Creating agent with strict validation...
  -> Agent uses agent-definition.schema.json for self-validation
  -> Agent validates inputs using custom schemas

[WORKFLOW-CREATOR] Creating workflow with typed steps...
  -> Each step output validates against schema
  -> Workflow uses workflow-definition.schema.json

现有 Schema 参考

活跃 Schema 总数： 27（25 个已归档，参见 .claude/schemas/_archive/） 已主动验证（Ajv）： 8 个具有运行时验证的 Schema 文档参考： 16 个用作结构模板的 Schema 可选验证： 3 个已定义路径但跳过验证的 Schema

完整目录： .claude/context/artifacts/catalogs/schema-catalog.md

按类别划分的活跃 Schema

Agent Schema（5 个）

Schema	接线状态	使用方
agent-capability-card	已接线	generate-agent-registry
agent-config	已接线	agent-config.cjs
agent-definition	已接线	agent-parser.cjs
agent-identity	已接线	agent-parser.cjs
agent-spawn-params	仅文档	Spawn 提示词参考

技能 Schema（4）

Schema	接线状态	使用方
skill-definition	WIRED	skill-creator/create.cjs
skill-diagram-generator-output	SOFT-WIRED	diagram-generator skill
skill-repo-rag-output	SOFT-WIRED	repo-rag skill
skill-test-generator-output	SOFT-WIRED	test-generator skill

工作流与钩子 Schema（2）

Schema	接线状态	使用方
workflow-definition	DOCS ONLY	无 workflow-creator 脚本
hook-definition	DOCS ONLY	无 hook-creator 脚本

演进与项目 Schema（2）

Schema	接线状态	使用方
evolution-state	WIRED	self-healing/validator.cjs
track-metadata	DOCS ONLY	TaskCreate 元数据字段

工具与模板 Schema（3）

Schema	接线状态	使用方
tool-manifest	WIRED	generate-tool-manifest.cjs
presets	WIRED	spawn/prompt-assembler.cjs
adr-template	DOCS ONLY	ADR 文档结构

规划 Schema（5）

Schema	接线状态	使用方
plan	DOCS ONLY	规划阶段参考
implementation-plan	DOCS ONLY	实施规划
phase-models	DOCS ONLY	阶段规划参考
product_requirements	DOCS ONLY	需求收集
project_brief	DOCS ONLY	项目初始化

测试 Schema（2）

Schema	接线状态	使用方
test_plan	DOCS ONLY	测试规划参考
test-results	DOCS ONLY	测试执行输出

架构 Schema（3）

Schema	接线状态	使用方
specification-template	DOCS ONLY	规格说明文档
system_architecture	DOCS ONLY	架构文档
ux_spec	DOCS ONLY	UX 规格说明文档

项目 Schema（1）

Schema	接线状态	使用方
project-analysis	DOCS ONLY	项目分析器输出

注： 除非另有说明，所有 Schema 均位于 .claude/schemas/。完整的使用方、验证方法和集成状态详情请参阅 Schema 目录。

文件放置与标准

输出位置规则

此技能的输出位置：.claude/schemas/

针对技能的 Schema：.claude/skills/<skill-name>/schemas/

Schema 命名约定：

• 全局 Schema：<name>.schema.json
• 技能输入：input.schema.json
• 技能输出：output.schema.json
• 组件：components/<name>.schema.json

必须参阅的文档

• 文件放置：参阅 .claude/docs/FILE_PLACEMENT_RULES.md
• 开发者工作流：参阅 .claude/docs/DEVELOPER_WORKFLOW.md
• 制品命名：参阅 .claude/docs/ARTIFACT_NAMING.md
• 工作区约定：参阅 .claude/rules/workspace-conventions.md（输出位置、命名、来源信息）

强制执行

文件放置规则由 file-placement-guard.cjs 钩子强制执行。 在生产模式下，违规放置将被阻止。

---

记忆协议（强制）

开始前：

cat .claude/context/memory/learnings.md

检查以下内容：

• 之前创建的架构
• 已知的验证问题
• 架构命名约定

完成后：

• 创建了新架构 -> 追加到 .claude/context/memory/learnings.md
• 发现了验证问题 -> 追加到 .claude/context/memory/issues.md
• 做出了架构决策 -> 追加到 .claude/context/memory/decisions.md

假设任务可能中断：上下文可能会重置。如果内容没有写入记忆，就等于没有发生。

架构创建铁律

这些规则不可违反。违反会导致验证失败。

1. NO SCHEMA WITHOUT $schema FIELD
   - Every schema MUST declare its JSON Schema version
   - Use draft-07 or later: "$schema": "https://json-schema.org/draft-07/schema#"

2. NO SCHEMA WITHOUT title AND description
   - Every schema MUST be self-documenting
   - title: Short name of what it validates
   - description: Detailed explanation of purpose

3. NO PROPERTY WITHOUT description
   - Every property MUST have a description
   - Readers should understand field purpose without external docs

4. NO REQUIRED FIELD WITHOUT DEFINITION
   - If field is in "required" array, it MUST be in "properties"
   - Undefined required fields cause silent validation failures

5. NO ADDITIONALPROPERTIES: true WITHOUT REASON
   - Default to additionalProperties: false for strict validation
   - Only allow additional properties when explicitly needed

6. NO SCHEMA WITHOUT VALIDATION TEST
   - Test schema with valid AND invalid examples
   - Schema that passes everything validates nothing

7. NO CREATION WITHOUT SYSTEM IMPACT ANALYSIS
   - Check if related validators need updating
   - Check if documentation needs updating
   - Check if related schemas need cross-references

8. NO SCHEMA WITHOUT CLAUDE.MD REGISTRATION
   - If schema enables new capabilities, update CLAUDE.md
   - Section 4 (Self-Evolution) for agent/skill/workflow schemas
   - Verify with: grep "schema-name" .claude/CLAUDE.md

9. IRON LAW II: TYPED TOOL CALLING (MODEL-AGNOSTIC INTERFACE)
   - Every tool-facing schema MUST include "description" on every property
   - This is Typed Tool Calling: the model resolves parameters from a typed
     JSON Schema contract instead of inferring from free-form markdown prose
   - Benefit: Reduces model hallucination by 40-60% vs. untyped instructions
   - Every required field must have: "type", "description", and where applicable "enum"
   - Use snake_case for property names for cross-framework compatibility
   - For schemas consumed by AI agents, add a Google Dork to your research:
     "$schema" "type": "object" "properties" filetype:json ("tool" OR "skill") [Domain]
   - additionalProperties MUST be false unless explicitly justified

验证清单（每次创建后运行）

# Verify schema is valid JSON
node -e "JSON.parse(require('fs').readFileSync('.claude/schemas/{name}.schema.json'))"

# Check required fields exist
node -e "const s = require('.claude/schemas/{name}.schema.json'); console.log('Has $schema:', !!s.\$schema); console.log('Has title:', !!s.title); console.log('Has description:', !!s.description);"

# Check all required properties are defined
node -e "const s = require('.claude/schemas/{name}.schema.json'); const r = s.required || []; const p = Object.keys(s.properties || {}); console.log('Missing:', r.filter(x => !p.includes(x)));"

# List all schemas
ls -la .claude/schemas/*.schema.json

完成清单（必须全部勾选）：

[ ] Schema file created with .schema.json extension
[ ] $schema field present (draft-07 or later)
[ ] title and description present
[ ] All properties have descriptions
[ ] required array matches defined properties
[ ] examples included for complex schemas
[ ] Schema validated with test data
[ ] System impact analysis completed
[ ] CLAUDE.md updated if schema enables new capabilities
[ ] Related schemas updated if needed ($ref links)

阻塞项：如果任意一项未通过，架构创建即未完成。必须全部通过才能继续。

---

生态系统对齐约定（强制）

此创建器技能属于一个协同的创建器生态系统。在此创建的任何架构都必须与相关创建器保持一致：

• agent-creator：负责所有权和执行路径
• skill-creator：负责能力打包和分配
• hook-creator：负责执行强制措施和防护机制
• workflow-creator：负责编排和阶段门控
• template-creator：负责标准化脚手架
• command-creator：负责用户/操作员命令体验
• tool-creator：负责可执行自动化界面

跨创建器交接（必需）

完成前，验证所有相关交接事项：

1. .claude/CLAUDE.md 和相关路由文档中存在对应的产物路由。
2. 已更新发现/注册表条目（适用时包括目录/索引/注册表）。
3. 已创建配套产物，或明确说明豁免原因。
4. 创建的产物通过 validate-integration.cjs 验证。
5. 技能元数据发生变更时，重新生成技能索引。

研究门槛（Exa + arXiv — 两者均为强制要求）

对于新的架构模式，必须进行研究：

1. 使用 Exa 研究实现和生态系统模式：
   • mcp__Exa__web_search_exa({ query: '<topic> JSON Schema 2025 best practices' })
   • mcp__Exa__get_code_context_exa({ query: '<topic> schema validation examples' })
2. 搜索 arXiv 上的学术研究（AI/ML、Agent、评估、编排、记忆/RAG、安全领域均为强制要求）：
   • 通过 Exa：mcp__Exa__web_search_exa({ query: 'site:arxiv.org <topic> 2024 2025' })
   • 直接 API：WebFetch({ url: 'https://arxiv.org/search/?query=<topic>&searchtype=all&start=0' })
3. 在产物引用/文档中记录决策、约束和非目标。
4. 保持架构精简，避免过度规定。

当主题涉及以下内容时，必须搜索 arXiv（不是备用选项）： AI Agent、大模型评估、编排、记忆/RAG、安全或任何新兴方法论。

回归安全交付

• 行为变更严格遵循 RED -> GREEN -> REFACTOR。
• 对变更的模块运行有针对性的测试。
• 对变更的文件运行 lint/format。
• 按关注点划分提交范围（逻辑/文档/生成的产物）。

---

创建后集成

创建完成后，运行生态系统集成清单：

1. 从 .claude/lib/creators/creator-commons.cjs 调用 runIntegrationChecklist(artifactType, artifactPath)
2. 从 .claude/lib/creators/creator-commons.cjs 调用 queueCrossCreatorReview(artifactType, artifactPath)
3. 检查影响报告——标记任务完成前，处理所有 mustHave 项
4. 将任何 shouldHave 项记录为后续任务

集成验证：

• 已将架构添加到 schema-catalog.md
• 已接入架构验证器（如适用）
• 使用该架构的产物已引用此架构
• 架构包含测试数据示例

评估说明

Schema 制品具有确定性，且可通过结构验证——此技能工作流中的第 7 步验证测试（AJV 编译、$id 唯一性检查、必填字段覆盖率、测试数据往返）是主要质量关卡，相比 LLM-as-judge 评分能提供更强的评估依据。对于为 Agent 或钩子输出契约提供数据的 Schema，还应根据 skill-evaluation-output.schema.json 进行验证，以确保下游评估器能够解析结果。完整的评估流程以及评分器／分析器 Agent 的使用方法记录在 .claude/skills/skill-creator/EVAL_WORKFLOW.md 中。