name: create-docs

description: Analyze any codebase and generate an Obsidian-ready knowledge vault (AGENTS.md, specs/, per-domain business-logic notes, integrations, rules), language- and framework-agnostic. Discovers every functional domain, extracts its core business logic (calculations, dates, thresholds, states, configuration) with code citations, and verifies each rule against the code. Use when the user asks to create docs, generate documentation, document the project or a domain, build an Obsidian vault from code, or set up AGENTS.md. Use ONLY when the task is about generating project documentation, not for writing app code docs inline.

Create Docs

Analyze a codebase and create a structured, verified documentation vault for Obsidian that other agents and colleagues query through an Obsidian MCP server.

Locations

The vault and the codebase are separate:

source=<path> — the codebase. Read-only: never create, edit or delete any file in it (no AGENTS.md, no specs/, no notes). Default: current working directory.
vault=<path> — the Obsidian vault, outside the codebase. Every file this skill writes goes here. Required: terminate if missing or if it resolves inside source.

All paths below (AGENTS.md, specs/…) are relative to vault. All path:line citations and sources entries are relative to source.

Params

This skill needs exactly one of these modes (plus source / vault):

new — create AGENTS.md and the vault structure (inventory first, then domains).
review — read and follow directions in specs-reviewer.md to review and update the docs.
domain <name> — deep-dive a single domain from the inventory and write/update only its notes.
continue — process the next todo domains of the inventory (resume after an interruption).

Terminate if the user does not provide one of these modes.

Process

Detect existing docs — if the vault already has notes, UPDATE in place: preserve content that is still accurate, add missing sections, remove stale references. Do NOT recreate from scratch unless the user explicitly asks for a full regeneration. In an existing vault:
- Generated notes — notes produced by scripts (declared in the vault's AGENTS.md, marked GENERATED, or written by generators in the vault's tools folder) are never hand-edited: a regeneration would overwrite the change. Link to them instead.
- Existing AGENTS.md — keep its audience, language and structure; only add entries pointing to new notes.
- Existing conventions — follow the vault's link style, folder layout and note naming; do not convert existing notes to a different format.
Scan the codebase — directory structure, project/build manifests of any ecosystem (package.json, .csproj/.vbproj/*.sln, pom.xml, go.mod, composer.json, Cargo.toml, …), config files, entry points, source and test directories, CI/CD configs, database scripts.
Identify — tech stack, architecture pattern, entry points, UI/API/job surfaces, persistence, lint/format config, build scripts, deploy targets, external integrations, trust boundaries.
Inventory domains — build specs/domains/domain-inventory.md (see Domain discovery) before writing any domain note.
Deep-dive domains — process inventory domains one at a time (see Domain deep-dive). Never document all domains in a single shallow pass; depth per domain beats breadth.
Verify — every domain note passes Verification before its status becomes verified.
Link — update MOC notes and cross-links (see Obsidian format).
Do NOT invent anything — base everything exclusively on existing code.
Language — all documentation in English; domain terms found in the UI or data keep their original wording (quoted) and go into aliases.

1. `AGENTS.md` in the vault root

Entry file for agents querying the vault. If it already exists, see Process step 1. A new one contains:

Project Overview — project name and 1-2 line description
Tech Stack — technologies used (framework, languages, main libraries)
Architecture — folder structure, entry points, main architectural pattern
Commands — dev, build, test, deploy, lint commands (most used, inline)
Code Style — preferred syntax, naming convention, formatting
Coding Rules — critical conventions the agent must respect (max 5-8 bullets, only non-obvious things)
Design System — tokens, UI libraries, component patterns (only if a frontend exists)
Constraints / What to avoid — things the agent must never do in this project
Workflow — operational order (e.g. typecheck after changes, single tests not full suite)
Self-maintenance rule: > "When the codebase changes, run create-docs review to re-verify the affected notes"
References — list of specs/ notes with a brief description of each

AGENTS.md must be short and scannable — for every line ask: "if I remove this, would the agent make mistakes?" — if no, cut it.

2. Domain discovery

A domain is a functional subsystem with its own data and non-obvious business rules (e.g. billing, scheduling, training compliance, inventory). Utilities, type-only modules and thin wrappers are NOT domains.

Combine these language-agnostic signals to find domains:

Signal	Where to look
Functional folder / module / namespace names	directory tree, project files
Persistent entities	tables, ORM models, migrations, SQL scripts, stored procedures
User-facing surfaces	menus, forms/screens, routes, API groups, reports
Configuration	option/setting keys, feature flags, per-tenant or per-customer switches
Scheduled / batch work	jobs, recalculation routines, imports/exports
Vocabulary	recurring domain terms in identifiers, UI labels, resource/translation files

Write specs/domains/domain-inventory.md with one row per domain:

Tier — 1 heavily customized core logic / 2 business logic with boilerplate / 3 standard framework usage / 4 thin or generated / 5 reference-only. When uncertain, default to Tier 2.
Status — todo → draft → verified (or blocked: <reason>).
Order rows by Tier, then by size. Deep-dive Tier 1 and 2; Tier 3-5 get only the inventory summary.

3. Domain deep-dive

For each domain, in order:

Locate — search (rg) the domain keywords, including localized UI labels, in code, constants, option keys, resources and SQL.
Find logic hotspots — code that decides or computes something:
- date arithmetic, deadlines, validity periods, cut-off dates
- thresholds, percentages, quantities, scoring
- status assignment and state transitions
- validations and eligibility/exemption rules
- branching on configuration, feature flags, tenant/customer codes
- SQL/queries that compute values (including SQL built in strings) Rank hotspots by number of branches, hard-coded constants and inbound references; read the top ones first.
Trace — follow each flow end-to-end: surface (UI/API/job) → configuration read → computation → persistence. Read only the relevant blocks of large files.
Active code only — ignore commented-out code and unreachable branches. Comments may explain active code, but never document a rule found only in commented-out code.
Extract — write each computation as numbered steps: inputs → conditions/thresholds → output.
Cite — every business rule ends with its source as path:line (repo-relative).
Behavior, not norm — describe what the code does, not what laws, standards or specs say it should do. If they appear to differ, record it under Inconsistencies; never "fix" it in the doc.

Domain note: `specs/domains/<domain>.md`

Main note of the domain (hub). If it grows beyond ~300 lines, split topics into specs/domains/<domain> - <topic>.md and link them from the hub. Link existing notes (flows, schema, UI, imports) instead of repeating their content.

Summary — 2-3 lines in plain language: what the domain does, for whom. Must make sense on its own.
Data model — entities with key fields, types, notes (tables)
Business rules — numbered with stable IDs (<DOMAIN>-R01, <DOMAIN>-R02, …). Each rule: one plain sentence + steps if it is a computation + source. These are contracts the code respects, not code patterns.
Configuration — Option key | Constant | Effect | Default | Default per tenant/customer | Location. Record the default where the computation reads it, and also where the UI shows it, if different.
Dates & thresholds — every hard-coded date, duration, percentage, limit: value, meaning, location.
States — status codes, meaning, condition that sets them.
Flows — numbered end-to-end flows (surface → computation → persistence).
Inconsistencies — mismatches found (UI default ≠ computation default, boundary dates off by one day, same rule implemented differently in two places). Facts with locations only; never resolve them silently.
Related — wikilinks to other domains, integrations and rules notes.

Create a domain note ONLY for domains whose rules are non-obvious from reading the code.

4. `specs/integrations/` — external system boundaries

For every integration with an external system (HTTP, DB, IPC, filesystem, third-party import/export, message queue, AI/OCR services, etc.):

integrations.md — MOC table: name, direction (IN/OUT/BIDIRECTIONAL), protocol, implementing files, link
One note per integration:
- Implementing files — table: file → key symbols
- Flow — numbered steps end-to-end
- Trust boundaries — Boundary | Mechanism | Location. Most important section: what NOT to relax and WHERE the guard lives.
- Config — timeouts, pool sizes, client settings (never secrets: names of settings only)

Create this folder ONLY if the project has at least one integration with a trust boundary.

5. `specs/rules/` — patterns and recipes

Recurring programming patterns go as rule notes in specs/rules/ (e.g. add-option.md, error-handling.md). Each answers "how do I add/change X?" with numbered steps and a minimal code snippet — a recipe, not a description.

6. Other `specs/` notes (only the needed ones)

file-structure.md — map of main directories and files
commands.md — extended commands
conventions-backend.md, conventions-frontend.md, conventions-database.md
api-routes.md — interface table adapted to the real interface type (HTTP, IPC, CLI, events, forms)
glossary.md — domain terms (original wording) → meaning → domain note link
module-index.md — Module | Path | Tier | Summary | Note

7. Obsidian format

Every note this skill creates (and every hand-written note it updates, except generated notes):

Starts with YAML frontmatter (first line of the file):

---
read_when: "<one line: when an agent or colleague should read this note>"
type: domain | integration | rule | convention | index | glossary
domain: <domain-slug>
tier: 1
status: draft | verified
aliases: ["<synonyms>", "<original UI wording>"]
tags: [domain/<slug>, type/<type>]
sources: ["path/to/file.ext", "path/to/other.ext"]
verified_date: <YYYY-MM-DD or empty>
---

Has a globally unique file name for new notes (Obsidian resolves wikilinks by name): never spec.md or index.md repeated across folders.
Links other notes in the vault's existing style: relative Markdown links [text](../path/note.md#heading) if the vault already uses them, otherwise wikilinks [[note name#Heading]]. Both work in Obsidian. Rules are linked by heading or block id (^domain-r01).
Uses plain Markdown tables, no embedded images for information, no content only in callouts.
Is self-contained: the first paragraph answers "what is this" without opening other notes, because MCP clients often retrieve a single note.

MOC (map of content) notes:

specs/home.md — entry point: project summary + links to every MOC
specs/domains/domain-inventory.md — doubles as the domains MOC
specs/integrations/integrations.md, specs/rules/rules.md

8. Verification

After drafting a domain note, verify it with a separate subagent that did not write it:

For each rule, open the cited path:line and confirm the code does exactly what the rule states (conditions, boundary operators < vs <=, dates, defaults, units).
Confirm the cited code is active (not commented out, reachable).
Mark failing rules: fix them, or move them under Inconsistencies with the reason.
When every rule passes, set status: verified, verified_date (today), and update the inventory row.

Base verification only on the files present in source: no version-control commands.

Never mark a note verified without running this pass.

General rules

English only (original domain terms quoted, see Process step 9)
Document only what is not obvious from reading the code (business rules, implicit conventions, architectural decisions, gotchas, trust boundaries, invariants)
Be concise: every note is a reference, not a tutorial
Use markdown tables where possible
Do NOT invent anything — base everything exclusively on existing code
Never copy secrets, credentials, connection strings or personal data into the vault
Separation of concerns between notes:
- conventions-*.md → HOW to write code (style, naming, patterns)
- rules/*.md → HOW to add/change a feature (recipe with steps + snippet)
- domains/<domain>.md → WHAT the code guarantees (business rules, data model, configuration, states)
- integrations/*.md → WHERE the trust boundaries are
- module-index.md / domain-inventory.md → WHICH modules/domains exist and how critical they are
No duplication: if a rule already lives in one note, link to it with a wikilink instead of repeating it.
Cross-link aggressively: an agent or colleague navigating one note must discover the next relevant one without guessing.

SKILL.md 14 KB Permalink History Raw