# Mk Docs

> Analyze codebase and manage project documentation. Use for doc initialization, updates, summaries, codebase analysis.

- Skill: `phuc-nt/mk-docs-2` (Agent Skill)
- Install (CLI): `npx skillmds@latest add phuc-nt/mk-docs-2`
- Raw SKILL.md: https://api.skillmd.com/api/skills/phuc-nt/mk-docs-2/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Docs & Writing
- Author: phuc-nt (https://skillmd.com/u/phuc-nt)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/phuc-nt/mk-docs-2

---

# mk-docs

Kit skill `docs` (full text inlined from `.claude/skills/docs/SKILL.md`). Relative paths it mentions (`references/`, `scripts/`, `bin/`, `assets/`) resolve from `.claude/skills/docs/`. Where it says to invoke another `/mk-*` skill, read `.kiro/skills/<that-skill>/SKILL.md`.

Argument hint: `init|update|summarize`

Request / arguments: $ARGUMENTS

---

# Documentation Management

Analyze codebase and manage project documentation through scouting, analysis, and structured doc generation.

**IMPORTANT:** Invoke "/mk-project-organization" skill to organize the outputs.

## Default (No Arguments)

If invoked without arguments, use `AskUserQuestion` to present available documentation operations:

| Operation | Description |
|-----------|-------------|
| `init` | Analyze codebase & create initial docs |
| `update` | Analyze changes & update docs |
| `summarize` | Quick codebase summary |

Present as options via `AskUserQuestion` with header "Documentation Operation", question "What would you like to do?".

## Subcommands

| Subcommand | Reference | Purpose |
|------------|-----------|---------|
| `/mk-docs init` | `references/init-workflow.md` | Analyze codebase and create initial documentation |
| `/mk-docs update` | `references/update-workflow.md` | Analyze codebase and update existing documentation |
| `/mk-docs summarize` | `references/summarize-workflow.md` | Quick analysis and update of codebase summary |

When another workflow needs to decide whether docs should change, load
`references/documentation-management.md` before invoking a docs update.

## Routing

Parse `$ARGUMENTS` first word:
- `init` → Load `references/init-workflow.md`
- `update` → Load `references/update-workflow.md`
- `summarize` → Load `references/summarize-workflow.md`
- empty/unclear → AskUserQuestion (do not auto-run `init`)

## Shared Context

Documentation lives in `./docs` directory:
```
./docs
├── project-overview-pdr.md
├── code-standards.md
├── codebase-summary.md
├── design-guidelines.md
├── deployment-guide.md
├── system-architecture.md
└── project-roadmap.md
```

Use `docs/` directory as the source of truth for documentation.

When authoring or refreshing diagrams in `system-architecture.md`, use the `archify` skill for publish-grade output: validated architecture / workflow / sequence / dataflow / lifecycle diagrams delivered as self-contained interactive HTML (dark/light themes, PNG/SVG export). Author a small typed JSON spec, then `node .claude/skills/archify/bin/archify.mjs deliver <type> <spec.json> <output.html>`. For quick inline sketches, plain mermaid code fences in markdown are fine.

**Embedding a diagram inside the Markdown doc.** The delivered HTML does not render inside a `.md` file — GitHub, VS Code preview, MkDocs and Obsidian all strip `<script>`/`<style>`, so an iframe or raw HTML embed shows nothing and the reader has to open a separate file. Export a standalone SVG instead and reference it as a normal image:

```bash
node .claude/skills/archify/bin/archify.mjs deliver architecture spec.json docs/diagrams/x.html
node .claude/skills/archify/bin/to-svg.mjs docs/diagrams/x.html docs/diagrams/x.svg
```

```markdown
![System architecture](diagrams/x.svg)
```

The SVG keeps the theme the HTML was delivered in, renders inline everywhere, and stays diffable in git. Ship **both** when the diagram benefits from the viewer: the SVG inline for reading, plus a line linking the HTML for the interactive version (guided views, present mode, export). The SVG drops that interactive chrome by design — it is the diagram only.

**IMPORTANT**: **Do not** start implementing code.