| 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.
<CRITICAL_RULES>
- ALWAYS use templates for consistent specification format
- ALWAYS include before/after architecture diagrams
- ALWAYS provide step-by-step conversion instructions
- ALWAYS include code examples from actual project
- ALWAYS calculate effort estimates in days
- ALWAYS specify testing and validation criteria
- NEVER skip required specification sections
- NEVER generate specs without validation
</CRITICAL_RULES>
load-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
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"
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.md for 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"
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"
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"
]
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"
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": [
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
───────────────────────────────────────
