bmad-module-skill-forge 0.8.4 → 0.9.0

package/src/workflows/export-skill/steps-c/step-04-update-context.md

@@ -69,27 +69,155 @@ Auto-proceed immediately to {nextStepFile}.
 
 Load {managedSectionData} and read the complete format template and three-case logic.
 
-### 3. Determine Target File
+### 3. Determine Target File(s)
 
-Based on the `--platform` flag parsed in step-01:
+Using the `target_platforms` list resolved in step-01, determine all target files:
 
 | Platform | Target File |
 |----------|-------------|
-| `claude` (default) | CLAUDE.md |
+| `claude` | CLAUDE.md |
 | `cursor` | .cursorrules |
 | `copilot` | AGENTS.md |
 
-Resolve target file path at project root: `{project-root}/{target-file}`
+For each platform in `target_platforms`, resolve target file path: `{project-root}/{target-file}`
+
+**If multiple platforms:** Sections 4-9a execute as a loop — one full pass per target platform. Each iteration uses the same skill index but rewrites root paths per platform (section 4d) and writes to the platform-specific target file. Section 9b executes once after all iterations complete.
+
+**Processing order:** Process platforms in the order listed in `target_platforms`.
+
+#### 3b. Detect Orphaned Platform Files (Stale Managed Sections)
+
+A platform file becomes orphaned when its IDE is removed from `config.yaml` after a prior export. The file still contains an SKF managed section pointing to stale skill versions, but no future export will rewrite it.
+
+Build `orphaned_platform_files` — the set of platform context files that exist on disk with an `<!-- SKF:BEGIN -->` marker but whose platform is NOT in the current `target_platforms` list:
+
+1. For each platform in the full set `{claude, cursor, copilot}`:
+   - If the platform is in `target_platforms`, skip (it will be rewritten in the main loop)
+   - Otherwise, check whether its target file exists (`CLAUDE.md`, `.cursorrules`, or `AGENTS.md`)
+   - If the file exists, read it and check for the `<!-- SKF:BEGIN -->` marker
+   - If the marker is present, add the file path to `orphaned_platform_files` along with the platform name
+
+2. If `orphaned_platform_files` is non-empty, emit a warning:
+
+   "**Orphaned platform files detected.** The following files contain SKF managed sections but their platforms are no longer in `config.yaml` `ides`:
+   {list: platform → file path}
+
+   The managed sections in these files are stale. Options:
+   - **(a) clear** — remove the SKF managed section from each orphaned file (surgical marker replacement, leaves user content intact)
+   - **(b) keep** — leave them untouched (they will remain stale until you re-add the IDE or delete the file)
+   - **(c) rewrite** — also rewrite the orphaned files with the current skill index (use this if the IDE was removed by mistake)"
+
+3. Wait for user choice. In non-interactive mode (dry-run or unattended), default to **(b) keep** and print the warning only.
+
+4. If the user chose **(a) clear**: for each orphaned file, replace everything between `<!-- SKF:BEGIN` and `<!-- SKF:END -->` (inclusive) with an empty string, preserving surrounding content byte-exactly. Record the cleared files in `orphans_cleared`.
+
+5. If the user chose **(c) rewrite**: add each orphaned platform to a separate `rewrite_platforms` list (kept distinct from `target_platforms` so the user's intent to only export to configured IDEs is preserved in the manifest's `platforms` field). Sections 4–9a will loop over `target_platforms + rewrite_platforms` for this run only. Record the rewritten files in `orphans_rewritten`.
+
+6. If the user chose **(b) keep**: record nothing and proceed.
+
+This cleanup only runs during interactive export. Drop-skill and rename-skill operate on the manifest's declared platforms and are not responsible for orphan detection.
 
 ### 4. Rebuild Complete Skill Index
 
-Scan `{skills_output_folder}/*/context-snippet.md` to find ALL exported skills (not just the current one).
+#### 4a. Read Export Manifest (v2 — version-aware)
+
+Read `{skills_output_folder}/.export-manifest.json` — see [knowledge/version-paths.md](../../../knowledge/version-paths.md) for the full v2 schema:
+
+**If the file exists:** Parse JSON. Check for `schema_version` field:
+
+**v2 manifest** (`schema_version: "2"`):
+```json
+{
+  "schema_version": "2",
+  "exports": {
+    "skill-name": {
+      "active_version": "0.6.0",
+      "versions": {
+        "0.1.0": {
+          "platforms": ["claude"],
+          "last_exported": "2026-01-15",
+          "status": "deprecated"
+        },
+        "0.5.0": {
+          "platforms": ["claude"],
+          "last_exported": "2026-03-15",
+          "status": "archived"
+        },
+        "0.6.0": {
+          "platforms": ["claude", "copilot"],
+          "last_exported": "2026-04-04",
+          "status": "active"
+        }
+      }
+    }
+  }
+}
+```
+
+**Status values:**
+- `"active"` — currently exported; snippet appears in managed sections
+- `"archived"` — previously exported, not active; files retained for rollback
+- `"deprecated"` — dropped via drop-skill workflow; excluded from all exports (files may or may not exist on disk)
+- `"draft"` — created but never exported
+
+**v1 manifest** (no `schema_version` field — migrate in-place to v2):
+1. For each entry in `exports`, read its `platforms` and `last_exported`
+2. Resolve the skill's current version from `{resolved_skill_package}/metadata.json`
+3. Wrap in v2 structure: set `active_version` to the resolved version, create a single entry in `versions` with `status: "active"`, the original `platforms`, and `last_exported`
+4. Set `schema_version: "2"` at root
+5. Hold the migrated structure in context (it will be written in section 9b)
+
+**If the file does not exist** (first export or migration): Treat as empty — only the current export target will appear in the rebuilt index.
 
-**If no context-snippet.md files are found:** Generate managed section with zero skills — header only, no skill entries.
+#### 4b. Build Exported Skill Set (version-aware)
 
-For each found context-snippet.md:
-1. Read snippet content
-2. Add to skill index
+Determine the set of skills to include in the rebuilt index:
+
+1. Start with all skill names listed in the manifest's `exports` object (if manifest exists)
+2. For each skill, record its `active_version` from the manifest (v2 schema)
+3. **Integrity guard — `active_version` must resolve to a versions entry:** Check that `versions[active_version]` exists as a key. If `active_version` is set but there is no matching entry under `versions`, the manifest is inconsistent (possible corruption or a botched v1→v2 migration). Skip this skill and log a loud warning: "**Manifest integrity warning:** `{skill-name}.active_version = v{active_version}` has no matching entry under `versions`. Skipping. Re-run `[EX] Export Skill` on `{skill-name}` to repair the manifest entry."
+4. **Exclude deprecated skills:** If the `active_version` entry in `versions.{active_version}` has `status: "deprecated"`, skip this skill entirely — it has been dropped via drop-skill workflow and must not appear in the managed section. Log: "Skipping {skill-name} — active version v{active_version} is deprecated"
+5. Add the current export target skill name (ensures it is always included even before manifest is written) — use the version from `{resolved_skill_package}/metadata.json` as its `active_version`
+6. This is the **exported skill set** — each entry has a skill name and its resolved `active_version`
+
+#### 4c. Resolve and Filter Snippets (manifest-driven — replaces glob scan)
+
+Instead of globbing `{skills_output_folder}/*/context-snippet.md`, resolve snippets from the exported skill set built in 4b:
+
+**For each skill in the exported skill set:**
+1. Resolve `{skill_package}` using the skill's `active_version`: `{skills_output_folder}/{skill-name}/{active_version}/{skill-name}/`
+2. Read `{skill_package}/context-snippet.md`
+3. **If snippet exists:** Add to skill index
+4. **If snippet does not exist at the versioned path:** Check for `active` symlink at `{skills_output_folder}/{skill-name}/active/{skill-name}/context-snippet.md`. If still not found, skip with warning: "Snippet missing for {skill-name} v{active_version} — skipping from managed section"
+
+**Skills NOT in the exported skill set are never scanned** — they have not been through export-skill and must not appear in the managed section (ADR-K).
+
+**If no snippets pass the filter:** Generate managed section with zero skills — header only, no skill entries.
+
+#### 4d. Rewrite Root Paths for Target Platform
+
+The context-snippet.md files on disk contain root paths for the platform they were originally exported to. When assembling the managed section for the current target platform, rewrite root paths if they differ:
+
+**Platform root path mapping:**
+
+| Platform | Root Path Prefix |
+|----------|-----------------|
+| `claude` | `.claude/skills/` |
+| `cursor` | `.cursor/skills/` |
+| `copilot` | `.agents/skills/` |
+| _(legacy)_ | `skills/` |
+
+The legacy `skills/` prefix may appear in snippets exported before platform-aware root paths were introduced, or in draft snippets generated by create-skill/quick-skill.
+
+For each snippet being included in the managed section:
+
+1. Read the `root:` value from the snippet's first line
+2. Detect the current root prefix by matching against the known prefixes above (check platform-specific prefixes first, then fall back to legacy `skills/`)
+3. If the detected prefix does not match the current target platform's prefix, rewrite it
+4. Example: if snippet has `root: .claude/skills/my-lib/` but target is `cursor`, rewrite to `root: .cursor/skills/my-lib/`
+5. Example: if snippet has legacy `root: skills/my-lib/` and target is `copilot`, rewrite to `root: .agents/skills/my-lib/`
+
+This ensures each platform's managed section points to the correct platform-specific skill directory, including during migration from pre-platform-aware exports.
 
 **Sort skills alphabetically by name.**
 
@@ -139,7 +267,7 @@ Assemble the complete managed section:
 
 ### 7. Present Change Preview
 
-"**Context update prepared.**
+"**Context update prepared.{if multi-platform: ' (platform {i}/{total}: {platform})'}**
 
 **Target:** `{project-root}/{target-file}`
 **Case:** {1: Create / 2: Append / 3: Regenerate}
@@ -170,9 +298,16 @@ Auto-proceed to {nextStepFile}.
 
 Display: "**Select:** [C] Continue — write changes to {target-file}"
 
+**Multi-platform behavior:** When processing multiple platforms, present all platforms' previews together before asking for a single confirmation. After confirmation, write all target files sequentially, verifying each one.
+
+"**Targets:** {list all platform → target-file pairs}
+**Ready to write changes to all targets?**"
+
+Display: "**Select:** [C] Continue — write changes to all targets"
+
 #### Menu Handling Logic:
 
-- IF C: Write the changes to target file, verify write succeeded, then load, read entire file, then execute {nextStepFile}
+- IF C: Write the changes to all target files (or single target), verify each write succeeded, then load, read entire file, then execute {nextStepFile}
 - IF Any other: help user respond, then [Redisplay Menu Options](#8-present-menu-options)
 
 #### EXECUTION RULES:
@@ -194,6 +329,38 @@ After user confirms with 'C':
 **If verification fails:**
 "**WARNING: Write verification failed.** {describe issue}. File may need manual review."
 
+### 9b. Update Export Manifest (Non-Dry-Run Only)
+
+**This section executes ONCE after all platform iterations complete** (outside the per-platform loop defined in section 3). Only platforms whose writes succeeded in section 9 are recorded.
+
+1. Read `{skills_output_folder}/.export-manifest.json` (or start with `{"schema_version": "2", "exports": {}}` if it does not exist)
+2. Ensure `schema_version` is `"2"` (if v1 was migrated in section 4a, the migrated structure is already in context)
+3. Add or update the current skill's entry in v2 format:
+   ```json
+   "{skill-name}": {
+     "active_version": "{version}",
+     "versions": {
+       "{version}": {
+         "platforms": ["{successfully-written platforms}"],
+         "last_exported": "{current-date}",
+         "status": "active"
+       }
+     }
+   }
+   ```
+   - `{version}` is the version from `{resolved_skill_package}/metadata.json`
+   - Set `platforms` to only the platforms that were successfully written and verified in section 9
+   - If the skill already has a manifest entry:
+     - Set `active_version` to the current version
+     - If the version already exists in `versions`, update its `platforms` (merge, deduplicate), `last_exported`, and set `status: "active"`
+     - If this is a new version, add it to `versions` with `status: "active"` and set any previously-active version's status to `"archived"`
+     - Preserve all other version entries in `versions` (do not delete archived versions)
+4. Write the updated manifest to `{skills_output_folder}/.export-manifest.json`
+
+**Dry-run mode:** Do NOT update the manifest. Display: "**[DRY RUN] Export manifest would be updated for {skill-name} on platform(s) {platform-list}.**"
+
+**Error handling:** If manifest write fails, warn but do not fail the workflow — the managed section was already written successfully.
+
 ## CRITICAL STEP COMPLETION NOTE
 
 ONLY WHEN the user confirms changes by selecting 'C' (or auto-proceed in dry-run) and the write is verified will you load and read fully `{nextStepFile}` to execute the token report.
@@ -205,8 +372,11 @@ ONLY WHEN the user confirms changes by selecting 'C' (or auto-proceed in dry-run
 ### ✅ SUCCESS:
 
 - Managed section format loaded from {managedSectionData}
-- Target file correctly determined from platform flag
-- Complete skill index rebuilt from all exported skills
+- Target file(s) correctly determined from platform flag or config.yaml ides list
+- Multi-platform loop executed for all target_platforms
+- Root paths rewritten per platform in managed section
+- Complete skill index rebuilt from exported skills only (filtered via .export-manifest.json per ADR-K)
+- Export manifest updated after successful write (non-dry-run only)
 - Correct case detected (create/append/regenerate)
 - Clear diff preview shown to user
 - User confirmation received before writing
@@ -218,6 +388,8 @@ ONLY WHEN the user confirms changes by selecting 'C' (or auto-proceed in dry-run
 
 - Modifying content outside `<!-- SKF:BEGIN/END -->` markers
 - Not rebuilding the COMPLETE skill index (only adding current skill)
+- Including un-exported skills in managed section (bypasses ADR-K publishing gate)
+- Updating export manifest during dry-run
 - Writing without user confirmation
 - Not verifying write after completion
 - Not detecting the correct case (create/append/regenerate)

package/src/workflows/export-skill/steps-c/step-05-token-report.md

@@ -72,14 +72,14 @@ For each artifact, estimate tokens using the heuristic: **words * 1.3** (approxi
 | Artifact | Words | Est. Tokens | Notes |
 |----------|-------|-------------|-------|
 | context-snippet.md | {n} | ~{t} | Passive context (always-on) |
-| Managed section (all skills) | {n} | ~{t} | In {target-file}, all {count} skills |
+| Managed section (all skills) | {n} | ~{t} | In {target-file-list}, all {count} skills |
 | SKILL.md | {n} | ~{t} | Active skill (on-trigger) |
 | metadata.json | {n} | ~{t} | Machine-readable |
 | references/ | {n} | ~{t} | {count} files |
 | **Package total** | **{n}** | **~{t}** | **All artifacts combined** |
 
 **Context Budget Impact:**
-- **Always-on cost:** ~{managed-section-tokens} tokens (managed section in {target-file})
+- **Always-on cost:** ~{managed-section-tokens} tokens (managed section in {target-file-list})
 - **On-trigger cost:** ~{skill-tokens} tokens (when SKILL.md is loaded)
 - **Full disclosure cost:** ~{total-tokens} tokens (if references/ also loaded)
 

package/src/workflows/export-skill/steps-c/step-06-summary.md

@@ -55,7 +55,7 @@ To present a complete export summary showing all files written, token counts, an
 
 **Skill:** {skill-name}
 **Type:** {skill_type} | **Authority:** {source_authority} | **Tier:** {confidence_tier}
-**Platform:** {platform} → {target-file}
+**Platform(s):** {platform-list} → {target-file-list}
 
 ---
 
@@ -64,7 +64,8 @@ To present a complete export summary showing all files written, token counts, an
 | File | Status | Tokens |
 |------|--------|--------|
 | context-snippet.md | {✅ written / ⚠️ skipped (passive off) / 👁️ previewed} | ~{t} |
-| {target-file} managed section | {✅ updated (case {n}) / ⚠️ skipped / 👁️ previewed} | ~{t} |
+| {target-file-1} managed section | {✅ updated (case {n}) / ⚠️ skipped / 👁️ previewed} | ~{t} |
+| {target-file-N} managed section | {✅ updated (case {n}) / ⚠️ skipped / 👁️ previewed} | ~{t} |
 | Package structure | ✅ validated | ~{t} total |
 
 **Total context cost:** ~{always-on-tokens} tokens always-on, ~{on-trigger-tokens} tokens on-trigger"
@@ -102,7 +103,7 @@ Your skill is committed to the project's `skills/` directory and ships with your
 
 **Team members** will automatically have access when they pull the latest changes.
 
-**To update team context:** Ensure {target-file} is committed with the managed section update."
+**To update team context:** Ensure all target files ({target-file-list}) are committed with the managed section updates."
 
 **If `community`:**
 
@@ -110,12 +111,28 @@ Your skill is committed to the project's `skills/` directory and ships with your
 
 Your skill is generated from an external dependency for local use.
 
-**Location:** `{skills_output_folder}/{skill-name}/`
+**Location:** `{skills_output_folder}/{skill-name}/{version}/{skill-name}/`
 **Scope:** This project only — not for publishing to agentskills.io
 
 **Note:** Community skills are generated from third-party source code. Only `official` skills (generated by the library maintainer) should be published to the ecosystem."
 
-### 3. Dry Run Reminder (If Applicable)
+### 3. Use It In This Project
+
+Always show this section (regardless of `source_authority`) so the author can install the skill they just forged into the current project and try it immediately:
+
+"### Use It In This Project
+
+To install this skill into the current project right now:
+
+```
+npx skills add {resolved_skill_package}
+```
+
+Replace `{resolved_skill_package}` with the absolute path to the package folder shown above (from step-02), e.g. `{skills_output_folder}/{skill-name}/{version}/{skill-name}/`.
+
+For other source formats (registry name, git URL, tarball, etc.), see the **Installation → Source Formats** section at <https://www.npmjs.com/package/skills>."
+
+### 4. Dry Run Reminder (If Applicable)
 
 **If dry-run mode was active:**
 
@@ -125,7 +142,7 @@ No files were written. To run the export for real:
 
 **Re-run without `--dry-run`** to write all files."
 
-### 4. Recommended Next Steps
+### 5. Recommended Next Steps
 
 "### Next Steps
 
@@ -133,7 +150,7 @@ No files were written. To run the export for real:
 - **update-skill** — After refactoring source code, regenerate the skill
 - **test-skill** — Verify skill completeness and accuracy"
 
-### 5. Workflow Complete
+### 6. Workflow Complete
 
 "---
 
@@ -152,6 +169,7 @@ This is the final step. The workflow is complete. No further steps to load.
 - Complete summary with all files and their status
 - Token counts included from step-05
 - Distribution instructions appropriate for source_authority
+- Local install command (`npx skills add {resolved_skill_package}`) displayed with npmjs.com/package/skills link for alternate source formats
 - Dry-run correctly indicated (if applicable)
 - Recommended next workflows listed
 - Clear workflow completion signal
@@ -160,6 +178,7 @@ This is the final step. The workflow is complete. No further steps to load.
 
 - Missing files from summary
 - Wrong distribution instructions for source_authority
+- Omitting the local install command / npmjs source-formats link
 - Not indicating dry-run status
 - Writing additional files (console-only step)
 - Not ending the workflow cleanly

package/src/workflows/quick-skill/steps-c/step-01-resolve-target.md

@@ -69,6 +69,16 @@ Provide a **GitHub URL** or **package name** and I'll resolve it to source and c
 
 Wait for user input.
 
+### 1b. Parse Version Targeting
+
+**Version targeting:** If the user input contains `@` followed by a semver-like string (e.g., `cognee@0.5.0`, `https://github.com/org/repo@2.1.0-beta`), parse it as:
+- **Package/URL:** everything before the last `@`
+- **Target version:** everything after the last `@`
+
+Store the target version as `target_version` in the extraction context. When present, this version overrides auto-detection (same behavior as `target_version` in the skill-brief schema).
+
+If no `@version` suffix is present, proceed as today — version will be auto-detected.
+
 ### 2. Classify Input Type
 
 **If input starts with `https://github.com/` or `github.com/`:**

package/src/workflows/quick-skill/steps-c/step-03-quick-extract.md

@@ -54,6 +54,8 @@ To read the resolved GitHub repository source and extract the public API surface
 
 **CRITICAL:** Follow this sequence exactly. Do not skip, reorder, or improvise unless user explicitly requests a change.
 
+**Ref-aware source reading:** When `source_ref` is set from tag resolution (see step-01), append `?ref={source_ref}` to all GitHub API content and tree requests (e.g., `gh api repos/{owner}/{repo}/contents/{path}?ref={source_ref}`) to read from the tagged version. When using web browsing, use the tagged URL format (e.g., `github.com/{owner}/{repo}/blob/{source_ref}/{path}`). This ensures extraction reads from the same source version resolved during tag resolution.
+
 ### 1. Read README
 
 Read `README.md` from the repository root via web browsing.

package/src/workflows/quick-skill/steps-c/step-05-validate.md

@@ -105,7 +105,7 @@ Check that SKILL.md has these required sections populated:
 Check context-snippet.md format compliance:
 
 - [ ] **Vercel-aligned indexed format** — pipe-delimited with version, retrieval instruction, section anchors
-- [ ] **First line** matches pattern: `[{name} v{version}]|root: skills/{name}/`
+- [ ] **First line** matches pattern: `[{name} v{version}]|root: {prefix}{name}/` where prefix is `skills/` or a platform root (`.claude/skills/`, `.cursor/skills/`, `.agents/skills/`)
 - [ ] **Second line** starts with: `|IMPORTANT:`
 - [ ] **Approximate token count** is ~80-120 tokens
 

package/src/workflows/quick-skill/steps-c/step-06-write.md

@@ -35,7 +35,7 @@ To write the compiled SKILL.md, context-snippet.md, and metadata.json to the ski
 ## EXECUTION PROTOCOLS:
 
 - 🎯 Follow the MANDATORY SEQUENCE exactly
-- 💾 Write three files to {skills_output_folder}/{repo_name}/
+- 💾 Write three files to `{skill_package}` and create the `active` symlink
 - 📖 File I/O required for directory creation and file writing
 - 🚫 This is the final step — no next step to load
 
@@ -45,6 +45,7 @@ To write the compiled SKILL.md, context-snippet.md, and metadata.json to the ski
 - Also available: resolved_url, repo_name, language, skills_output_folder
 - Focus: file writing and completion only
 - This is the FINAL step — workflow ends here
+- Path resolution: See `knowledge/version-paths.md` for canonical path templates. Quick-skill uses `{repo_name}` as the skill name and defaults `{version}` to `1.0.0` if not detected from the extraction inventory
 
 ## MANDATORY SEQUENCE
 
@@ -52,15 +53,16 @@ To write the compiled SKILL.md, context-snippet.md, and metadata.json to the ski
 
 ### 1. Create Output Directory
 
-Create the skill output directory:
+Resolve `{version}` from the extraction inventory's detected version, defaulting to `1.0.0` if not detected. Create the skill output directories:
 
 ```
-{skills_output_folder}/{repo_name}/
+{skill_group}                          # {skills_output_folder}/{repo_name}/
+{skill_package}                        # {skills_output_folder}/{repo_name}/{version}/{repo_name}/
 ```
 
-If directory already exists, confirm with user before overwriting:
+If `{skill_package}` already exists, confirm with user before overwriting:
 
-"**Directory `{skills_output_folder}/{repo_name}/` already exists.** Overwrite existing files? [Y/N]"
+"**Directory `{skill_package}` already exists.** Overwrite existing files? [Y/N]"
 
 - **If user selects Y:** Proceed to section 2.
 - **If user selects N:** Halt with: "Overwrite cancelled. Existing skill preserved. Run [QS] with a different skill name or remove the existing directory manually."
@@ -70,7 +72,7 @@ If directory already exists, confirm with user before overwriting:
 Write the compiled SKILL.md content to:
 
 ```
-{skills_output_folder}/{repo_name}/SKILL.md
+{skill_package}/SKILL.md
 ```
 
 Confirm: "Written: SKILL.md"
@@ -80,7 +82,7 @@ Confirm: "Written: SKILL.md"
 Write the context snippet to:
 
 ```
-{skills_output_folder}/{repo_name}/context-snippet.md
+{skill_package}/context-snippet.md
 ```
 
 Confirm: "Written: context-snippet.md"
@@ -90,11 +92,23 @@ Confirm: "Written: context-snippet.md"
 Write the metadata JSON to:
 
 ```
-{skills_output_folder}/{repo_name}/metadata.json
+{skill_package}/metadata.json
 ```
 
 Confirm: "Written: metadata.json"
 
+### 4b. Create Active Symlink
+
+Create or update the `active` symlink at `{skill_group}/active` pointing to `{version}`:
+
+```
+{skill_group}/active -> {version}
+```
+
+If the symlink already exists, remove it first and recreate.
+
+Confirm: "Symlink: {skill_group}/active -> {version}"
+
 ### 5. Handle Write Failures
 
 **If any file write fails — HARD HALT:**
@@ -112,16 +126,17 @@ Please check:
 
 "**Quick Skill complete.**
 
-**Skill:** {repo_name}
+**Skill:** {repo_name} v{version}
 **Language:** {language}
 **Source:** {resolved_url}
 **Authority:** community
 **Confidence:** {extraction confidence}
 
 **Files written:**
-- `{skills_output_folder}/{repo_name}/SKILL.md`
-- `{skills_output_folder}/{repo_name}/context-snippet.md`
-- `{skills_output_folder}/{repo_name}/metadata.json`
+- `{skill_package}/SKILL.md`
+- `{skill_package}/context-snippet.md`
+- `{skill_package}/metadata.json`
+- `{skill_group}/active` -> `{version}`
 
 **Exports documented:** {count}
 **Validation:** {pass / N issues (advisory)}
@@ -147,8 +162,9 @@ No next step to load. Session ends here.
 
 ### ✅ SUCCESS:
 
-- Output directory created (or overwrite confirmed)
-- All three files written successfully
+- Output directory created (or overwrite confirmed) with version-nested structure
+- All three files written successfully to {skill_package}
+- Active symlink created at {skill_group}/active -> {version}
 - Completion summary displayed with file paths
 - Next step recommendations provided
 - Workflow ends cleanly

package/src/workflows/refine-architecture/steps-c/step-01-init.md

@@ -74,9 +74,14 @@ Wait for user input. Store the validated architecture document path as `architec
 
 ### 2. Scan Skills Folder
 
-Read the `{skills_output_folder}` directory.
+Read the `{skills_output_folder}` directory. Skills use a version-nested directory structure (see [knowledge/version-paths.md](../../../knowledge/version-paths.md)).
 
-For each subdirectory, check for the presence of `SKILL.md` and `metadata.json`.
+**Version-aware skill discovery:**
+1. Read `{skills_output_folder}/.export-manifest.json` if it exists. For each skill in `exports`, use `active_version` to resolve `{skill_package}` = `{skills_output_folder}/{skill-name}/{active_version}/{skill-name}/`
+2. For any subdirectory not covered by the manifest, check for an `active` symlink at `{skills_output_folder}/{dir_name}/active` — resolve to `{skill_group}/active/{dir_name}/`
+3. Fall back to flat path `{skills_output_folder}/{dir_name}/` for unmigrated skills
+
+For each resolved skill package, check for the presence of `SKILL.md` and `metadata.json`.
 
 **For each valid skill directory, extract from metadata.json:**
 - `name` — skill name
@@ -87,7 +92,7 @@ For each subdirectory, check for the presence of `SKILL.md` and `metadata.json`.
 
 **Build a skill inventory** as an internal list of all loaded skills with the fields above.
 
-**If a subdirectory lacks SKILL.md or metadata.json:**
+**If a resolved skill package lacks SKILL.md or metadata.json:**
 - Log: "Skipping `{dir_name}` — missing SKILL.md or metadata.json"
 - Do not include in inventory