ln-160-docs-skill-extractor

Paths: File paths (references/, ../ln-*) are relative to this skill directory.

ln-160-docs-skill-extractor

Type: L2 Coordinator Category: 1XX Documentation Pipeline Workers: ln-161-skill-creator, ln-162-skill-reviewer

Scans project documentation, identifies procedural content, and extracts it into executable slash command files under .claude/commands/*.md. Declarative documentation stays in markdown; this skill only routes procedural sections into command form.

---

Overview

Aspect	Details
Input	Project docs, test docs, and optional doc registry
Output	.claude/commands/*.md files in target project
Workers	ln-161 creates commands, ln-162 reviews them
Source policy	Docs-first extraction; AGENTS.md and CLAUDE.md are routing-only

---

Workflow

Phase 1: Discovery (route docs, build inventory)
    |
Phase 2: Classification (procedural vs declarative scoring)
    |
Phase 3: Extraction Plan (user approval)
    |
Phase 4: Delegate -> ln-161 (create commands)
    |
Phase 5: Delegate -> ln-162 (review commands)
    |
Phase 6: Report (aggregate results)

---

Phase 1: Discovery

MANDATORY READ: Load references/procedural_extraction_rules.md, references/markdown_read_protocol.md, and references/docs_quality_contract.md

Build a docs-first inventory before extracting anything.

Routing Sources

Use these files only to route discovery and prioritize reading:

• AGENTS.md
• CLAUDE.md
• docs/project/.context/doc_registry.json if present

Do not extract commands from routing sources.

Extraction Sources

Scan only these sources for procedural content:

• docs/**/*.md
• tests/README.md
• tests/manual/**/*
• README.md
• CONTRIBUTING.md

Also scan:

• .claude/commands/*.md to avoid duplicate command creation

Discovery Rules

1. If docs/project/.context/doc_registry.json exists, prioritize:
   • canonical docs first
   • DOC_KIND=how-to before reference
   • reference before index and explanation
2. Read markdown with the shared section-first protocol:
   • use outline first for large or unfamiliar files
   • read header markers and top sections first
   • expand only sections that might contain procedures
3. Ignore standard doc shell sections as extraction candidates:
   • Quick Navigation
   • Agent Entry
   • Maintenance
   • header markers such as SCOPE, DOC_KIND, DOC_ROLE, READ_WHEN, SKIP_WHEN, PRIMARY_SOURCES

Build contextStore

contextStore:
  project_root: {CWD}
  routing_sources:
    agents_md: true
    claude_md: true
    doc_registry: true
  existing_commands: [list of .claude/commands/*.md filenames]
  doc_inventory:
    - file: docs/project/runbook.md
      doc_kind: how-to
      doc_role: canonical
      sections:
        - header: "Deployment"
          line_range: [45, 92]
          signals: { code_blocks: 3, numbered_steps: 5, imperative_verbs: 8 }

---

Phase 2: Classification

Score each candidate section with the shared procedural extraction rules.

Classification	Condition	Action
PROCEDURAL	proc >= 4 and proc > decl * 2	Extract to command
DECLARATIVE	decl >= 4 and decl > proc * 2	Keep as documentation
MIXED	Both >= 3	Extract procedural subsection only
THIN	Both < 3	Skip

Filter:

• drop sections already covered by an existing .claude/commands/*.md
• drop standard doc shell sections
• prefer DOC_KIND=how-to when multiple sections overlap semantically

---

Phase 3: Extraction Plan (User Approval Gate)

Present the classified result set to the user before creating files.

Found {N} procedural sections in {M} files:

| # | Source | DOC_KIND | Section | Score | Proposed Command |
|---|--------|----------|---------|-------|------------------|
| 1 | runbook.md | how-to | Deployment | P:8/D:1 | deploy.md |
| 2 | tests/README.md | index | Running Tests | P:7/D:2 | run-tests.md |

Existing .claude/commands/ (will skip): refresh_context.md, build-and-test.md

Include? (e.g., "1,2" or "all" or "all skip 2")

If the user approves nothing, stop with No skills to create.

---

Phase 4: Delegate to ln-161 (Skill Creation)

Pass only approved sections to ln-161-skill-creator.

Agent(
  description: "Create commands from procedural docs",
  prompt: "Execute skill creator.\nStep 1: Invoke:\n  Skill(skill: \"ln-161-skill-creator\")\nCONTEXT:\n{approved_sections}",
  subagent_type: "general-purpose"
)

Normalized payload:

{
  "approved_sections": [
    {
      "source_file": "docs/project/runbook.md",
      "section_header": "Deployment",
      "line_range": [45, 92],
      "command_name": "deploy.md",
      "doc_kind": "how-to",
      "doc_role": "canonical"
    }
  ]
}

Collect:

• created file paths
• source-to-command mapping
• per-command summary

---

Phase 5: Delegate to ln-162 (Skill Review)

Pass created command paths to ln-162-skill-reviewer in COMMAND mode.

Agent(
  description: "Review created commands",
  prompt: "Execute skill reviewer in COMMAND mode.\nStep 1: Invoke:\n  Skill(skill: \"ln-162-skill-reviewer\", args: \"commands\")\nFILES: {list of created paths}",
  subagent_type: "general-purpose"
)

Collect:

• verdict per file
• aggregate pass/fix/warn counts

---

Phase 6: Report

Aggregate the create and review results.

## Docs Skill Extractor -- Complete

| Metric | Count |
|--------|-------|
| Documents scanned | {N} |
| Sections analyzed | {N} |
| Procedural found | {N} |
| Commands created | {N} |
| Commands skipped (existing) | {N} |
| Review PASS | {N} |
| Review FIXED | {N} |
| Review WARN | {N} |

Created commands:
- .claude/commands/deploy.md (from runbook.md#Deployment)
- .claude/commands/run-tests.md (from tests/README.md#Running Tests)

---

Critical Rules

• Docs-first extraction: Extract only from docs sources. AGENTS.md and CLAUDE.md route discovery but never become command sources.
• Section-first reading: Use the shared markdown read protocol before full-file reads.
• Detect before extract: Only extract sections classified as procedural.
• No duplicates: Skip sections already covered by existing .claude/commands/*.md.
• User approval required: Never create commands without Phase 3 confirmation.
• Delegate creation: All command file writing goes through ln-161.
• Delegate review: All command validation goes through ln-162.
• Preserve docs: Source documentation stays intact.

---

TodoWrite format (mandatory):

- Build docs inventory (in_progress)
- Invoke ln-161-skill-creator (pending)
- Invoke ln-162-skill-reviewer (pending)
- Aggregate report (pending)

Worker Invocation (MANDATORY)

Host Skill Invocation: Skill(skill: "...", args: "...") is mandatory delegation.

• Claude: call the Skill tool exactly as shown.
• Codex: if no Skill tool exists, locate the named skill in available skills, read its SKILL.md, treat args as $ARGUMENTS, execute that skill workflow, then return here with its result/artifact.
• Do not inline worker logic or mark the worker complete without executing the target skill.

Phase	Worker	Context
4	ln-161-skill-creator	Approved procedural sections with source metadata
5	ln-162-skill-reviewer	Created command file paths in COMMAND mode

All workers: Invoke via Skill tool. Workers consume only the context they need.

Definition of Done

• Routing sources checked (AGENTS.md, CLAUDE.md, doc registry if present)
• Extraction inventory built from docs-first sources
• Every candidate section classified
• User approved extraction plan
• ln-161 created all approved commands
• ln-162 reviewed all created commands
• Final report aggregated with scan, create, and review metrics

---

Meta-Analysis

Optional reference: load references/meta_analysis_protocol.md only when the user asks for post-run meta-analysis or protocol-formatted run reflection.

Skill type: planning-coordinator. When requested, run after Phase 6 completes. Output to chat using the planning-coordinator format.

---

Version: 1.0.0 Last Updated: 2026-03-26