mirror of
https://github.com/catlog22/Claude-Code-Workflow.git
synced 2026-02-13 02:41:50 +08:00
Enhance skill generator documentation and templates
- Updated Phase 1 and Phase 2 documentation to include next phase links and data flow details. - Expanded Phase 5 documentation to include comprehensive validation and README generation steps, along with validation report structure. - Added purpose and usage context sections to various action and script templates (e.g., autonomous-action, llm-action, script-bash). - Improved commands management by simplifying the command scanning logic and enabling/disabling commands through renaming files. - Enhanced dashboard command manager to format group names and display nested groups with appropriate icons and colors. - Updated LiteLLM executor to allow model overrides during execution. - Added action reference guide and template reference sections to the skill-tuning SKILL.md for better navigation and understanding.
This commit is contained in:
catlog22
@@ -218,3 +218,11 @@ Write(`${workDir}/skill-config.json`, JSON.stringify(config, null, 2));
|
||||
```
|
||||
|
||||
|
||||
|
||||
## Next Phase
|
||||
|
||||
→ [Phase 2: Structure Generation](02-structure-generation.md)
|
||||
|
||||
**Data Flow to Phase 2**:
|
||||
- skill-config.json with all configuration parameters
|
||||
- Execution mode decision drives directory structure creation
|
||||
|
||||
@@ -191,3 +191,12 @@ function generateReferenceTable(config) {
|
||||
```
|
||||
|
||||
|
||||
|
||||
## Next Phase
|
||||
|
||||
→ [Phase 3: Phase Generation](03-phase-generation.md)
|
||||
|
||||
**Data Flow to Phase 3**:
|
||||
- Complete directory structure in .claude/skills/{skill-name}/
|
||||
- SKILL.md entry file ready for phase/action generation
|
||||
- skill-config.json for template population
|
||||
|
||||
@@ -1,27 +1,119 @@
|
||||
# Phase 5: Validation & Documentation
|
||||
|
||||
验证生成的 Skill 完整性并生成使用说明。
|
||||
Verify generated skill completeness and generate user documentation.
|
||||
|
||||
## Objective
|
||||
|
||||
- 验证所有必需文件存在
|
||||
- 检查文件内容完整性
|
||||
- 生成 README.md 使用说明
|
||||
- 输出验证报告
|
||||
Comprehensive validation and documentation:
|
||||
- Verify all required files exist
|
||||
- Check file content quality and completeness
|
||||
- Generate validation report with issues and recommendations
|
||||
- Generate README.md usage documentation
|
||||
- Output final status and next steps
|
||||
|
||||
## Input
|
||||
|
||||
- 依赖: 所有前序阶段产出
|
||||
- 生成的 Skill 目录
|
||||
**File Dependencies**:
|
||||
- `skill-config.json` (from Phase 1)
|
||||
- `.claude/skills/{skill-name}/` directory (from Phase 2)
|
||||
- All generated phase/action files (from Phase 3)
|
||||
- All generated specs/templates files (from Phase 4)
|
||||
|
||||
## Execution Steps
|
||||
**Required Information**:
|
||||
- Skill name, display name, description
|
||||
- Execution mode
|
||||
- Trigger words
|
||||
- Output configuration
|
||||
- Complete skill directory structure
|
||||
|
||||
### Step 1: 文件完整性检查
|
||||
## Output
|
||||
|
||||
**Generated Files**:
|
||||
|
||||
| File | Purpose | Content |
|
||||
|------|---------|---------|
|
||||
| `validation-report.json` (workDir) | Validation report with detailed checks | File completeness, content quality, issues, recommendations |
|
||||
| `README.md` (skillDir) | User documentation | Quick Start, Usage, Output, Directory Structure, Customization |
|
||||
|
||||
**Validation Report Structure** (`validation-report.json`):
|
||||
```json
|
||||
{
|
||||
"skill_name": "...",
|
||||
"execution_mode": "sequential|autonomous",
|
||||
"generated_at": "ISO timestamp",
|
||||
"file_checks": {
|
||||
"total": N,
|
||||
"existing": N,
|
||||
"with_content": N,
|
||||
"with_todos": N,
|
||||
"details": [...]
|
||||
},
|
||||
"content_checks": {
|
||||
"files_checked": N,
|
||||
"all_passed": true|false,
|
||||
"details": [...]
|
||||
},
|
||||
"summary": {
|
||||
"status": "PASS|REVIEW|FAIL",
|
||||
"issues": [...],
|
||||
"recommendations": [...]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**README Structure** (`README.md`):
|
||||
```markdown
|
||||
# {display_name}
|
||||
- Quick Start (Triggers, Execution Mode)
|
||||
- Usage (Examples)
|
||||
- Output (Format, Location, Filename)
|
||||
- Directory Structure (Tree view)
|
||||
- Customization (How to modify)
|
||||
- Related Documents (Links)
|
||||
```
|
||||
|
||||
**Validation Status Gates**:
|
||||
|
||||
| Status | Condition | Meaning |
|
||||
|--------|-----------|---------|
|
||||
| PASS | All files exist + All content checks passed | Ready for use |
|
||||
| REVIEW | All files exist + Some content checks failed | Needs refinement |
|
||||
| FAIL | Missing files | Incomplete generation |
|
||||
|
||||
## Decision Logic
|
||||
|
||||
```
|
||||
Decision (Validation Flow):
|
||||
├─ File Completeness Check
|
||||
│ ├─ All files exist → Continue to content checks
|
||||
│ └─ Missing files → Status = FAIL, collect missing file errors
|
||||
│
|
||||
├─ Content Quality Check
|
||||
│ ├─ Sequential mode → Check phase files for structure
|
||||
│ ├─ Autonomous mode → Check orchestrator + action files
|
||||
│ └─ Common → Check SKILL.md, specs/, templates/
|
||||
│
|
||||
├─ Status Calculation
|
||||
│ ├─ All files exist + All checks pass → Status = PASS
|
||||
│ ├─ All files exist + Some checks fail → Status = REVIEW
|
||||
│ └─ Missing files → Status = FAIL
|
||||
│
|
||||
└─ Generate Report & README
|
||||
├─ validation-report.json (with issues and recommendations)
|
||||
└─ README.md (with usage documentation)
|
||||
```
|
||||
|
||||
## Execution Protocol
|
||||
|
||||
```javascript
|
||||
// Phase 5: Validation & Documentation
|
||||
// Reference: phases/05-validation.md
|
||||
|
||||
// Load config and setup
|
||||
const config = JSON.parse(Read(`${workDir}/skill-config.json`));
|
||||
const skillDir = `.claude/skills/${config.skill_name}`;
|
||||
|
||||
// Step 1: File completeness check
|
||||
const requiredFiles = {
|
||||
common: [
|
||||
'SKILL.md',
|
||||
@@ -64,14 +156,11 @@ const fileCheckResults = filesToCheck.map(file => {
|
||||
};
|
||||
}
|
||||
});
|
||||
```
|
||||
|
||||
### Step 2: 内容质量检查
|
||||
|
||||
```javascript
|
||||
// Step 2: Content quality check
|
||||
const contentChecks = [];
|
||||
|
||||
// 检查 SKILL.md
|
||||
// Check SKILL.md structure
|
||||
const skillMd = Read(`${skillDir}/SKILL.md`);
|
||||
contentChecks.push({
|
||||
file: 'SKILL.md',
|
||||
@@ -83,11 +172,11 @@ contentChecks.push({
|
||||
]
|
||||
});
|
||||
|
||||
// 检查 Phase 文件
|
||||
// Check phase files
|
||||
const phaseFiles = Glob(`${skillDir}/phases/*.md`);
|
||||
for (const phaseFile of phaseFiles) {
|
||||
if (phaseFile.includes('/actions/')) continue; // 单独检查
|
||||
|
||||
if (phaseFile.includes('/actions/')) continue; // Check separately
|
||||
|
||||
const content = Read(phaseFile);
|
||||
contentChecks.push({
|
||||
file: phaseFile.replace(skillDir + '/', ''),
|
||||
@@ -100,7 +189,7 @@ for (const phaseFile of phaseFiles) {
|
||||
});
|
||||
}
|
||||
|
||||
// 检查 Specs 文件
|
||||
// Check specs files
|
||||
const specFiles = Glob(`${skillDir}/specs/*.md`);
|
||||
for (const specFile of specFiles) {
|
||||
const content = Read(specFile);
|
||||
@@ -113,16 +202,13 @@ for (const specFile of specFiles) {
|
||||
]
|
||||
});
|
||||
}
|
||||
```
|
||||
|
||||
### Step 3: 生成验证报告
|
||||
|
||||
```javascript
|
||||
// Step 3: Generate validation report
|
||||
const report = {
|
||||
skill_name: config.skill_name,
|
||||
execution_mode: config.execution_mode,
|
||||
generated_at: new Date().toISOString(),
|
||||
|
||||
|
||||
file_checks: {
|
||||
total: fileCheckResults.length,
|
||||
existing: fileCheckResults.filter(f => f.exists).length,
|
||||
@@ -130,13 +216,13 @@ const report = {
|
||||
with_todos: fileCheckResults.filter(f => f.hasTodo).length,
|
||||
details: fileCheckResults
|
||||
},
|
||||
|
||||
|
||||
content_checks: {
|
||||
files_checked: contentChecks.length,
|
||||
all_passed: contentChecks.every(c => c.checks.every(ch => ch.pass)),
|
||||
details: contentChecks
|
||||
},
|
||||
|
||||
|
||||
summary: {
|
||||
status: calculateOverallStatus(fileCheckResults, contentChecks),
|
||||
issues: collectIssues(fileCheckResults, contentChecks),
|
||||
@@ -146,10 +232,11 @@ const report = {
|
||||
|
||||
Write(`${workDir}/validation-report.json`, JSON.stringify(report, null, 2));
|
||||
|
||||
// Helper functions
|
||||
function calculateOverallStatus(fileResults, contentResults) {
|
||||
const allFilesExist = fileResults.every(f => f.exists);
|
||||
const allContentPassed = contentResults.every(c => c.checks.every(ch => ch.pass));
|
||||
|
||||
|
||||
if (allFilesExist && allContentPassed) return 'PASS';
|
||||
if (allFilesExist) return 'REVIEW';
|
||||
return 'FAIL';
|
||||
@@ -157,44 +244,41 @@ function calculateOverallStatus(fileResults, contentResults) {
|
||||
|
||||
function collectIssues(fileResults, contentResults) {
|
||||
const issues = [];
|
||||
|
||||
|
||||
fileResults.filter(f => !f.exists).forEach(f => {
|
||||
issues.push({ type: 'ERROR', message: `文件缺失: ${f.file}` });
|
||||
});
|
||||
|
||||
|
||||
fileResults.filter(f => f.hasTodo).forEach(f => {
|
||||
issues.push({ type: 'WARNING', message: `包含 TODO: ${f.file}` });
|
||||
});
|
||||
|
||||
|
||||
contentResults.forEach(c => {
|
||||
c.checks.filter(ch => !ch.pass).forEach(ch => {
|
||||
issues.push({ type: 'WARNING', message: `${c.file}: 缺少 ${ch.name}` });
|
||||
});
|
||||
});
|
||||
|
||||
|
||||
return issues;
|
||||
}
|
||||
|
||||
function generateRecommendations(fileResults, contentResults) {
|
||||
const recommendations = [];
|
||||
|
||||
|
||||
if (fileResults.some(f => f.hasTodo)) {
|
||||
recommendations.push('替换所有 TODO 占位符为实际内容');
|
||||
}
|
||||
|
||||
|
||||
contentResults.forEach(c => {
|
||||
if (c.checks.some(ch => !ch.pass)) {
|
||||
recommendations.push(`完善 ${c.file} 的结构`);
|
||||
}
|
||||
});
|
||||
|
||||
|
||||
return recommendations;
|
||||
}
|
||||
```
|
||||
|
||||
### Step 4: 生成 README.md
|
||||
|
||||
```javascript
|
||||
// Step 4: Generate README.md
|
||||
const readme = `# ${config.display_name}
|
||||
|
||||
${config.description}
|
||||
@@ -210,10 +294,10 @@ ${config.triggers.map(t => `- "${t}"`).join('\n')}
|
||||
**${config.execution_mode === 'sequential' ? 'Sequential (顺序)' : 'Autonomous (自主)'}**
|
||||
|
||||
${config.execution_mode === 'sequential' ?
|
||||
`阶段按固定顺序执行：\n${config.sequential_config.phases.map((p, i) =>
|
||||
`阶段按固定顺序执行：\n${config.sequential_config.phases.map((p, i) =>
|
||||
`${i + 1}. ${p.name}`
|
||||
).join('\n')}` :
|
||||
`动作由编排器动态选择：\n${config.autonomous_config.actions.map(a =>
|
||||
`动作由编排器动态选择：\n${config.autonomous_config.actions.map(a =>
|
||||
`- ${a.name}: ${a.description || ''}`
|
||||
).join('\n')}`}
|
||||
|
||||
@@ -283,24 +367,21 @@ ${config.execution_mode === 'sequential' ?
|
||||
`;
|
||||
|
||||
Write(`${skillDir}/README.md`, readme);
|
||||
```
|
||||
|
||||
### Step 5: 输出最终结果
|
||||
|
||||
```javascript
|
||||
// Step 5: Output final result
|
||||
const finalResult = {
|
||||
skill_name: config.skill_name,
|
||||
skill_path: skillDir,
|
||||
execution_mode: config.execution_mode,
|
||||
|
||||
|
||||
generated_files: [
|
||||
'SKILL.md',
|
||||
'README.md',
|
||||
...filesToCheck
|
||||
],
|
||||
|
||||
|
||||
validation: report.summary,
|
||||
|
||||
|
||||
next_steps: [
|
||||
'1. 审阅生成的文件结构',
|
||||
'2. 替换 TODO 占位符',
|
||||
@@ -319,16 +400,18 @@ console.log('下一步:');
|
||||
finalResult.next_steps.forEach(s => console.log(s));
|
||||
```
|
||||
|
||||
## Output
|
||||
## Workflow Completion
|
||||
|
||||
- `{workDir}/validation-report.json` - 验证报告
|
||||
- `{skillDir}/README.md` - 使用说明
|
||||
**Final Status**: Skill generation pipeline complete
|
||||
|
||||
## Completion
|
||||
**Generated Artifacts**:
|
||||
- Complete skill directory structure in `.claude/skills/{skill-name}/`
|
||||
- Validation report in `{workDir}/validation-report.json`
|
||||
- User documentation in `{skillDir}/README.md`
|
||||
|
||||
Skill 生成流程完成。用户可以：
|
||||
|
||||
1. 查看生成的 Skill 目录
|
||||
2. 根据验证报告修复问题
|
||||
3. 自定义执行逻辑
|
||||
4. 测试 Skill 功能
|
||||
**Next Steps**:
|
||||
1. Review validation report for any issues or recommendations
|
||||
2. Replace TODO placeholders with actual implementation
|
||||
3. Test skill execution with trigger words
|
||||
4. Customize phase logic based on specific requirements
|
||||
5. Update triggers and descriptions as needed
|
||||
|
||||
@@ -2,6 +2,20 @@
|
||||
|
||||
自主模式动作文件的模板。
|
||||
|
||||
## Purpose
|
||||
|
||||
生成 Autonomous 执行模式的 Action 文件，定义可独立执行的动作单元。
|
||||
|
||||
## Usage Context
|
||||
|
||||
| Phase | Usage |
|
||||
|-------|-------|
|
||||
| Phase 3 (Phase Generation) | `config.execution_mode === 'autonomous'` 时生成 |
|
||||
| Generation Trigger | 为每个 `config.autonomous_config.actions` 生成一个 action 文件 |
|
||||
| Output Location | `.claude/skills/{skill-name}/phases/actions/{action-id}.md` |
|
||||
|
||||
---
|
||||
|
||||
## 模板结构
|
||||
|
||||
```markdown
|
||||
|
||||
@@ -2,6 +2,20 @@
|
||||
|
||||
自主模式编排器的模板。
|
||||
|
||||
## Purpose
|
||||
|
||||
生成 Autonomous 执行模式的 Orchestrator 文件，负责状态驱动的动作选择和执行循环。
|
||||
|
||||
## Usage Context
|
||||
|
||||
| Phase | Usage |
|
||||
|-------|-------|
|
||||
| Phase 3 (Phase Generation) | `config.execution_mode === 'autonomous'` 时生成 |
|
||||
| Generation Trigger | 创建编排器逻辑，管理动作选择和状态更新 |
|
||||
| Output Location | `.claude/skills/{skill-name}/phases/orchestrator.md` |
|
||||
|
||||
---
|
||||
|
||||
## ⚠️ 重要提示
|
||||
|
||||
> **Phase 0 是强制前置阶段**：在 Orchestrator 启动执行循环之前，必须先完成 Phase 0 的规范研读。
|
||||
|
||||
@@ -2,6 +2,18 @@
|
||||
|
||||
代码分析动作模板，用于在 Skill 中集成代码探索和分析能力。
|
||||
|
||||
## Purpose
|
||||
|
||||
为 Skill 生成代码分析动作，集成 MCP 工具 (ACE) 和 Agent 进行语义搜索和深度分析。
|
||||
|
||||
## Usage Context
|
||||
|
||||
| Phase | Usage |
|
||||
|-------|-------|
|
||||
| Optional | 当 Skill 需要代码探索和分析能力时使用 |
|
||||
| Generation Trigger | 用户选择添加 code-analysis 动作类型 |
|
||||
| Agent Types | Explore, cli-explore-agent, universal-executor |
|
||||
|
||||
---
|
||||
|
||||
## 配置结构
|
||||
|
||||
@@ -2,6 +2,18 @@
|
||||
|
||||
LLM 动作模板，用于在 Skill 中集成 LLM 调用能力。
|
||||
|
||||
## Purpose
|
||||
|
||||
为 Skill 生成 LLM 动作，通过 CCW CLI 统一接口调用 Gemini/Qwen/Codex 进行分析或生成。
|
||||
|
||||
## Usage Context
|
||||
|
||||
| Phase | Usage |
|
||||
|-------|-------|
|
||||
| Optional | 当 Skill 需要 LLM 能力时使用 |
|
||||
| Generation Trigger | 用户选择添加 llm 动作类型 |
|
||||
| Tools | gemini, qwen, codex (支持 fallback chain) |
|
||||
|
||||
---
|
||||
|
||||
## 配置结构
|
||||
|
||||
@@ -2,6 +2,20 @@
|
||||
|
||||
Bash 脚本模板，用于生成技能中的确定性脚本。
|
||||
|
||||
## Purpose
|
||||
|
||||
为 Skill 生成 Bash 脚本，用于执行确定性操作（文件处理、系统命令、数据转换等）。
|
||||
|
||||
## Usage Context
|
||||
|
||||
| Phase | Usage |
|
||||
|-------|-------|
|
||||
| Optional | Phase/Action 中声明 `## Scripts` 时使用 |
|
||||
| Execution | 通过 `ExecuteScript('script-id', params)` 调用 |
|
||||
| Output Location | `.claude/skills/{skill-name}/scripts/{script-id}.sh` |
|
||||
|
||||
---
|
||||
|
||||
## 模板代码
|
||||
|
||||
```bash
|
||||
|
||||
@@ -2,6 +2,20 @@
|
||||
|
||||
Python 脚本模板，用于生成技能中的确定性脚本。
|
||||
|
||||
## Purpose
|
||||
|
||||
为 Skill 生成 Python 脚本，用于执行确定性操作（数据处理、分析、转换等），比 Bash 提供更强的数据处理能力。
|
||||
|
||||
## Usage Context
|
||||
|
||||
| Phase | Usage |
|
||||
|-------|-------|
|
||||
| Optional | Phase/Action 中声明 `## Scripts` 时使用 |
|
||||
| Execution | 通过 `ExecuteScript('script-id', params)` 调用 |
|
||||
| Output Location | `.claude/skills/{skill-name}/scripts/{script-id}.py` |
|
||||
|
||||
---
|
||||
|
||||
## 模板代码
|
||||
|
||||
```python
|
||||
|
||||
@@ -2,6 +2,20 @@
|
||||
|
||||
顺序模式 Phase 文件的模板。
|
||||
|
||||
## Purpose
|
||||
|
||||
生成 Sequential 执行模式的 Phase 文件，定义固定顺序的执行步骤。
|
||||
|
||||
## Usage Context
|
||||
|
||||
| Phase | Usage |
|
||||
|-------|-------|
|
||||
| Phase 3 (Phase Generation) | `config.execution_mode === 'sequential'` 时生成 |
|
||||
| Generation Trigger | 为每个 `config.sequential_config.phases` 生成一个 phase 文件 |
|
||||
| Output Location | `.claude/skills/{skill-name}/phases/{phase-id}.md` |
|
||||
|
||||
---
|
||||
|
||||
## ⚠️ 重要提示
|
||||
|
||||
> **Phase 0 是强制前置阶段**：在实现任何 Phase (1, 2, 3...) 之前，必须先完成 Phase 0 的规范研读。
|
||||
|
||||
@@ -2,6 +2,20 @@
|
||||
|
||||
用于生成新 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 开头，即以 `---` 作为文件第一行。
|
||||
|
||||
Reference in New Issue
Block a user