bundle-builder: no umbrella SKILL.md entry point — generated bundles invisible to agent #52

New issue

Closed

opened 2026-05-29 23:12:41 -04:00 by magnus · 0 comments

magnus commented

2026-05-29 23:12:41 -04:00

Owner

Summary

The workflow-architect bundle-builder generates sub-skills and registers them with skill_manage(), but never creates an umbrella SKILL.md at the bundle root. Without an umbrella, the agent cannot auto-detect the workflow bundle via trigger conditions — the bundle exists but has no entry point.

Current Behavior

After convergence, the bundle-builder generates these files:

<bundle-name>/
├── README.md
├── manifest.yaml
├── skills/
│   ├── phase-one.md
│   ├── phase-two.md
│   └── ...
├── decision-map.md
├── AGENTS.md
├── kanban/          (optional)
└── references/
    └── generated-from.md

Each sub-skill is registered with skill_manage(action="create") so it shows up in skills_list(). But there is no umbrella SKILL.md at <bundle-name>/SKILL.md — which means:

No auto-detectable entry point: the agent cannot discover the bundle via trigger conditions
No "big picture" context: when a user says "I want to write about X" or "research this," the agent has no single skill that says "this matches a known workflow — here is the pipeline and all available phases"
No slash command: the bundle cannot be loaded as /bundle-name because no umbrella SKILL.md exists

This was discovered when a user of the magnus919-blogging bundle asked "how am I meant to enter the workflow?" — the sub-skills existed, but there was no door.

Expected Behavior

The bundle-builder should generate an umbrella SKILL.md at <bundle-name>/SKILL.md as its first step that:

Lists all phases/sub-skills with descriptions and transition signals
Contains broad trigger conditions in its description frontmatter so the agent can auto-detect it
Includes a Mermaid flowchart showing the workflow
Is registered via skill_manage(action="create") so it appears in skills_list()

The generated bundle structure should be:

<bundle-name>/
├── SKILL.md               ← UMBRELLA (entry point, registered)
├── README.md
├── manifest.yaml
├── skills/
│   ├── phase-one.md
│   ├── phase-two.md
│   └── ...
├── decision-map.md
├── AGENTS.md
├── kanban/          (optional)
└── references/
    └── generated-from.md

Proposed Fix

1. bundle-builder/SKILL.md

Add a new step 0 to the file creation order (before existing step 1) that:

a. Generates an umbrella SKILL.md for the bundle with:

Frontmatter: name=<bundle-name>, description with broad trigger conditions, metadata tags including bundle:generated, spec-version "1.0"
Body: Mermaid flowchart, sub-skill table (name, description, trigger keywords), navigation instructions (identify current phase → load sub-skill → follow instructions → transition), pipeline heuristics
b. Writes it to <bundle-name>/SKILL.md
c. Registers it with skill_manage(action="create", name="<bundle-name>", content=...)

Update the Output Structure diagram to show SKILL.md at root.

Update step 8 (registration) to also register the umbrella if not already registered.

2. Umbrella SKILL.md (workflow-architect umbrella)

Update the "What You Get" section to list the umbrella SKILL.md as the first item (entry point).

Update step 5 of the Loading Protocol to include umbrella registration verification.

3. AGENTS.md

Add a "Registration" section explaining that the umbrella and sub-skills are registered via skill_manage() so they appear in skills_list() and are discoverable.

Why This Matters

Without the umbrella, a workflow bundle is a collection of individual skills that the agent can only load if told their exact names. With the umbrella, the agent can detect "oh, the user is starting their morning triage routine — I should load the morning-triage skill" based on the trigger conditions in the umbrella description. This is what makes workflow-architect-generated bundles actually useful in day-to-day sessions.

Suggested Labels

bug, enhancement, skill/workflow-architect

[Jasper - AI agent on behalf of Magnus Hedemark]

## Summary The `workflow-architect` bundle-builder generates sub-skills and registers them with `skill_manage()`, but never creates an **umbrella SKILL.md** at the bundle root. Without an umbrella, the agent cannot auto-detect the workflow bundle via trigger conditions — the bundle exists but has no entry point. ## Current Behavior After convergence, the bundle-builder generates these files: ``` <bundle-name>/ ├── README.md ├── manifest.yaml ├── skills/ │ ├── phase-one.md │ ├── phase-two.md │ └── ... ├── decision-map.md ├── AGENTS.md ├── kanban/ (optional) └── references/ └── generated-from.md ``` Each sub-skill is registered with `skill_manage(action="create")` so it shows up in skills_list(). But there is no umbrella `SKILL.md` at `<bundle-name>/SKILL.md` — which means: 1. No auto-detectable entry point: the agent cannot discover the bundle via trigger conditions 2. No "big picture" context: when a user says "I want to write about X" or "research this," the agent has no single skill that says "this matches a known workflow — here is the pipeline and all available phases" 3. No slash command: the bundle cannot be loaded as `/bundle-name` because no umbrella SKILL.md exists This was discovered when a user of the magnus919-blogging bundle asked "how am I meant to enter the workflow?" — the sub-skills existed, but there was no door. ## Expected Behavior The bundle-builder should generate an umbrella SKILL.md at `<bundle-name>/SKILL.md` as its **first step** that: - Lists all phases/sub-skills with descriptions and transition signals - Contains broad trigger conditions in its `description` frontmatter so the agent can auto-detect it - Includes a Mermaid flowchart showing the workflow - Is registered via `skill_manage(action="create")` so it appears in skills_list() The generated bundle structure should be: ``` <bundle-name>/ ├── SKILL.md ← UMBRELLA (entry point, registered) ├── README.md ├── manifest.yaml ├── skills/ │ ├── phase-one.md │ ├── phase-two.md │ └── ... ├── decision-map.md ├── AGENTS.md ├── kanban/ (optional) └── references/ └── generated-from.md ``` ## Proposed Fix ### 1. bundle-builder/SKILL.md Add a new step 0 to the file creation order (before existing step 1) that: a. Generates an umbrella SKILL.md for the bundle with: - Frontmatter: name=`<bundle-name>`, description with broad trigger conditions, metadata tags including `bundle:generated`, spec-version "1.0" - Body: Mermaid flowchart, sub-skill table (name, description, trigger keywords), navigation instructions (identify current phase → load sub-skill → follow instructions → transition), pipeline heuristics b. Writes it to `<bundle-name>/SKILL.md` c. Registers it with `skill_manage(action="create", name="<bundle-name>", content=...)` Update the Output Structure diagram to show SKILL.md at root. Update step 8 (registration) to also register the umbrella if not already registered. ### 2. Umbrella SKILL.md (workflow-architect umbrella) Update the "What You Get" section to list the umbrella SKILL.md as the first item (entry point). Update step 5 of the Loading Protocol to include umbrella registration verification. ### 3. AGENTS.md Add a "Registration" section explaining that the umbrella and sub-skills are registered via skill_manage() so they appear in skills_list() and are discoverable. ## Why This Matters Without the umbrella, a workflow bundle is a collection of individual skills that the agent can only load if told their exact names. With the umbrella, the agent can detect "oh, the user is starting their morning triage routine — I should load the morning-triage skill" based on the trigger conditions in the umbrella description. This is what makes workflow-architect-generated bundles actually useful in day-to-day sessions. ## Suggested Labels bug, enhancement, skill/workflow-architect [Jasper - AI agent on behalf of Magnus Hedemark]

magnus referenced this issue from a commit

2026-05-29 23:15:58 -04:00

fix(bundle-builder): generate umbrella SKILL.md as discoverable entry point

magnus referenced this issue from a pull request that will close it,

2026-05-29 23:16:04 -04:00

fix(bundle-builder): generate umbrella SKILL.md as discoverable entry point #53

magnus referenced this issue from a commit

2026-06-03 23:12:37 -04:00

fix: add umbrella SKILL.md to 'What You Get' and update Loading Protocol (fixes #52)