bmad-module-skill-forge 0.2.0 → 0.4.0

package/src/workflows/audit-skill/validation-report.md

@@ -175,7 +175,7 @@ No bmb-specific path assumptions found. Workflow correctly uses SKF module varia
 **Init (step-01):**
 - ✅ Creates output from template (`{templateFile}`)
 - ✅ C-only menu (no A/P — appropriate for init)
-- ✅ Input discovery: loads SKILL.md, metadata.json, provenance-map.json, forge-tier.yaml
+- ✅ Input discovery: loads SKILL.md, metadata.json, provenance-map.json, forge-tier.yaml, and checks `preferences.yaml` for `tier_override`
 - ✅ User gate with baseline summary before analysis
 
 **Auto-Proceed Steps (02-05):**
@@ -490,7 +490,7 @@ The audit-skill workflow is a well-designed, cohesive 6-step pipeline that achie
 | ast_bridge | Forge/Deep tier | ✅ Steps 02-03 reference AST extraction | ✅ |
 | gh_bridge | All tiers | ✅ Steps 01-02 reference file reading | ✅ |
 | qmd_bridge | Deep tier only | ✅ Step 04 references QMD queries | ✅ |
-| skills_ref | Included | ✅ Step 01 references skill format validation | ✅ |
+| skill-check | Included | ✅ Step 01 references skill format validation | ✅ |
 
 ### Implementation Gaps
 

package/src/workflows/audit-skill/workflow-plan-audit-skill.md

@@ -189,7 +189,7 @@ Drift report with severity levels (added/removed/changed exports, breaking chang
 - **ast_bridge** (ast-grep): Required at Forge/Deep tier — Steps 02-03 structural extraction and comparison
 - **gh_bridge** (gh CLI): Required at all tiers — Steps 01-02 source file reading
 - **qmd_bridge** (QMD): Required at Deep tier only — Step 04 semantic knowledge context
-- **skills_ref**: Included — Step 01 skill format validation and ecosystem cross-reference
+- **skill-check**: Included — Step 01 skill format validation: `npx skill-check check --fix --format json` for validation + auto-fix + quality scoring, security scan for prompt injection detection
 
 **Installation Requirements:**
 - None — all tools pre-detected by setup-forge workflow

package/src/workflows/brief-skill/data/scope-templates.md

@@ -0,0 +1,60 @@
+# Scope Templates Reference
+
+## Scope Type Options
+
+Present these options to the user for selection:
+
+**[F] Full Library** — Include everything. Best for smaller, focused libraries.
+- All public exports, all modules
+- Exclude only tests, build artifacts, and internal utilities
+
+**[M] Specific Modules** — Select which modules to include. Best for large libraries where only some parts are relevant.
+- You choose which modules/directories
+- Fine-grained control over what's in and out
+
+**[P] Public API Only** — Include only the public-facing API surface. Best for libraries with a clear public/private boundary.
+- Entry points and exported interfaces only
+- Internal implementation excluded
+
+## Boundary Definitions by Scope Type
+
+### Full Library Boundaries
+
+Default inclusions:
+- All source files under {main source directory}
+- All public modules: {list from analysis}
+
+Default exclusions:
+- Test files (`**/*.test.*`, `**/*.spec.*`, `**/test/`, `**/tests/`)
+- Build artifacts (`**/dist/`, `**/build/`, `**/target/`)
+- Configuration files
+- Documentation source files
+
+Prompt: "Any additional exclusions you'd like to add? Or adjustments to these defaults?"
+
+### Specific Modules Boundaries
+
+**Phase 1 — Module selection:**
+
+Present numbered list of modules from step 02 with brief descriptions.
+Prompt: "Which modules would you like to include? (Enter numbers, comma-separated):"
+
+**Phase 2 — Granularity within selected modules:**
+
+For selected modules, ask:
+- **A)** Everything in those modules (all files)
+- **B)** Only public exports from those modules
+
+Prompt: "Any files or patterns to explicitly exclude within these modules?"
+
+### Public API Only Boundaries
+
+**Phase 1 — Export selection:**
+
+Present numbered list of exports/entry points from step 02.
+Prompt: "Which of these would you like to include? (Enter numbers, or 'all'):"
+
+**Phase 2 — Confirm exclusions:**
+
+Exclusions will include all internal implementation files, tests, and utilities.
+Prompt: "Any additional items you'd like to include or exclude?"

package/src/workflows/brief-skill/data/skill-brief-schema.md

@@ -5,7 +5,7 @@
 | Field | Type | Description | Validation |
 |-------|------|-------------|------------|
 | name | string | Kebab-case skill name | Must match `[a-z0-9-]+` |
-| version | string | Semantic version | Must match `X.Y.Z` pattern, default "1.0.0" |
+| version | string | Semantic version | Must match `X.Y.Z` pattern. Auto-detect from source (see Version Detection below), fall back to "1.0.0" |
 | source_repo | string | GitHub URL or local path | Must be accessible |
 | language | string | Primary programming language | Must be detected or user-specified |
 | scope | object | Inclusion/exclusion boundaries | Must have type + at least one pattern |
@@ -14,6 +14,34 @@
 | created | string | Creation date | ISO date format |
 | created_by | string | User who created the brief | From config user_name |
 
+## Optional Fields
+
+| Field | Type | Description | Validation |
+|-------|------|-------------|------------|
+| source_type | string | Source mode: `source` or `docs-only` | Default `source`. When `docs-only`: `source_repo` optional, `doc_urls` required |
+| doc_urls | array | Documentation URLs for T3 content | Each entry: `{url, label}`. Required when `source_type: "docs-only"` |
+
+When `source_type: "docs-only"`:
+- `source_repo` becomes optional (set to doc site URL for reference)
+- `doc_urls` must have at least one entry
+- `source_authority` is forced to `community` (T3 external documentation cannot be `official`)
+- All extracted content gets `[EXT:{url}]` citations
+
+## Version Detection
+
+During brief creation, attempt to auto-detect the source version before defaulting to `"1.0.0"`. Check the first matching file in the source:
+
+- **Python:** `pyproject.toml` `[project] version` (static) → if `dynamic = ["version"]`, check `__init__.py` for `__version__` → `_version.py` if exists → `setup.py` `version=` → `git describe --tags --abbrev=0`
+- **JavaScript/TypeScript:** `package.json` (`"version"`)
+- **Rust:** `Cargo.toml` `[package] version` (static) → if `version = { workspace = true }`, resolve from workspace root `Cargo.toml` → `git describe --tags --abbrev=0`
+- **Go:** version tag from `go.mod` or `git describe --tags --abbrev=0`
+
+If the source is a remote GitHub repo, use `gh api repos/{owner}/{repo}/contents/{file}` to read the version file. If the source is local, read the file directly.
+
+If detection succeeds, use the detected version. If it fails or returns a non-semver value, fall back to `"1.0.0"`.
+
+The create-skill workflow (step-03-extract) also performs version reconciliation at extraction time — if the source version has changed since the brief was created, the extraction step warns and uses the source version.
+
 ## Scope Object Structure
 
 ```yaml
@@ -32,7 +60,8 @@ scope:
 ```yaml
 ---
 name: "{skill-name}"
-version: "1.0.0"
+version: "{detected-version or 1.0.0}"  # Auto-detect from source, fall back to 1.0.0
+source_type: "source"                    # "source" (default) or "docs-only"
 source_repo: "{github-url-or-local-path}"
 language: "{detected-language}"
 description: "{brief-description}"
@@ -40,12 +69,16 @@ forge_tier: "{quick|forge|deep}"
 created: "{date}"
 created_by: "{user_name}"
 scope:
-  type: "{full-library|specific-modules|public-api}"
+  type: "{full-library|specific-modules|public-api|docs-only}"
   include:
     - "{pattern}"
   exclude:
     - "{pattern}"
   notes: "{optional-scope-notes}"
+# Optional: documentation URLs for T3 content (required when source_type: "docs-only")
+# doc_urls:
+#   - url: "https://docs.example.com/api"
+#     label: "API Reference"
 ---
 ```
 
@@ -80,3 +113,5 @@ Created by: {created_by}
 4. `scope.type` must be one of the three defined types
 5. `scope.include` must have at least one pattern
 6. `forge_tier` must match the tier from forge-tier.yaml (or default to quick)
+7. When `source_type: "docs-only"`: `doc_urls` must have >= 1 entry, `source_repo` becomes optional
+8. Each `doc_urls` entry must have a valid `url` field

package/src/workflows/brief-skill/steps-c/step-01-gather-intent.md

@@ -64,6 +64,8 @@ Attempt to load `{forgeTierFile}`:
 - Read the tier level (quick, forge, or deep)
 - Note available tools for scoping guidance later
 
+**Apply tier override:** Read `{sidecar_path}/preferences.yaml`. If `tier_override` is set and is a valid tier value (Quick, Forge, or Deep), use it instead of the detected tier.
+
 **If not found:**
 - Display: "**Note:** No forge tier configuration found. Defaulting to Quick tier. Run **setup-forge** first for full capabilities."
 - Default to: `forge_tier: quick`
@@ -86,15 +88,29 @@ Let's get started."
 
 ### 3. Gather Target Repository
 
-"**What repository do you want to create a skill for?**
+"**What repository or documentation do you want to create a skill for?**
 
-Provide either:
+Provide one of:
 - A **GitHub URL** (e.g., `https://github.com/org/repo`)
 - A **local path** (e.g., `/path/to/project`)
+- **Documentation URLs** for a docs-only skill (e.g., `https://docs.cognee.ai/`) — use this when no source code is available (SaaS, closed-source)
 
 **Target:**"
 
-Wait for user response. Confirm the target.
+Wait for user response.
+
+**If user provides documentation URLs (not a repo):**
+- Set `source_type: "docs-only"` in the brief data
+- Collect one or more doc URLs with optional labels
+- Note: `source_authority` will be forced to `community` (T3 external documentation)
+- Note: `source_repo` becomes optional (can be set to the main doc site URL for reference)
+
+**If user provides a GitHub URL or local path:**
+- Set `source_type: "source"` (default)
+- Optionally ask: "Are there any documentation URLs you'd like to include for supplemental context? (These will be fetched as T3 external references.)"
+- If yes: collect doc URLs into `doc_urls`
+
+Confirm the target.
 
 ### 4. Gather User Intent
 
@@ -166,7 +182,7 @@ ONLY WHEN C is selected and target repository is confirmed will you load and rea
 
 ### ✅ SUCCESS:
 
-- Forge tier discovered (or defaulted to Quick with warning)
+- Forge tier discovered (or defaulted to Quick with warning), override applied if set in preferences.yaml
 - Target repository confirmed (GitHub URL or local path)
 - User intent captured with enough context for scoping
 - Skill name derived and confirmed

package/src/workflows/brief-skill/steps-c/step-03-scope-definition.md

@@ -3,6 +3,7 @@ name: 'step-03-scope-definition'
 description: 'Collaboratively define skill scope boundaries using analysis findings and scope templates'
 
 nextStepFile: './step-04-confirm-brief.md'
+scopeTemplatesFile: '../data/scope-templates.md'
 advancedElicitationTask: '{project-root}/_bmad/core/workflows/advanced-elicitation/workflow.xml'
 partyModeWorkflow: '{project-root}/_bmad/core/workflows/party-mode/workflow.md'
 ---
@@ -70,83 +71,38 @@ Based on the analysis, here's what we're working with:
 {If scope hints from step 01:}
 - **Your initial scope hints:** {hints}"
 
-### 2. Offer Scope Templates
+### 2. Handle Docs-Only Mode (if applicable)
 
-"**How broadly should this skill cover the library?**
+**If `source_type: "docs-only"`:**
 
-**[F] Full Library** — Include everything. Best for smaller, focused libraries.
-- All public exports, all modules
-- Exclude only tests, build artifacts, and internal utilities
+"**Docs-only mode — scope is defined by documentation pages.**
 
-**[M] Specific Modules** — Select which modules to include. Best for large libraries where only some parts are relevant.
-- You choose which modules/directories
-- Fine-grained control over what's in and out
+You've provided these documentation URLs:
+{numbered list of doc_urls with labels}
 
-**[P] Public API Only** — Include only the public-facing API surface. Best for libraries with a clear public/private boundary.
-- Entry points and exported interfaces only
-- Internal implementation excluded
+Which pages should be included in the skill? (Enter numbers, or 'all')
+Any additional documentation URLs to add?"
 
-Which scope type fits your needs?"
+Wait for confirmation. Then skip to section 5 (Summarize Scope Decisions) with:
+- `scope.type: "docs-only"`
+- `scope.include`: confirmed doc URLs
+- `scope.notes: "Generated from external documentation. All content is T3 confidence."`
 
-Wait for user selection.
-
-### 3. Define Boundaries Based on Selection
-
-**If [F] Full Library:**
-
-"**Full Library scope selected.**
-
-Default inclusions:
-- All source files under {main source directory}
-- All public modules: {list from analysis}
-
-Default exclusions:
-- Test files (`**/*.test.*`, `**/*.spec.*`, `**/test/`, `**/tests/`)
-- Build artifacts (`**/dist/`, `**/build/`, `**/target/`)
-- Configuration files
-- Documentation source files
-
-Any additional exclusions you'd like to add? Or adjustments to these defaults?"
-
-**If [M] Specific Modules:**
-
-"**Specific Modules scope selected.**
-
-Here are the modules found in the analysis:
+**If `source_type: "source"` (default):** Continue to scope templates below.
 
-{numbered list of modules from step 02 with brief descriptions}
+### 2b. Offer Scope Templates
 
-Which modules would you like to include? (Enter numbers, comma-separated):"
+Load `{scopeTemplatesFile}` for the scope type options ([F], [M], [P]) and their descriptions.
 
-Wait for selection. Then:
+Present: "**How broadly should this skill cover the library?**" followed by the three scope type options from the loaded reference.
 
-"**Selected modules:**
-- {list selected modules}
+Ask: "Which scope type fits your needs?"
 
-For these modules, should I include:
-- **A)** Everything in those modules (all files)
-- **B)** Only public exports from those modules
-
-Any files or patterns to explicitly exclude within these modules?"
-
-**If [P] Public API Only:**
-
-"**Public API scope selected.**
-
-From the analysis, these appear to be the public entry points:
-
-{numbered list of exports/entry points from step 02}
-
-Which of these would you like to include? (Enter numbers, or 'all'):"
-
-Wait for selection. Then:
-
-"**Selected exports:**
-- {list selected exports}
+Wait for user selection.
 
-Exclusions will include all internal implementation files, tests, and utilities.
+### 3. Define Boundaries Based on Selection
 
-Any additional items you'd like to include or exclude?"
+Using the boundary definitions from `{scopeTemplatesFile}`, present the appropriate flow for the user's selected scope type ([F], [M], or [P]). Follow each type's prompts and wait for user input at each phase before proceeding.
 
 ### 4. Handle Language Override
 

package/src/workflows/brief-skill/steps-c/step-04-confirm-brief.md

@@ -67,7 +67,7 @@ Load `{briefSchemaFile}` to reference required fields and the human-readable pre
 Compile all gathered data from steps 01-03 into the complete brief:
 
 - **name:** {skill name from step 01}
-- **version:** "1.0.0" (default)
+- **version:** {auto-detected from source, or "1.0.0" if not found — see schema for detection rules}
 - **source_repo:** {target repo from step 01}
 - **language:** {detected/confirmed language from steps 02-03}
 - **description:** {derived from user intent in step 01}

package/src/workflows/brief-skill/steps-c/step-05-write-brief.md

@@ -72,8 +72,9 @@ Generate the YAML file using the approved field values and the schema template:
 ```yaml
 ---
 name: "{approved skill name}"
-version: "1.0.0"
-source_repo: "{approved source repo}"
+version: "{detected source version or 1.0.0}"
+source_type: "{source or docs-only}"
+source_repo: "{approved source repo or doc site URL}"
 language: "{approved language}"
 description: "{approved description}"
 forge_tier: "{approved forge tier}"
@@ -86,16 +87,67 @@ scope:
   exclude:
     - "{approved exclude patterns}"
   notes: "{approved scope notes or empty string}"
+# Include doc_urls when source_type is "docs-only" or when supplemental doc URLs were provided
+# doc_urls:
+#   - url: "{documentation URL}"
+#     label: "{page label}"
 ---
 ```
 
+**If `source_type: "docs-only"`:** Include `doc_urls` array (required). `source_repo` may be set to the doc site URL for reference or omitted. `source_authority` must be `community`.
+
+**If `doc_urls` were collected during scope definition (supplemental mode):** Include the `doc_urls` array even when `source_type: "source"`.
+
 ### 4. Write the File
 
 Write the generated YAML to `{forge_data_folder}/{skill-name}/skill-brief.yaml`.
 
 If write fails: **HALT** — "**Error:** Failed to write skill-brief.yaml. Please check that the directory is writable and try again."
 
-### 5. Display Success Summary
+### 5. QMD Collection Registration (Deep Tier Only)
+
+**IF forge tier is Deep AND QMD tool is available:**
+
+Index the skill brief into a QMD collection so that portfolio-level searches can find existing briefs and avoid duplicate skill creation across large monorepos.
+
+**Collection creation:**
+
+Create a QMD collection targeting only the brief file:
+```bash
+qmd collection add {forge_data_folder}/{skill-name} --name {skill-name}-brief --mask "skill-brief.yaml"
+qmd embed
+```
+
+If collection already exists (re-briefing): remove and recreate for atomic replace:
+```bash
+qmd collection remove {skill-name}-brief
+qmd collection add {forge_data_folder}/{skill-name} --name {skill-name}-brief --mask "skill-brief.yaml"
+qmd embed
+```
+
+**Registry update:**
+
+Read `{sidecar_path}/forge-tier.yaml` and update the `qmd_collections` array.
+
+If an entry with `name: "{skill-name}-brief"` already exists, replace it. Otherwise, append:
+
+```yaml
+  - name: "{skill-name}-brief"
+    type: "brief"
+    source_workflow: "brief-skill"
+    skill_name: "{skill-name}"
+    created_at: "{current ISO date}"
+```
+
+Write the updated forge-tier.yaml.
+
+**Error handling:**
+- If QMD collection creation fails: log the error. Do NOT fail the workflow — the brief file was already written successfully.
+- If forge-tier.yaml update fails: log the error, continue.
+
+**IF forge tier is NOT Deep:** Skip this section silently. No messaging.
+
+### 6. Display Success Summary
 
 "**Skill brief written successfully.**
 
@@ -123,7 +175,7 @@ After compilation, you can:
 
 **Brief-skill workflow complete.**"
 
-### 6. End Workflow
+### 7. End Workflow
 
 This is the final step. No next step file to load. The workflow is complete.
 
@@ -141,6 +193,8 @@ This is the FINAL step of the brief-skill workflow. After writing the file and d
 - Output directory created (or fallback used with notification)
 - skill-brief.yaml generated with all required fields matching approved values
 - File written successfully to correct location
+- Deep tier: QMD collection `{skill-name}-brief` created/updated and registered in forge-tier.yaml
+- Non-Deep tier: QMD indexing skipped silently
 - Success summary displayed with next steps recommendation
 - Workflow marked as complete
 
@@ -152,5 +206,6 @@ This is the FINAL step of the brief-skill workflow. After writing the file and d
 - Not creating output directory before writing
 - Not displaying next steps recommendation
 - Not handling write failure gracefully
+- Failing the workflow due to QMD indexing errors (should degrade gracefully)
 
-**Master Rule:** Skipping steps, optimizing sequences, or not following exact instructions is FORBIDDEN and constitutes SYSTEM FAILURE.
+**Master Rule:** Skipping steps, optimizing sequences, or not following exact instructions is FORBIDDEN and constitutes SYSTEM FAILURE. QMD indexing failures never block the workflow.

package/src/workflows/brief-skill/workflow.md

@@ -2,6 +2,7 @@
 name: brief-skill
 description: Scope and design a skill through guided discovery
 web_bundle: true
+installed_path: '{project-root}/_bmad/skf/workflows/skillforge/brief-skill'
 ---
 
 # Brief Skill
@@ -50,7 +51,7 @@ web_bundle: true
 
 Load and read full config from {project-root}/_bmad/skf/config.yaml and resolve:
 
-- `project_name`, `output_folder`, `user_name`, `communication_language`, `document_output_language`, `forge_data_folder`
+- `project_name`, `output_folder`, `user_name`, `communication_language`, `document_output_language`, `forge_data_folder`, `sidecar_path`
 
 ### 2. First Step Execution
 

package/src/workflows/create-skill/data/compile-assembly-rules.md

@@ -0,0 +1,110 @@
+# SKILL.md Compilation Assembly Rules
+
+## Frontmatter (REQUIRED — agentskills.io compliance)
+
+```yaml
+---
+name: {brief.name}
+description: >
+  {Trigger-optimized description from brief and extraction data.
+  Include what it does, when to use it, and what NOT to use it for.
+  1-1024 chars, optimized for agent discovery.}
+---
+```
+
+**Frontmatter rules:**
+
+- `name`: lowercase alphanumeric + hyphens only, must match the skill output directory name
+- `description`: non-empty, max 1024 chars, optimized for agent discovery
+- Only `name` and `description` in frontmatter — `version` and `author` go in metadata.json
+- No other frontmatter fields for standard skills (only `name`, `description`, `license`, `compatibility`, `metadata`, `allowed-tools` are permitted by spec)
+
+## Two-Tier Assembly
+
+**CRITICAL: Two-tier assembly.** SKILL.md must retain actionable inline content that survives `split-body` extraction. Assemble Tier 1 sections first (always inline), then Tier 2 sections (reference-eligible, may be extracted by split-body).
+
+### Tier 1 — Always Inline (must survive split-body)
+
+These sections form the essential standalone body. Target: **under 300 lines total** for Tier 1. An agent loading only SKILL.md (without references) must get enough to act.
+
+**Section 1 — Overview (~10 lines):**
+- 1-line summary of what the library does
+- Source repo, version, branch
+- Forge tier used for compilation
+- Export count and confidence summary
+
+**Section 2 — Quick Start (~30 lines):**
+- Select the 3-5 most commonly used functions (by import frequency or documentation prominence)
+- One runnable code example showing a typical end-to-end flow (e.g., `add → process → search`)
+- Minimal usage examples — ONLY from source tests or official docs
+- If no examples exist in source, show signature-only quick start
+- Provenance citation for each function
+
+**Section 3 — Common Workflows (~30 lines):**
+- 4-5 patterns showing typical function call sequences
+- Each pattern: 1-line bold description + function call chain with key params
+- Focus on the most common developer tasks, not exhaustive coverage
+- Format example:
+  ```
+  **Add and process data:**
+  `await cognee.add(data) → await cognee.cognify() → await cognee.search(query)`
+  ```
+
+**Section 4 — Key API Summary (~20 lines):**
+- Table of top 10-15 functions: name, purpose, key parameters
+- One row per function — no full signatures, just enough for discovery
+- Provenance citation per function
+
+**Section 4b — Migration & Deprecation Warnings (~10 lines, Deep tier only):**
+- Only populated when step-04 enrichment produced **T2-future** annotations (deprecation warnings, breaking changes, planned renames)
+- List each warning as a single-line bullet: function name, what changed or will change, source citation
+- Max 10 lines — just the actionable warnings, not full context
+- Link to Tier 2 Full API Reference for details: "See Full API Reference for migration details."
+- **Skip entirely** for Quick/Forge tiers or when no T2-future annotations exist — do not emit an empty section
+- This section survives split-body, ensuring agents always see critical migration context
+
+**Section 5 — Key Types (~20 lines):**
+- Most important enum/type definitions inline (e.g., SearchType values, config options)
+- Only types that appear in Quick Start or Common Workflows
+- Full type details go in Tier 2
+
+**Section 6 — Architecture at a Glance (~10 lines):**
+- Bullet list of major subsystem categories (e.g., "Graph DBs: Neo4j, Kuzu, Neptune")
+- Adapter/driver overview — what's available, not how it works
+- Skip for Quick tier or small libraries with < 5 modules
+
+**Section 7 — CLI (~10 lines, if applicable):**
+- Basic CLI commands if the library has a CLI interface
+- Skip if no CLI exists
+
+**Section 8 — Manual Sections:**
+- Seed empty `<!-- [MANUAL] -->` markers:
+```markdown
+<!-- [MANUAL:additional-notes] -->
+<!-- Add custom notes here. This section is preserved during skill updates. -->
+<!-- [/MANUAL:additional-notes] -->
+```
+- Place after Quick Start and after Key API Summary sections
+
+### Tier 2 — Reference-Eligible (can be extracted by split-body)
+
+Assemble Sections 9-11 (Full API Reference, Full Type Definitions, Full Integration Patterns) as defined in the skill-sections data file. These contain full detail and are split into `references/` when the body exceeds 500 lines. Include T2 annotations from enrichment in the Full API Reference (Deep tier only).
+
+**CRITICAL — Tier 2 differentiation from Tier 1:** Tier 2 Full API Reference must contain content that is NOT present in Tier 1's Key API Summary. Specifically:
+
+- **Full parameter tables** with types, defaults, and required/optional flags (Tier 1 only lists key params)
+- **Return value details** including structure, types, and error conditions
+- **T2 temporal annotations** — migration notes, deprecation details, breaking change context (Deep tier)
+- **Usage examples** from source tests or documentation (Tier 1 has signature-only references)
+- **Edge cases and constraints** — parameter validation rules, size limits, behavioral notes
+
+Do NOT repeat Tier 1's name/purpose/key-params table format in Tier 2. Tier 2 is a deep reference, not a reformatted summary. This distinction prevents conciseness scorers from flagging the two-tier design as redundancy.
+
+### Assembly Rules
+
+1. Assemble all Tier 1 sections first — these form the essential standalone body
+2. Assemble all Tier 2 sections after — these are progressive disclosure detail
+3. Tier 1 content MUST be under 300 lines (excluding frontmatter)
+4. If Tier 1 alone exceeds 300 lines, reduce Key API Summary and Architecture at a Glance
+5. Tier 1 sections are kept short enough that `split-body` targets the larger Tier 2 sections (`## Full ...` headings) instead
+6. After split-body, SKILL.md must still contain all Tier 1 sections with actionable content