107 lines
4.8 KiB
Markdown
107 lines
4.8 KiB
Markdown
---
|
|
name: convert-process
|
|
description: Automated skill conversion workflow. Analyzes an existing skill, rebuilds it outcome-driven, and generates a before/after HTML comparison report.
|
|
---
|
|
|
|
**Language:** Use `{communication_language}` for all output.
|
|
|
|
# Convert Process
|
|
|
|
Convert any existing skill into a BMad-compliant, outcome-driven equivalent. Whether the input is bloated, poorly structured, or simply non-conformant, this process extracts intent, rebuilds following BMad best practices, and produces a before/after comparison report.
|
|
|
|
This process is always headless — no interactive questions. The original skill provides all the context needed.
|
|
|
|
## Step 1: Capture the Original
|
|
|
|
1. **Fetch/read the original skill.** If a URL was provided, fetch the raw content. If a local path, read all files in the skill directory.
|
|
|
|
2. **Save the original.** Write the complete original content to `{bmad_builder_reports}/convert-{skill-name}/original/SKILL.md` (and any additional files if the original is a multi-file skill). This preserved copy is needed for the comparison script.
|
|
|
|
3. **Note the source** (URL or path) for the report metadata.
|
|
|
|
## Step 2: Rebuild from Intent
|
|
|
|
Load and follow `build-process.md` with these parameters pre-set:
|
|
|
|
- **Intent:** Rebuild — rethink from core outcomes, the original is reference material only
|
|
- **Headless mode:** Active — skip all interactive questions, use sensible defaults
|
|
- **Discovery questions:** Answer them yourself by analyzing the original skill's intent
|
|
- **Classification:** Determine from the original's structure and purpose
|
|
- **Requirements:** Derive from the original, applying aggressive pruning
|
|
|
|
**Critical:** Do not inherit the original's verbosity, structure, or mechanical procedures. Extract *what it achieves*, then build the leanest skill that delivers the same outcome.
|
|
|
|
When the build process reaches Phase 6 (Summary), skip the quality analysis offer and continue to Step 3 below.
|
|
|
|
## Step 3: Generate Comparison Report
|
|
|
|
After the rebuilt skill is complete:
|
|
|
|
1. **Create the analysis file.** Write `{bmad_builder_reports}/convert-{skill-name}/convert-analysis.json`:
|
|
|
|
```json
|
|
{
|
|
"skill_name": "{skill-name}",
|
|
"original_source": "{url-or-path-provided-by-user}",
|
|
"cuts": [
|
|
{
|
|
"category": "Category Name",
|
|
"description": "Why this content was cut",
|
|
"examples": ["Specific example 1", "Specific example 2"],
|
|
"severity": "high|medium|low"
|
|
}
|
|
],
|
|
"retained": [
|
|
{
|
|
"category": "Category Name",
|
|
"description": "Why this content was kept — what behavioral impact it has"
|
|
}
|
|
],
|
|
"verdict": "One sharp sentence summarizing the conversion"
|
|
}
|
|
```
|
|
|
|
### Categorizing Changes
|
|
|
|
Not every conversion is about bloat — some skills are well-intentioned but non-conformant. Categorize what changed and why, drawing from these common patterns:
|
|
|
|
**Content removal** (when applicable):
|
|
|
|
| Category | Signal |
|
|
|----------|--------|
|
|
| **Training Data Redundancy** | Facts, biographies, domain knowledge the LLM already has |
|
|
| **Prescriptive Procedures** | Step-by-step instructions for things the LLM reasons through naturally |
|
|
| **Mechanical Frameworks** | Scoring rubrics, decision matrices, evaluation checklists for subjective judgment |
|
|
| **Generic Boilerplate** | "Best Practices", "Common Pitfalls", "When to Use/Not Use" filler |
|
|
| **Template Bloat** | Response format templates, greeting scripts, output structure prescriptions |
|
|
| **Redundant Examples** | Examples that repeat what the instructions already say |
|
|
| **Per-Platform Duplication** | Separate instructions per platform when one adaptive instruction works |
|
|
|
|
**Structural changes** (conformance to BMad best practices):
|
|
|
|
| Category | Signal |
|
|
|----------|--------|
|
|
| **Progressive Disclosure** | Monolithic content split into SKILL.md routing + references |
|
|
| **Outcome-Driven Rewrite** | Prescriptive instructions reframed as outcomes |
|
|
| **Frontmatter/Description** | Added or fixed BMad-compliant frontmatter and trigger phrases |
|
|
| **Path Convention Fixes** | Corrected file references to use `./` for skill-internal, `{project-root}/` for project-scope |
|
|
|
|
Severity: **high** = significant impact on quality or compliance, **medium** = notable improvement, **low** = minor or stylistic.
|
|
|
|
### Categorizing Retained Content
|
|
|
|
Focus on what the LLM *wouldn't* do correctly without being told. The retained categories should explain why each piece earns its place.
|
|
|
|
2. **Generate the HTML report:**
|
|
|
|
```bash
|
|
python3 ./scripts/generate-convert-report.py \
|
|
"{bmad_builder_reports}/convert-{skill-name}/original" \
|
|
"{rebuilt-skill-path}" \
|
|
"{bmad_builder_reports}/convert-{skill-name}/convert-analysis.json" \
|
|
-o "{bmad_builder_reports}/convert-{skill-name}/convert-report.html" \
|
|
--open
|
|
```
|
|
|
|
3. **Present the summary** — key metrics, reduction percentages, report file location. The HTML report opens automatically.
|