mirror of
https://github.com/catlog22/Claude-Code-Workflow.git
synced 2026-02-15 02:42:45 +08:00
b791c09476
- Create specs/reference-docs-spec.md with comprehensive guidelines for phase-based reference document organization - Update skill-generator's Mandatory Prerequisites to include new reference-docs-spec - Refactor skill-md.md template to generate phase-based reference tables with 'When to Use' guidance - Add generateReferenceTable() function to automatically create structured reference sections - Replace flat template reference lists with phase-based navigation - Update skill-generator's own SKILL.md to demonstrate correct reference documentation pattern - Ensure all generated skills will have clear document usage timing and context
326 lines
11 KiB
Markdown
326 lines
11 KiB
Markdown
# SKILL.md Template
|
||
|
||
用于生成新 Skill 入口文件的模板。
|
||
|
||
## Purpose
|
||
|
||
生成新 Skill 的入口文件 (SKILL.md)，作为 Skill 的主文档和执行入口点。
|
||
|
||
## Usage Context
|
||
|
||
| Phase | Usage |
|
||
|-------|-------|
|
||
| Phase 2 (Structure Generation) | 创建 SKILL.md 入口文件 |
|
||
| Generation Trigger | `config.execution_mode` 决定架构图样式 |
|
||
| Output Location | `.claude/skills/{skill-name}/SKILL.md` |
|
||
|
||
---
|
||
|
||
## ⚠️ 重要：YAML Front Matter 规范
|
||
|
||
> **CRITICAL**: SKILL.md 文件必须以 YAML front matter 开头，即以 `---` 作为文件第一行。
|
||
>
|
||
> **禁止**使用以下格式：
|
||
> - `# Title` 然后 `## Metadata` + yaml 代码块 ❌
|
||
> - 任何在 `---` 之前的内容 ❌
|
||
>
|
||
> **正确格式**：文件第一行必须是 `---`
|
||
|
||
## 可直接应用的模板
|
||
|
||
以下是完整的 SKILL.md 模板。生成时**直接复制应用**，将 `{{变量}}` 替换为实际值：
|
||
|
||
---
|
||
name: {{skill_name}}
|
||
description: {{description}}. Triggers on {{triggers}}.
|
||
allowed-tools: {{allowed_tools}}
|
||
---
|
||
|
||
# {{display_name}}
|
||
|
||
{{description}}
|
||
|
||
## Architecture Overview
|
||
|
||
\`\`\`
|
||
{{architecture_diagram}}
|
||
\`\`\`
|
||
|
||
## Key Design Principles
|
||
|
||
{{design_principles}}
|
||
|
||
---
|
||
|
||
## ⚠️ Mandatory Prerequisites (强制前置条件)
|
||
|
||
> **⛔ 禁止跳过**: 在执行任何操作之前，**必须**完整阅读以下文档。未阅读规范直接执行将导致输出不符合质量标准。
|
||
|
||
{{mandatory_prerequisites}}
|
||
|
||
---
|
||
|
||
## Execution Flow
|
||
|
||
{{execution_flow}}
|
||
|
||
## Directory Setup
|
||
|
||
\`\`\`javascript
|
||
const timestamp = new Date().toISOString().slice(0,19).replace(/[-:T]/g, '');
|
||
const workDir = \`{{output_location}}\`;
|
||
|
||
Bash(\`mkdir -p "\${workDir}"\`);
|
||
{{additional_dirs}}
|
||
\`\`\`
|
||
|
||
## Output Structure
|
||
|
||
\`\`\`
|
||
{{output_structure}}
|
||
\`\`\`
|
||
|
||
## Reference Documents by Phase
|
||
|
||
> **重要**: 参考文档应按执行阶段组织，清晰标注使用时机和场景。避免平铺文档列表。
|
||
|
||
{{reference_table}}
|
||
|
||
---
|
||
|
||
## 变量说明
|
||
|
||
| 变量 | 类型 | 来源 |
|
||
|------|------|------|
|
||
| `{{skill_name}}` | string | config.skill_name |
|
||
| `{{display_name}}` | string | config.display_name |
|
||
| `{{description}}` | string | config.description |
|
||
| `{{triggers}}` | string | config.triggers.join(", ") |
|
||
| `{{allowed_tools}}` | string | config.allowed_tools.join(", ") |
|
||
| `{{architecture_diagram}}` | string | 根据 execution_mode 生成 (包含 Phase 0) |
|
||
| `{{design_principles}}` | string | 根据 execution_mode 生成 |
|
||
| `{{mandatory_prerequisites}}` | string | 强制前置阅读文档列表 (specs + templates) |
|
||
| `{{execution_flow}}` | string | 根据 phases/actions 生成 (Phase 0 在最前) |
|
||
| `{{output_location}}` | string | config.output.location |
|
||
| `{{additional_dirs}}` | string | 根据 execution_mode 生成 |
|
||
| `{{output_structure}}` | string | 根据配置生成 |
|
||
| `{{reference_table}}` | string | 根据文件列表生成 |
|
||
|
||
## 生成函数
|
||
|
||
```javascript
|
||
function generateSkillMd(config) {
|
||
const template = Read('templates/skill-md.md');
|
||
|
||
return template
|
||
.replace(/\{\{skill_name\}\}/g, config.skill_name)
|
||
.replace(/\{\{display_name\}\}/g, config.display_name)
|
||
.replace(/\{\{description\}\}/g, config.description)
|
||
.replace(/\{\{triggers\}\}/g, config.triggers.map(t => `"${t}"`).join(", "))
|
||
.replace(/\{\{allowed_tools\}\}/g, config.allowed_tools.join(", "))
|
||
.replace(/\{\{architecture_diagram\}\}/g, generateArchitecture(config)) // 包含 Phase 0
|
||
.replace(/\{\{design_principles\}\}/g, generatePrinciples(config))
|
||
.replace(/\{\{mandatory_prerequisites\}\}/g, generatePrerequisites(config)) // 强制前置条件
|
||
.replace(/\{\{execution_flow\}\}/g, generateFlow(config)) // Phase 0 在最前
|
||
.replace(/\{\{output_location\}\}/g, config.output.location)
|
||
.replace(/\{\{additional_dirs\}\}/g, generateAdditionalDirs(config))
|
||
.replace(/\{\{output_structure\}\}/g, generateOutputStructure(config))
|
||
.replace(/\{\{reference_table\}\}/g, generateReferenceTable(config));
|
||
}
|
||
|
||
// 生成强制前置条件表格
|
||
function generatePrerequisites(config) {
|
||
const specs = config.specs || [];
|
||
const templates = config.templates || [];
|
||
|
||
let result = '### 规范文档 (必读)\n\n';
|
||
result += '| Document | Purpose | When |\n';
|
||
result += '|----------|---------|------|\n';
|
||
|
||
specs.forEach((spec, index) => {
|
||
const when = index === 0 ? '**执行前必读**' : '执行前推荐';
|
||
result += `| [${spec.path}](${spec.path}) | ${spec.purpose} | ${when} |\n`;
|
||
});
|
||
|
||
if (templates.length > 0) {
|
||
result += '\n### 模板文件 (生成前必读)\n\n';
|
||
result += '| Document | Purpose |\n';
|
||
result += '|----------|---------|\n';
|
||
templates.forEach(tmpl => {
|
||
result += `| [${tmpl.path}](${tmpl.path}) | ${tmpl.purpose} |\n`;
|
||
});
|
||
}
|
||
|
||
return result;
|
||
}
|
||
|
||
// ⭐ 新增：生成分阶段参考文档指南
|
||
function generateReferenceTable(config) {
|
||
const phases = config.phases || config.actions || [];
|
||
const specs = config.specs || [];
|
||
const templates = config.templates || [];
|
||
|
||
let result = '';
|
||
|
||
// 为每个执行阶段生成文档导航
|
||
phases.forEach((phase, index) => {
|
||
const phaseNum = index + 1;
|
||
const phaseEmoji = getPhaseEmoji(phase.type || 'default');
|
||
const phaseTitle = phase.display_name || phase.name;
|
||
|
||
result += `### ${phaseEmoji} Phase ${phaseNum}: ${phaseTitle}\n`;
|
||
result += `执行Phase ${phaseNum}时查阅的文档\n\n`;
|
||
|
||
// 列出该阶段相关的文档
|
||
const relatedDocs = filterDocsByPhase(specs, phase, index);
|
||
if (relatedDocs.length > 0) {
|
||
result += '| Document | Purpose | When to Use |\n';
|
||
result += '|----------|---------|-------------|\n';
|
||
relatedDocs.forEach(doc => {
|
||
result += `| [${doc.path}](${doc.path}) | ${doc.purpose} | ${doc.context || '查阅内容'} |\n`;
|
||
});
|
||
result += '\n';
|
||
}
|
||
});
|
||
|
||
// 问题排查部分
|
||
result += '### 🔍 Debugging & Troubleshooting (问题排查)\n';
|
||
result += '遇到问题时查阅的文档\n\n';
|
||
result += '| Issue | Solution Document |\n';
|
||
result += '|-------|-------------------|\n';
|
||
result += `| Phase执行失败 | 查阅相应Phase的文档 |\n`;
|
||
result += `| 输出不符合预期 | [specs/quality-standards.md](specs/quality-standards.md) - 验证质量标准 |\n`;
|
||
result += '\n';
|
||
|
||
// 深度学习参考
|
||
result += '### 📚 Reference & Background (深度学习)\n';
|
||
result += '用于理解原始实现和设计决策\n\n';
|
||
result += '| Document | Purpose | Notes |\n';
|
||
result += '|----------|---------|-------|\n';
|
||
templates.forEach(tmpl => {
|
||
result += `| [${tmpl.path}](${tmpl.path}) | ${tmpl.purpose} | 生成时参考 |\n`;
|
||
});
|
||
|
||
return result;
|
||
}
|
||
|
||
// 辅助函数：获取Phase表情符号
|
||
function getPhaseEmoji(phaseType) {
|
||
const emojiMap = {
|
||
'discovery': '📋',
|
||
'generation': '🔧',
|
||
'analysis': '🔍',
|
||
'implementation': '⚙️',
|
||
'validation': '✅',
|
||
'completion': '🏁',
|
||
'default': '📌'
|
||
};
|
||
return emojiMap[phaseType] || emojiMap['default'];
|
||
}
|
||
|
||
// 辅助函数：根据Phase过滤文档
|
||
function filterDocsByPhase(specs, phase, phaseIndex) {
|
||
// 简单过滤逻辑：匹配phase名称关键词
|
||
const keywords = phase.name.toLowerCase().split('-');
|
||
return specs.filter(spec => {
|
||
const specName = spec.path.toLowerCase();
|
||
return keywords.some(kw => specName.includes(kw));
|
||
});
|
||
}
|
||
```
|
||
|
||
## Sequential 模式示例
|
||
|
||
```markdown
|
||
---
|
||
name: api-docs-generator
|
||
description: Generate API documentation from source code. Triggers on "generate api docs", "api documentation".
|
||
allowed-tools: Task, Read, Write, Glob, Grep, Bash
|
||
---
|
||
|
||
# API Docs Generator
|
||
|
||
Generate API documentation from source code.
|
||
|
||
## Architecture Overview
|
||
|
||
\`\`\`
|
||
┌─────────────────────────────────────────────────────────────────┐
|
||
│ ⚠️ Phase 0: Specification → 阅读并理解设计规范 (强制前置) │
|
||
│ Study │
|
||
│ ↓ │
|
||
│ Phase 1: Scanning → endpoints.json │
|
||
│ ↓ │
|
||
│ Phase 2: Parsing → schemas.json │
|
||
│ ↓ │
|
||
│ Phase 3: Generation → api-docs.md │
|
||
└─────────────────────────────────────────────────────────────────┘
|
||
\`\`\`
|
||
|
||
## ⚠️ Mandatory Prerequisites (强制前置条件)
|
||
|
||
> **⛔ 禁止跳过**: 在执行任何操作之前，**必须**完整阅读以下文档。
|
||
|
||
### 规范文档 (必读)
|
||
|
||
| Document | Purpose | Priority |
|
||
|----------|---------|----------|
|
||
| [specs/api-standards.md](specs/api-standards.md) | API 文档标准规范 | **P0 - 最高** |
|
||
|
||
### 模板文件 (生成前必读)
|
||
|
||
| Document | Purpose |
|
||
|----------|---------|
|
||
| [templates/endpoint-doc.md](templates/endpoint-doc.md) | 端点文档模板 |
|
||
```
|
||
|
||
## Autonomous 模式示例
|
||
|
||
```markdown
|
||
---
|
||
name: task-manager
|
||
description: Interactive task management with CRUD operations. Triggers on "manage tasks", "task list".
|
||
allowed-tools: Task, AskUserQuestion, Read, Write
|
||
---
|
||
|
||
# Task Manager
|
||
|
||
Interactive task management with CRUD operations.
|
||
|
||
## Architecture Overview
|
||
|
||
\`\`\`
|
||
┌─────────────────────────────────────────────────────────────────┐
|
||
│ ⚠️ Phase 0: Specification Study (强制前置) │
|
||
└───────────────┬─────────────────────────────────────────────────┘
|
||
↓
|
||
┌─────────────────────────────────────────────────────────────────┐
|
||
│ Orchestrator (状态驱动决策) │
|
||
└───────────────┬─────────────────────────────────────────────────┘
|
||
│
|
||
┌───────────┼───────────┬───────────┐
|
||
↓ ↓ ↓ ↓
|
||
┌───────┐ ┌───────┐ ┌───────┐ ┌───────┐
|
||
│ List │ │Create │ │ Edit │ │Delete │
|
||
└───────┘ └───────┘ └───────┘ └───────┘
|
||
\`\`\`
|
||
|
||
## ⚠️ Mandatory Prerequisites (强制前置条件)
|
||
|
||
> **⛔ 禁止跳过**: 在执行任何操作之前，**必须**完整阅读以下文档。
|
||
|
||
### 规范文档 (必读)
|
||
|
||
| Document | Purpose | Priority |
|
||
|----------|---------|----------|
|
||
| [specs/task-schema.md](specs/task-schema.md) | 任务数据结构规范 | **P0 - 最高** |
|
||
| [specs/action-catalog.md](specs/action-catalog.md) | 动作目录 | P1 |
|
||
|
||
### 模板文件 (生成前必读)
|
||
|
||
| Document | Purpose |
|
||
|----------|---------|
|
||
| [templates/orchestrator-base.md](templates/orchestrator-base.md) | 编排器模板 |
|
||
| [templates/action-base.md](templates/action-base.md) | 动作模板 |
|
||
```
|