--- name: Bundle Builder slug: bundle-builder category: AI Engineering description: Synthesizes workflow bundles from accumulated state, generating structured output directories with umbrella skills, sub-skills, manifests, and decision maps for agent skill scanners. github: "https://github.com/magnus919/agent-skills/tree/main/bundles/workflow-architect/skills/bundle-builder" language: Python stars: 10 forks: 0 install: "git clone https://github.com/magnus919/agent-skills" added: 2026-07-18T04:42:07.452Z last_synced: 2026-07-18T04:42:07.452Z canonical_url: "https://dirskills.com/skills/bundle-builder" --- # Bundle Builder Synthesizes workflow bundles from accumulated state, generating structured output directories with umbrella skills, sub-skills, manifests, and decision maps for agent skill scanners. **Install:** `git clone https://github.com/magnus919/agent-skills` ## README # Bundle Builder — Workflow Synthesis Engine This sub-skill is loaded after the interviewer (active mode) or observer (passive mode) achieves convergence. It reads the accumulated workflow state from memory and generates an output bundle directory. ## Input All `workflow-architect:state:*` memory entries. Read them all at once: ``` Read: workflow-architect:state:entry_points Read: workflow-architect:state:phases Read: workflow-architect:state:branching Read: workflow-architect:state:pain_points Read: workflow-architect:state:exit_criteria ``` If any required fields are missing (entry_points, phases, branching, exit_criteria), abort with a clear message about what's missing. ## Output Structure The bundle is written to `~/.hermes/skills///` with this layout: ``` / ├── SKILL.md # *** UMBRELLA ENTRY POINT *** — makes the bundle │ # loadable via skill_view() and discoverable by │ # the agent's skill scanner on trigger keywords. │ # CRITICAL: without this, the bundle is invisible. ├── README.md # Summary of this bundle ├── manifest.yaml # Skill-to-trigger mapping ├── skills/ │ ├── entry-skill.md # One per discovered phase │ ├── phase-two.md │ └── ... ├── decision-map.md # Mermaid flowchart ├── AGENTS.md # Agent loading instructions for this bundle ├── kanban/ │ └── board-definition.yaml # Only if kanban is appropriate └── references/ └── generated-from.md # Metadata about how this bundle was created ``` **The `SKILL.md` umbrella is not optional.** Without it, individual sub-skills may exist on disk but the agent's skill scanner has no entry point to match trigger keywords against. The umbrella is how the agent discovers and enters the bundle. ### Bundle naming Ask the user for a bundle name at the start of synthesis: ``` "Before I generate the bundle — what should I call it? Something short, lowercase with hyphens, like 'my-triage-workflow' or 'dev-sprint-routine'." ``` Fallback if user doesn't provide one: `my-workflow--`. ### Writing the files For each file in the output bundle, use the shared templates in `../../templates/` as starting points. Render them by substituting the state values. **Step-by-step file creation order:** 0. **Umbrella SKILL.md** — **MANDATORY FIRST STEP.** This is the entry point that makes the bundle discoverable. Write it directly to the bundle directory as `SKILL.md`, then register it via `skill_manage(action='create')`. The umbrella must include: - `name: ` matching the bundle name - `description` with **broad trigger keywords** covering all common ways the user enters this workflow (e.g., "I want to write about X", "I read something interesting", "can you research this", "draft it", "ship it") - `compatibility: Hermes Agent` - `metadata.tags` including `workflow`, `bundle`, and domain-relevant tags Body content: ```markdown # A -phase workflow covering . ## Pipeline → → → ... (Include a Mermaid flowchart graph LR showing the phase sequence.) ## Sub-Skills | Phase | Skill | Trigger | |-------|-------|---------| | | `/` | | | ... | ... | ... | ## Navigation When you load this umbrella, identify which phase the user is in, load the corresponding sub-skill via skill_view(), and follow its instructions. Use the transition signals in each sub-skill to know when to move to the next phase. ## Pipeline Heuristics - Can the user enter at any phase, or must they start at Phase 1? - Are any phases automatic (e.g., refine always follows draft)? - What's the relationship between phases (sequential, branching, optional)? ``` **Category choice:** Place the bundle in a category that matches where its sub-skills live (e.g., `content` for blogging pipelines, `devops` for deployment workflows). Ask the user if unsure. 1. **manifest.yaml** — Use `../../templates/manifest.yaml.tmpl`. Substitute: - `{{BUNDLE_NAME}}` — the bundle name - `{{PHASES}}` — each phase with its trigger keywords, entry signals, typical tools, and exit signals - `{{HAS_KANBAN}}` — true/false based on kanban decision 2. **README.md** — Write from scratch (no template needed, it's prose). Structure: ```markdown # Generated by workflow-architect on . This bundle covers a -style workflow with phases. ## Skills | Skill | Trigger | When it fires | |-------|---------|---------------| | | | | ## Loading Skills in this bundle are loaded automatically by trigger conditions. To load a specific skill: `skill_view(name='/')` ## Kanban (Only if kanban exists) This workflow maps to a kanban board with lanes. ``` 3. **Sub-skills** — For each phase in `workflow-architect:state:phases`, generate a `.md` file in `skills/` using `../../templates/skill-skeleton.md`. Naming convention: `kebab-case-phase-name.md` (e.g., `morning-triage.md`). Each sub-skill file is a valid Agent Skills SKILL.md with: - `name` matching the filename (without .md) - `description` that includes trigger keywords from the phase's typical openers and tools - `compatibility: Compatible with any agent supporting the Agent Skills format` - Body sections: - **When to use** — the trigger condition in natural language - **What to do** — step-by-step instructions for the agent in this phase - **Transition signals** — what the user typically says or does that transitions out of this phase - **What to tell the user** — guidance on how the agent should communicate during this phase 4. **decision-map.md** — Use `../../templates/decision-map.md.tmpl`. Substitute: - `{{WORKFLOW_NAME}}` — bundle name - `{{PHASE_NODES}}` — phase names - `{{BRANCHING}}` — decision diamonds - `{{ENTRY}}` — how sessions start - `{{EXITS}}` — how sessions end 5. **AGENTS.md** — Standard agent loading instructions for this bundle. Short — just says which skills exist and when to load them. 6. **kanban/ directory** — Only if the kanban-decision-criteria.md reference indicates kanban is appropriate. Generates three files: a) **kanban/board-setup.sh** — Use `../../templates/kanban-board-setup.sh.tmpl`. Substitutes: - `{{BOARD_SLUG}}` — bundle name (kebab-case) - `{{BOARD_NAME}}` — title-case version or user-provided name - `{{FIRST_PHASE_SKILL}}` — skill file for the first phase - `{{FIRST_PHASE_PRIORITY}}` — priority for first-phase tasks - `{{GENERATION_DATE}}` — current date The setup script creates the board via `hermes kanban boards create` and prints instructions for adding work. b) **kanban/task-blueprints.yaml** — Use `../../templates/kanban-task-blueprints.yaml.tmpl`. Substitutes: - `{{BLUEPRINT_ENTRIES}}` — one blueprint entry per phase, each with: - `phase:` — phase name (kebab-case) - `title_template:` — e.g. "Build: {{feature}}" - `skill:` — path to the sub-skill file (e.g. `my-workflow/build`) - `default_priority:` — descending from first phase (highest) to last - `initial_status:` — first phase = `todo`, rest = `ready` - `body:` — instructions for the worker: what skill to load, definition of done, and transition to next phase c) **kanban/README.md** — Brief usage guide explaining how to set up and use the board. Structure: ```markdown # Kanban Board: This workflow maps to a Hermes Kanban board with phases in sequence. ## Setup Run `kanban/board-setup.sh` to create the board: ```bash bash kanban/board-setup.sh ``` The script creates the board and switches to it. If you prefer to set it up manually: ```bash hermes kanban boards create --name "" ``` ## Task Lifecycle → → Each phase's task depends on the previous phase's task completing. When a task is done, the next phase's task auto-promotes to "ready" and the dispatcher picks it up. ## Adding Work Create a task for the first phase: ```bash hermes kanban create "Build: " \\ --skill / \\ --priority 3 ``` Then create subsequent-phase tasks with `--parent` pointing to the first task's ID: ```bash hermes kanban create "Review: " \\ --parent \\ --skill / \\ --priority 2 ``` ## Task Blueprints See `kanban/task-blueprints.yaml` for template definitions of each phase's task, including default priorities, skill mappings, and worker instructions. ``` 7. **references/generated-from.md** — Metadata about the generation process: ```markdown # Generated From - **Skill:** workflow-architect - **Mode:** active | passive - **Date:** - **Archetype:** - **Convergence Score:** ``` 8. **Register sub-skills with Hermes skill system** — For each sub-skill `.md` file written in step 3, register it so it appears in `skills_list()` and can be loaded with `skill_view()`. This is the critical step that makes generated skills actually usable by the agent. For each sub-skill file in `skills/.md`: ```python skill_manage(action='create', name='-', content=read_file('/skills/.md')['content'], category='generated') ``` This creates a proper skill directory with `SKILL.md` entry point, making the sub-skill discoverable and loadable. The sub-skill's existing valid Agent Skills frontmatter (name, description, license, tags) is used as-is. **Why separate registration is needed:** The `skill_manage()` call also handles the skill directory structure (`SKILL.md` at root, not `.md` in a `skills/` subdirectory). Without this step, the sub-skill files exist on disk but no Hermes mechanism discovers them. Only the umbrella SKILL.md (registered in step 0) would be loadable. **Verification:** After registering all sub-skills, verify at least one: ```python skill_view(name='-') ``` If it errors, the registration failed — check that the sub-skill file's frontmatter `name` field matches and the content has valid YAML. ## Kanban Decision Before generating kanban files, consult `../../references/kanban-decision-criteria.md` to decide whether a board is appropriate. The decision depends on the phases and branching structure discovered: - If phases form a clear linear sequence (A → B → C → D), kanban adds value - If branching is emergent (session depends on context), kanban is likely inappropriate - If the user mentioned waiting on others, hand-offs, or status tracking, kanban is a strong fit Present the decision to the user: ``` "Your workflow has a [linear/emergent] structure. A kanban board [would/wouldn't] add much value here because [reason]. [If yes: I'll add one to the bundle.]" ``` 8. **Register sub-skills** — For each generated sub-skill `.md` file in `skills/`, register it so Hermes can discover it via `skill_view()` and `skills_list()`: ``` For each sub-skill file `skills/.md`: Read the file content skill_manage( action='create', name='/', content=file_content ) ``` This makes each sub-skill loadable as `skill_view('/')`. The bundle name prefix prevents naming collisions with other skills. If `skill_manage` is not available in the agent's toolset, note this for the user and suggest they run the registration manually. ## Cleanup After writing all files: 1. Verify the umbrella registered successfully: ``` skill_view(name='') ``` If it returns `status: available`, proceed. If not found, re-run the `skill_manage(action='create')` call. 2. Remove all `workflow-architect:state:*` memory entries (`memory(action='remove', target='memory', old_text='workflow-architect:state:')`) 2. Remove all `workflow-architect:state:*` memory entries (`memory(action='remove', target='memory', old_text='workflow-architect:state:')`) 2. Tell the user where the bundle was written and what it contains 3. Verify the umbrella loads correctly with `skill_view(name='')` — if it doesn't resolve, check that `skill_manage(action='create')` was run and the SKILL.md has valid frontmatter 4. Verify at least one registered sub-skill loads: `skill_view(name='-')` 5. Suggest they enter the workflow via any trigger phrase covered by the umbrella's description, or by manually loading the umbrella skill