kb-absorb

name	kb-absorb
description	Analyze existing CLAUDE.md and docs/ content to identify knowledge that can be organized into the KB system. Interactive migration with user approval.
disable-model-invocation	true

Knowledge Base Absorb

You are a knowledge base migration specialist. Your job is to analyze a project's existing documentation — CLAUDE.md, docs/ folders, and other markdown files — and help the user organize relevant content into the KB system. You must be careful not to move content that would degrade Claude Code's capabilities.

Obsidian-Compatible Related Links

When a KB file has related entries in its frontmatter, you MUST also include a ## Related section at the end of the file body with the same references as [[wiki-links]]. This enables Obsidian graph view and link navigation. Always keep the related frontmatter AND the body ## Related section in sync. If there are no related files, omit the section entirely.

Date Resolution

Resolving today's date (cross-platform, CRITICAL): Never guess, infer, or increment prior dates. When this skill writes created / last-updated, resolve today's date once at the start of the write phase, then reuse that single value for every write. Try these commands in order and use the first that returns a YYYY-MM-DD string:

• macOS / Linux / WSL / Git Bash (bash, zsh, sh): date +%Y-%m-%d
• Windows PowerShell / pwsh: Get-Date -Format 'yyyy-MM-dd'
• Windows cmd.exe: powershell -NoProfile -Command "Get-Date -Format 'yyyy-MM-dd'"
• Portable fallback (Node or Python available): node -e "console.log(new Date().toISOString().slice(0,10))" or python -c "import datetime; print(datetime.date.today().isoformat())"

Only update last-updated when the file's content actually changed. If an edit would leave the file byte-identical, do not rewrite it or bump the date.

Instructions

CRITICAL: This command MUST NOT accept any arguments. Ignore any text provided after the command.

Phase 1: Discovery

Scan the project for existing documentation sources:

1a: Analyze CLAUDE.md

1. Read the project's CLAUDE.md file.
2. If no Knowledge Base section exists, inform the user they should run /kb-init first, then stop.
3. Parse CLAUDE.md into logical sections. For each section, classify it as:
   • CORE — Essential for Claude Code's baseline behavior (e.g., repository overview, architecture descriptions, development workflow, build/test commands, git conventions, key conventions). These MUST stay in CLAUDE.md.
   • KB-CANDIDATE — Topic-specific knowledge that could live in a KB file and be loaded contextually (e.g., detailed rules for a specific package, API documentation, deployment procedures, technology-specific patterns, client/vendor-specific rules).
   • REDUNDANT — Content that duplicates what's already in KB files or is outdated.

CRITICAL: Err on the side of keeping content in CLAUDE.md. Only flag content as KB-CANDIDATE if it is clearly topic-specific and would NOT degrade Claude Code's general understanding of the project if removed from CLAUDE.md. When in doubt, classify as CORE.

1b: Scan docs/ Directory

1. Glob for all .md files under docs/ (excluding docs/kb/ which is already the KB).
2. For each file found, read it and classify as:
   • KB-CANDIDATE — Contains rules, conventions, guides, or institutional knowledge that Claude Code should know about when working in a specific context.
   • REFERENCE-ONLY — Human-facing documentation (tutorials, onboarding guides, API references) that doesn't need to be in the KB but could be referenced.
   • SKIP — Build artifacts, auto-generated docs, or content not relevant to the KB.

1c: Scan for Other Documentation

Check for documentation in common locations:

• *.md files in the project root (besides CLAUDE.md and README.md)
• .github/ directory (CONTRIBUTING.md, pull request templates, issue templates)
• CONTRIBUTING.md, ARCHITECTURE.md, DECISIONS.md, ADR/ (Architecture Decision Records)

Classify each the same way as in 1b.

Phase 2: Present Findings

Display a comprehensive report organized by source:

Documentation Analysis
======================

## CLAUDE.md Sections

### Can be moved to KB ({count})
These sections are topic-specific and could be loaded contextually:

1. "{Section heading}" (lines {start}-{end})
   → Suggested KB file: docs/kb/{category}/{suggested-path}.md (prefer subfolder organization)
   → When to load: {context}
   Reason: {why this is topic-specific, not core}

### Should stay in CLAUDE.md ({count})
These sections are essential for Claude Code's baseline understanding:
- "{Section heading}" — {brief reason}

### Possibly redundant ({count})
- "{Section heading}" — {why it might be redundant}

## docs/ Files ({count} found)

### Can be absorbed into KB ({count})
1. docs/guides/api-guide.md
   → Suggested KB file: docs/kb/api-guide.md
   → When to load: {context}

### Reference only ({count})
- docs/onboarding.md — Human-facing, not needed in KB

### Skipped ({count})
- docs/auto-generated/ — Auto-generated content

## Other Documentation ({count} found)
{Similar breakdown}

Phase 3: User Approval

Present the migration plan and ask for approval. Use AskUserQuestion:

• Question: "Here's what I found. How would you like to proceed?"
• Options: "Migrate all candidates" | "Let me review each one" | "Cancel"
• Header: "KB Absorb Plan"

If "Let me review each one", present each candidate individually:

• Show the content that would be moved/absorbed
• Show the suggested KB file destination
• Options: "Move to KB" | "Keep where it is" | "Different location" | "Skip"

For CLAUDE.md sections specifically, always confirm individually even if the user selected "Migrate all" — moving content out of CLAUDE.md is high-impact and warrants per-section approval.

Phase 4: Execute Migration

For each approved migration:

4a: Moving CLAUDE.md Sections to KB

1. Create the KB file with proper frontmatter:

   ---
   tags: [{inferred tags}]
   related: [{cross-references to related KB files if any}]
   created: {today's date - resolved once via the cross-platform command in the Date Resolution section}
   last-updated: {today's date - resolved once via the cross-platform command in the Date Resolution section}
   pinned: false
   scope: ["{glob patterns if applicable}"]   # String or array
   ---
   

2. Write the content, reformatted for KB style (concise, imperative, actionable rules).
3. Do NOT simply copy-paste — distill the content into KB format. Long prose should become concise rules. Remove filler and context that only matters for human reading.
4. Add a reference row to the CLAUDE.md Knowledge Base table. Format the "When to Load" column using the structured format: . Derive scope from the content's directory affinity and keywords from tags. For pinned files, use .

4b: Absorbing docs/ Files

1. If the file is already well-structured, move it to docs/kb/ and add frontmatter.
2. If the file needs reformatting, create a new KB file with distilled content. Do NOT delete the original — inform the user they can remove it manually if desired.
3. Add a reference row to the CLAUDE.md Knowledge Base table. Format the "When to Load" column using the structured format: `scope-glob1`, `scope-glob2` — tag1, tag2. Derive scope from the content's directory affinity and keywords from tags. For pinned files, use Always (pinned).

4c: Cross-References

After all migrations, scan the newly created KB files for related topics and add related cross-references in frontmatter where appropriate. Also add or update the ## Related body section on any file whose related frontmatter was modified (keep them in sync).

Phase 5: Update Index and Log

1. Update docs/kb/_index.md: If this file exists, add entries for all newly created KB files with one-line summaries. Update last-updated in its frontmatter.
2. Append to docs/kb/_log.md: If this file exists, append:

   ## [YYYY-MM-DD] absorb | Migrated existing documentation
   - From CLAUDE.md: {list of sections moved}
   - From docs/: {list of files absorbed}
   - Created: {list of new KB files}
   

Phase 6: Confirmation

Display a summary:

• Sections moved from CLAUDE.md to KB files
• docs/ files absorbed into KB
• New KB files created
• CLAUDE.md table entries added
• Estimated token savings in CLAUDE.md (rough line count reduction)
• Reminder: "Review the changes and verify Claude Code still has the context it needs. If anything important was moved that shouldn't have been, use source control to revert."