cm-dockit

CM DocKit: Knowledge Systematization Engine

A professional knowledge systematization engine powered by codebase analysis and UX design principles. One source scan = one complete knowledge base — Personas, JTBD, Process Flows, Technical Docs, SOPs, API Reference. Supports plain Markdown output or a premium VitePress site. Includes SEO optimization, sitemap generation, and AI/LLM-readable content.

When to Activate

• User asks to "create documentation", "generate docs"
• User mentions "SOP", "user guide", "manual"
• User wants technical docs from a codebase
• User runs /DocKit Master

Document Types

Type	Skill File	Description
knowledge	skills/persona-builder.md + skills/jtbd-analyzer.md + skills/flow-mapper.md (files pending)	Personas, JTBD, Process Flows — knowledge foundation
tech	skills/tech-docs.md	Architecture, database, deployment, data flow
sop	skills/sop-guide.md	Step-by-step user guides (enriched with knowledge)
api	skills/api-reference.md	API endpoint reference with examples
all	All above	Full knowledge base + documentation suite

Support Skill	File	Purpose
SEO Checklist	skills/seo-checklist.md	Per-page SEO audit (title, meta, headings, robots)
Content Writing	skills/content-writing.md	SEO copywriting, keywords, active voice, FAQ
LLM Optimization	skills/llm-optimization.md	AI-readable structure, NotebookLM-friendly

Output Formats

Format	Workflow	Description
markdown	workflows/export-markdown.md	Plain .md files in docs/ folder
vitepress	workflows/setup-vitepress.md	Premium VitePress static site (default) — built-in Mermaid, search, dark mode

Procedure

Step 1: Gather Input (Single Consolidated Prompt)

CRITICAL: Ask ALL questions in ONE message. Do NOT ask one at a time. Present the following intake form to the user, using this 📚 DocKit Master — Configuration

Please answer the following questions so I can automatically create an execution plan:

#	Question	Options	Default
1	📑 Document type?	knowledge · tech · sop · api · all	all
2	🎨 Output format?	markdown (plain) · vitepress (premium site)	vitepress
3	📂 Code scan scope?	full (entire project) · focused (specific folder/feature)	full
4	🎯 Focus area? (only if focused)	Folder name, module, or specific feature	—
5	🌏 Writing language?	Auto-detect from chat language (see below)	auto-detect
6	🌐 Add multi-language?	yes (add English + source language) · no	no
7	📹 Record video demo?	yes (record browser walkthrough) · no	no
8	📁 Project path?	(absolute path)	current workspace
9	🔍 SEO optimization?	yes (SEO frontmatter + checklist + sitemap) · no	yes
10	🤖 Optimize for AI/LLM?	yes (AI-readable + NotebookLM sitemap) · no	yes

You can answer briefly, e.g.: "all, vitepress, full, yes, no, yes, yes"

🌏 Smart language rules:

1. Auto-detect: Determine default language from the user's chat language
   • User chats in Vietnamese → default vi
   • User chats in Chinese → default zh
   • User chats in Japanese → default ja
   • User chats in English → default en
   • (Applies similarly for any other language)
2. Multi-language (yes): Automatically add English (en) as secondary language
   • Example: Vietnamese user + multi-language → vi + en
   • Example: Chinese user + multi-language → zh + en
   • If user already chats in English + multi-language → ask which secondary language
3. Override: User can override by specifying explicitly, e.g.: "write in Japanese"

---

Step 1b: Auto-Generate Execution Plan

After receiving answers, immediately create an execution plan (do NOT ask more questions).

Map the answers to this execution config:

DOC_TYPE     = [knowledge | tech | sop | api | all]
FORMAT       = [markdown | vitepress]
SCOPE        = [full | focused]
FOCUS_TARGET = [directory/module name if focused, else null]
LANGUAGE     = [vi | en | vi+en]
I18N         = [yes | no] (only relevant for vitepress)
RECORD       = [yes | no]
PROJECT_PATH = [absolute path]
SEO          = [yes | no] (default: yes)
LLM_OPTIMIZE = [yes | no] (default: yes)

Then present the plan to user as a checklist artifact, like:

## 🚀 Execution Plan

- [ ] Scan code: [full/focused → target]
- [ ] Generate documents: [type] in [language]
- [ ] Export format: [markdown/vitepress]
- [ ] [If vitepress + i18n] Configure multi-language
- [ ] [If record] Record video walkthrough
- [ ] [If seo] Run SEO checklist + generate sitemap
- [ ] [If llm_optimize] Apply LLM optimization rules
- [ ] Review and deliver

After presenting the plan → proceed to Step 2 immediately (auto-execute). Do NOT wait for approval unless the plan has ambiguity.

Step 2: Analyze Codebase

Read and follow skills/analyze-codebase.md in this directory.

Output: structured analysis saved to docs/analysis.md (NOT _analysis.md) including:

• Project type, languages, frameworks
• Directory structure and architecture layers
• Entry points, routes, database schema
• Key business logic modules
• Dependencies overview
• Test coverage

Step 3: Apply Content Guidelines

MANDATORY — Read skills/content-guidelines.md before generating any content.

Key rules to enforce:

• Filenames: kebab-case, no underscores, no dots
• Frontmatter: Every .md file must have title, description, keywords, robots
• Quick Reference: Every doc starts with a summary box
• Progressive Disclosure: Use <details> for advanced content
• Admonitions: Use :::tip, :::info, :::warning, :::danger for callouts
• Mermaid: NO hardcoded colors — VitePress auto-adapts to light/dark
• Code Groups: Use :::code-group for multi-platform examples
• Internal Links: ≥2 cross-links per page

Step 3b: Apply SEO & LLM Guidelines (If enabled)

If SEO = yes: Read skills/content-writing.md for:

• Keyword placement (title, H1, first paragraph, H2s, meta)
• Inverted pyramid structure (answer first, details later)
• Active voice (≥80%), transition words (≥30%)
• FAQ in schema-ready format for rich snippets

If LLM_OPTIMIZE = yes: Read skills/llm-optimization.md for:

• Clean heading hierarchy (no skipped levels)
• Text descriptions alongside all Mermaid diagrams
• Self-contained sections (≤500 words per H2)
• Consistent terminology (glossary section in index)
• UTF-8 clean output

Step 4: Generate Documents

Based on the chosen type, read and follow the corresponding skill file:

• knowledge → Run 3 skills sequentially:

  1. Read skills/persona-builder.md → docs/personas/ (Buyer & User Personas)
  2. Read skills/jtbd-analyzer.md → docs/jtbd/ (JTBD Canvases)
  3. Read skills/flow-mapper.md → docs/flows/ (Workflow, Sequence, Lifecycle, Journey)

• tech → Read skills/tech-docs.md, generate:

  • docs/architecture.md — System architecture + ADR
  • docs/database.md — Database schema & data model
  • docs/deployment.md — Deployment & infrastructure
  • docs/data-flow.md — Data flow diagrams

• sop → Auto-run knowledge first if not yet generated, then:

  • Read skills/sop-guide.md, generate:
  • docs/sop/ — One .md per feature/module
  • Each file: Persona Context → Process Flow → Steps → Journey → Troubleshooting → FAQ

• api → Read skills/api-reference.md, generate:

  • docs/api/ — Organized by resource
  • Each file: Quick Ref → Endpoints table → Multi-language examples

• all → Run knowledge → tech → sop → api sequentially

Step 5: Export

Based on the chosen format, read and follow the corresponding workflow:

• markdown → Read workflows/export-markdown.md

  • Create docs/README.md as index
  • Organize into clean folder structure

• vitepress → Read workflows/setup-vitepress.md

  • Scaffold VitePress with premium template
  • Auto-sidebar from folder structure
  • Built-in Mermaid, search, dark mode
  • Build and verify

Step 5b: Generate Sitemap (If SEO = yes)

Read and follow workflows/generate-sitemap.md:

• VitePress: Sitemap auto-generated via sitemap config option. Generate robots.txt, extract sitemap-urls.txt
• Markdown: Generate docs/sitemap.md (link index) + docs/sitemap-urls.txt
• Both formats produce a NotebookLM-ready URL list for AI research

Step 5c: Run SEO Audit (If SEO = yes)

Read skills/seo-checklist.md and audit every generated page:

• Title (50–60 chars, keyword) ✔️
• Meta description (150–160 chars) ✔️
• Single H1, no skipped levels ✔️
• ≥2 internal links ✔️
• Robots directive set ✔️
• All images have alt text ✔️

Step 6: Summary

Present to user:

• List of generated files with sizes
• How to view/serve the docs
• Next steps (customize, deploy, etc.)

If generated docs > 30 files, also suggest:

💡 **Pro Tip: Deep Search**

The documentation set just created has [X] files. You can index them using
[qmd](https://github.com/tobi/qmd) for semantic search by AI
across all future sessions:

\`\`\`bash
npm install -g @tobilu/qmd
qmd collection add ./docs --name project-docs
qmd context add qmd://project-docs "Project documentation for [project-name]"
qmd embed
\`\`\`

See also: `cm-deep-search` skill.

CLI Quick Start

For a fast interactive experience, users can run the doc generation script from the skill root:

# Run from the cm-dockit skill directory
bash scripts/doc-gen.sh

Note: The scripts/ directory and doc-gen.sh script need to be created. For now, trigger this skill by invoking cm-dockit directly via the AI assistant.

UX Principles Applied

UX Law	Application
Hick's Law	≤7 TOC items, progressive disclosure for advanced content
Miller's Law	Information chunked into groups of 5-9
Doherty Threshold	Tables for structured data, scannable summaries
Jakob's Law	Standard doc layout (sidebar + content + TOC)
Fitts's Law	Touch-friendly navbar links (≥44px)
WCAG 2.1 AA	Focus-visible rings, high contrast, reduced motion

Constraints

• All Mermaid diagrams use NO hardcoded inline styles — VitePress theming handles light/dark
• Every technical claim cites (file_path:line_number)
• SOP docs use <details> for troubleshooting (progressive disclosure)
• All generated files include YAML frontmatter with title, description
• Pure Markdown — no MDX, no special escaping needed
• No underscore-prefixed filenames — breaks auto-sidebar detection
• VitePress output must pass npx vitepress build without errors
• SEO default: robots: "index, follow" unless page is internal/draft
• ≥2 internal links per page (never orphan pages)
• Text fallback for every Mermaid diagram (LLM readability)
• Self-contained sections — each H2 makes sense read alone
• sitemap-urls.txt generated for NotebookLM import

CM DocKit Development Rules

If you are an AI agent asked to modify or upgrade this skill (CM DocKit):

1. Test Gate Enforcement: You MUST run the backend test suite located in the cm-dockit skill directory by executing $ npm run test:gate or $ vitest. Do NOT claim "task completed" unless tests pass.
2. Boilerplate Integrity: If modifying templates/vitepress-premium, ensure the frontend test suite (tests/frontend.test.ts) still works.
3. No Direct Copying: Never hardcode file-copy commands that copy [project_root]/docs/ content into docs-site/. Always rely on srcDir: '../docs' in config.mts.