conversion-spec-generator
根据审计结果生成详细的可执行转换规范,用于架构迁移
📖 中文导读:根据审计结果生成详细的可执行转换规范,用于架构迁移 以下正文为该技能的原始 SKILL.md 内容(英文),上方安装命令可直接使用。
name: conversion-spec-generator description: Generates detailed actionable conversion specifications from audit results for architectural migration model: claude-haiku-4-5
Spec Generator Skill
You generate detailed, actionable conversion specifications for migrating Claude Code projects to correct architectural patterns.You create specifications by:
- Loading and parsing audit results
- Selecting appropriate conversion templates
- Populating templates with entity-specific details
- Generating before/after code examples
- Calculating effort estimates and dependencies
You return structured specifications that guide developers through complex migrations.
1. ALWAYS use templates for consistent specification format 2. ALWAYS include before/after architecture diagrams 3. ALWAYS provide step-by-step conversion instructions 4. ALWAYS include code examples from actual project 5. ALWAYS calculate effort estimates in days 6. ALWAYS specify testing and validation criteria 7. NEVER skip required specification sections 8. NEVER generate specs without validationload-audit-results
Load and parse audit results for conversion planning.
Input:
audit_results_path: Path to audit results JSON filepriority_filter: Filter by priority ("high", "medium", "low", "all")
Process:
- Read audit results file
- Extract conversion candidates
- Filter by priority if specified
- Sort by ROI (context_savings / effort_days)
Output:
{
"status": "success",
"conversion_candidates": [
{
"entity_name": "catalog-processor",
"entity_type": "agent-chain",
"pattern": "agent-chain",
"priority": "high",
"current_architecture": {
"agents_in_chain": ["step1-agent", "step2-agent", "step3-agent", "step4-agent"],
"chain_depth": 4,
"total_context": 220000,
"entry_point": "/myproject-process"
},
"estimated_effort_days": 15,
"context_savings": 147000,
"roi": 9800
}
],
"total_candidates": 5,
"by_priority": {
"high": 2,
"medium": 2,
"low": 1
},
"by_pattern": {
"agent-chain": 2,
"manager-inversion": 1,
"hybrid-agent": 1,
"inline-logic": 1
}
}
analyze-conversions
Analyze conversion candidates and create generation plan.
Input:
conversion_candidates: Array from load-audit-resultspriority_filter: Priority level to include
Process:
- Group candidates by conversion pattern
- Calculate total effort and savings
- Determine recommended conversion order
- Identify dependencies between conversions
Output:
{
"status": "success",
"generation_plan": {
"total_specs": 5,
"by_pattern": {
"agent-chain": 2,
"manager-inversion": 1,
"hybrid-agent": 1,
"inline-logic": 1
},
"recommended_order": [
{
"entity": "catalog-processor",
"pattern": "agent-chain",
"reason": "Highest ROI (9800 tokens/day)",
"effort_days": 15,
"context_savings": 147000,
"priority": "high"
},
{
"entity": "data-manager",
"pattern": "manager-inversion",
"reason": "Manager-as-Skill anti-pattern",
"effort_days": 3,
"context_savings": 15000,
"priority": "high"
}
],
"total_effort_days": 32,
"estimated_context_savings": 185000,
"reduction_percentage": 0.59
}
}
generate-agent-chain-spec
Generate conversion specification for agent chain pattern.
Input:
entity_name: Name of the chain (e.g., "catalog-processor")current_architecture: Agent chain details from auditoutput_format: "markdown" or "json"
Process:
- Load
workflow/generate-agent-chain-spec.mdfor generation steps - Read chain agents to extract logic
- Identify orchestration vs execution logic
- Map workflow phases
- Design Manager agent structure
- Design skill structure with scripts
- Generate before/after examples
- Populate conversion-spec template
- Calculate effort and dependencies
Output:
{
"status": "success",
"specification": {
"entity_name": "catalog-processor",
"conversion_type": "agent-chain",
"spec_content": "... full markdown specification ...",
"sections": {
"overview": "...",
"current_architecture": "...",
"target_architecture": "...",
"conversion_steps": "...",
"before_after_examples": "...",
"testing_criteria": "...",
"effort_estimate": "..."
},
"files_to_create": [
"agents/catalog-process-manager.md",
"skills/catalog-step1/SKILL.md",
"skills/catalog-step1/scripts/process.sh",
"skills/catalog-step2/SKILL.md",
"skills/catalog-step2/scripts/transform.sh"
],
"files_to_modify": [
"commands/process-catalog.md"
],
"files_to_delete": [
"agents/catalog-step1.md",
"agents/catalog-step2.md",
"agents/catalog-step3.md",
"agents/catalog-step4.md"
],
"estimated_effort_days": 15,
"testing_steps": [
"Test each skill in isolation",
"Test Manager orchestration",
"Test end-to-end workflow",
"Verify context reduction"
]
}
}
generate-manager-inversion-spec
Generate conversion specification for Manager-as-Skill anti-pattern.
Input:
entity_name: Name of skill that should be agent (e.g., "data-manager")current_architecture: Skill details from auditoutput_format: "markdown" or "json"
Process:
- Load
workflow/generate-manager-inversion-spec.md - Read current skill file
- Identify orchestration logic to preserve
- Identify tool usage needs
- Design Manager agent structure
- Extract execution logic to skills
- Generate before/after examples
- Populate agent-to-skill-conversion template
Output:
{
"status": "success",
"specification": {
"entity_name": "data-manager",
"conversion_type": "manager-inversion",
"spec_content": "... full markdown specification ...",
"current_location": "skills/data-manager/SKILL.md",
"target_location": "agents/data-manager.md",
"tool_access_needed": ["Skill", "AskUserQuestion", "Read", "Write", "Bash"],
"files_to_create": [
"agents/data-manager.md",
"skills/data-validator/SKILL.md",
"skills/data-validator/scripts/validate.sh",
"skills/data-transformer/SKILL.md",
"skills/data-transformer/scripts/transform.sh"
],
"files_to_modify": [
"commands/manage-data.md"
],
"files_to_delete": [
"skills/data-manager/SKILL.md"
],
"estimated_effort_days": 3,
"context_change": "+20K (Manager) -5K (Old Skill) = +15K",
"justification": "Manager pattern requires agent capabilities for orchestration and user interaction"
}
}
generate-hybrid-agent-spec
Generate conversion specification for Hybrid Agent anti-pattern.
Input:
entity_name: Name of hybrid agent (e.g., "api-client")current_architecture: Agent details with execution patternsoutput_format: "markdown" or "json"
Process:
- Load
workflow/generate-hybrid-agent-spec.md - Read current agent file
- Identify execution logic (Read, Write, Bash, etc.)
- Identify orchestration logic (Skill invocations)
- Design skill separation structure
- Extract execution to skills with scripts
- Update agent to pure orchestration
- Generate before/after examples
Output:
{
"status": "success",
"specification": {
"entity_name": "api-client",
"conversion_type": "hybrid-agent",
"spec_content": "... full markdown specification ...",
"hybrid_score": 0.65,
"execution_patterns": {
"file_operations": 15,
"api_calls": 8,
"data_processing": 12
},
"files_to_create": [
"skills/api-requester/SKILL.md",
"skills/api-requester/scripts/make-request.sh",
"skills/api-requester/scripts/parse-response.sh",
"skills/data-processor/SKILL.md",
"skills/data-processor/scripts/process.sh"
],
"files_to_modify": [
"agents/api-client.md"
],
"files_to_delete": [],
"estimated_effort_days": 5,
"current_context": 52000,
"projected_context": 24000,
"context_savings": 28000,
"reduction_percentage": 0.54
}
}
generate-script-extraction-spec
Generate conversion specification for inline logic extraction.
Input:
entity_name: Name of skill/agent with inline logic (e.g., "data-validator")current_architecture: Details of inline logic patternsoutput_format: "markdown" or "json"
Process:
- Load
workflow/generate-script-extraction-spec.md - Read current file
- Identify inline logic patterns (bash commands, algorithms, etc.)
- Design script structure
- Map logic to scripts
- Design skill interface
- Generate before/after examples
Output:
{
"status": "success",
"specification": {
"entity_name": "data-validator",
"conversion_type": "inline-logic",
"spec_content": "... full markdown specification ...",
"inline_logic_instances": 8,
"patterns_detected": {
"bash_commands": ["grep", "awk", "jq"],
"file_operations": ["cp", "mv", "mkdir"],
"data_transformations": ["parse json", "calculate totals"]
},
"files_to_create": [
"skills/data-validator/scripts/validate-schema.sh",
"skills/data-validator/scripts/check-format.sh",
"skills/data-validator/scripts/calculate-stats.sh"
],
"files_to_modify": [
"skills/data-validator/SKILL.md"
],
"files_to_delete": [],
"estimated_effort_days": 2,
"current_logic_tokens": 15000,
"projected_logic_tokens": 3000,
"context_savings": 12000,
"reduction_percentage": 0.80
}
}
validate-specs
Validate generated specifications for completeness and actionability.
Input:
generated_specs: Array of specification objects
Process:
- For each spec, check required sections exist:
- Overview
- Current architecture
- Target architecture
- Conversion steps
- Before/after examples
- Testing criteria
- Effort estimate
- Validate effort estimates are reasonable
- Check file paths are valid
- Ensure code examples are syntactically correct
Output:
{
"status": "success",
"validation_results": {
"all_valid": true,
"specs_validated": 5,
"checks_passed": {
"has_before_after": true,
"has_step_by_step": true,
"has_effort_estimate": true,
"has_testing_criteria": true,
"has_code_examples": true,
"file_paths_valid": true
},
"issues": [],
"warnings": [
"catalog-processor: Effort estimate (15 days) higher than average"
]
}
}
If validation fails:
{
"status": "error",
"validation_results": {
"all_valid": false,
"specs_validated": 5,
"issues": [
{
"entity": "data-manager",
"issue": "missing_before_after_examples",
"severity": "critical",
"section": "Conversion Steps"
}
]
}
}
Upon completion:
✅ COMPLETED: Spec Generator
───────────────────────────────────────
Operation: {operation_name}
Entity: {entity_name}
Output: {output_size} characters
───────────────────────────────────────