Maintain project knowledge with ak:docs

Use ak:docs to establish, update, or summarize project documentation while keeping code and executable artifacts as the owners of current behavior. The Skill discovers the repository's real authority surfaces, preserves durable rationale and constraints, and removes documentation that merely duplicates implementation details.

Choose ak:docs for project documentation

Use ak:docs when

• A project needs its first coherent documentation route.
• User-visible behavior, architecture, configuration, or operating guidance has changed and impacted docs must be reconciled.
• You need an evidence-backed project summary without forcing a new file.
• Existing docs contain stale paths, duplicate guidance, or copied inventories.
• You explicitly want to establish durable product principles through the philosophy author interview.

Choose another workflow when

• You need current documentation for an external library. Use the documentation discovery workflow instead.
• You need a generated visual but no documentation change. Use ak:preview.
• You need product code changed. Use the relevant planning or implementation workflow; ak:docs must not implement product code.
• You only need to learn which Skill fits. Use ak:help.

Prepare the project and runtime

Before you start:

• Complete Onboarding, and confirm Engineer Kit is installed for the runtime and scope you are using.
• Open the project and make repository instructions, the root README, and the existing documentation navigation available.
• State the audience, outcome, affected decisions, evidence, and acceptance criteria for the documentation operation.
• Separate evergreen guidance from plans, audits, release evidence, and other stateful records.
• Identify any generated or machine-owned documentation that must be changed through its owner rather than hand-edited.

Run the Skill

/ak:docs update "Reconcile onboarding docs with the current authentication flow. Preserve generated CLI pages, remove duplicated command lists, and verify links."

/ak:docs update "Reconcile onboarding docs with the current authentication flow. Preserve generated CLI pages, remove duplicated command lists, and verify links."

$ak:docs update "Reconcile onboarding docs with the current authentication flow. Preserve generated CLI pages, remove duplicated command lists, and verify links."

The first argument selects the operation:

Choose a fixed docs layout with --preset classic

By default, ak:docs init discovers the project's real documentation route: it reads repository instructions, the root README, and existing docs navigation, then creates only the files that earn their place. A project that wants the earlier fixed layout instead can opt in explicitly:

/ak:docs init --preset classic

--preset classic creates seven files under docs/: project-overview-pdr.md, code-standards.md, codebase-summary.md, design-guidelines.md, deployment-guide.md, system-architecture.md, and project-roadmap.md.

Declaring the same route in the project's own CLAUDE.md, AGENTS.md, or docs/README.md achieves the same result without the flag, and it persists for later update and summarize runs — the Skill reuses whichever route the project already commits to.

The preset only chooses filenames. Every content rule still applies: each file points to the code that owns the behavior instead of describing it, and a file with no real information is skipped rather than filled with a placeholder.

Discovery is the default because documentation that re-describes code becomes a second source of truth no test can check — it drifts and misleads agents — and every generated file spends context budget in every later session.

Manage root agent context

Use agent-context for repository-root instructions; keep ak:folder-context for subfolders.

/ak:docs agent-context --advice
/ak:docs agent-context --audit

Use the $ak:docs spelling in Codex. --advice asks kongming for counsel before presenting a proposed write. --audit gets an audit, then asks one keep, cut, fix, or migrate decision at a time and applies only confirmed changes. The Skill verifies current runtime behavior, excludes secrets, and keeps deterministic settings and Hook configuration recommend-only. This release defines no root context filename for Cursor.

ak:docs applies one write-authority ladder across init, update, and agent-context: routine, in-scope maintenance is self-authorized, and the Skill only stops to confirm before replacing existing prose, an owning document, or a correction you already gave. This includes self-maintenance — reconciling affected instructions after other authorized work in the project, even when no source file changed. When nothing durable actually changed, the run is a true no-op: it writes nothing.

For an operational route — how to retrieve a secret, which log source and window to read for an environment, or which audience a destination is cleared for — the Skill keeps the lookup detail in the project's own operational guide and leaves only a one-line pointer to it in the root agent context file. It redacts observed output before retention, delegation, or publication, and it never writes a credential value, a tokenized URL, an account or project ID, or a customer name into any repository file, including the operational guide and the agent context file itself.

Each route is one record with seven fields: when to use it, scope (project, account, region, and environment, never an implicit default account), source of truth, how to look it up, access and permission, limits, and verification and fallback. One topic has one owner that other pages link to; a file such as docs/deployment.md is an example destination, not a required tree. Before recording a locator, dashboard URL, or account identifier, the Skill checks the destination's real audience and access; when the destination is public or unverifiable, it keeps the detail in an approved restricted owner and reports a blocker instead.

Use agents when root process rules should come from recurring evidence rather than an open-ended audit:

/ak:docs agents 30d --source
/ak:docs agents --dry-run

Use the invocation spelling for your runtime. An ordinary agents run implicitly includes --advice; a separate flag is redundant. The operation mines at most 90 days or 300 commits by default, whichever is smaller, plus up to 200 CI runs. If gh is unauthenticated, it reports that CI signals were skipped and continues with Git-only evidence. --source adds read-only source-marker mining to the git and CI pass; --dry-run stops after ranking signals, spawns no adviser, and writes nothing. Proposed rules still require your confirmation.

Establish product principles with philosophy

Opt in explicitly when you want the product's author or builder to decide durable boundaries and priorities:

/ak:docs philosophy

Use $ak:docs philosophy in Codex. Ordinary documentation maintenance does not start this interview or read local session history without an explicit request. It preserves author-confirmed principles even without incident history or when implementation has drifted; code proves behavior, not authority to change intent.

The interview uses repository evidence and, by default, the last 90 days of verified same-project local sessions, including proven worktrees. It filters project metadata before reading conversation content and uses event times, not file modification times. Author decisions and acceptance are separated from assistant proposals and inference; only sanitized attribution is retained, never raw history, credentials, or personal data. Missing or unsupported history is a reported coverage gap, not a reason to invent evidence or widen access.

You answer one unresolved question at a time. Each retained principle states its scope and behavioral consequence as a mandatory boundary or guiding priority, leaving implementation choices open within those boundaries. Existing confirmed principles remain effective until their author approves replacement; repeated assistant suggestions do not confer that authority.

Before writing, review the exact additions, changes, removals, and resolved destination for every affected file. An in-project symlink's canonical target is previewed and edited without replacing the link; an external destination requires explicit authorization. Missing answers or exact-diff approval yield only a proposal and unresolved questions. Earlier approval can be reused only while the target and patch remain valid; a changed target requires re-preview rather than overwriting concurrent edits. Repeating equivalent principles is a no-op. Recorded guidance is a collaboration contract, not proof that every runtime loads or enforces it.

Session evidence comes only from local history the runtime makes readable. Claude Code and Codex keep local session history the Skill can verify and read; another runtime is scanned only through a verified local reader. The report names missing, inaccessible, or unsupported sources instead of claiming complete coverage.

Before proposing a destination, the Skill reads both root AGENTS.md and CLAUDE.md when present and identifies symlinks and existing principle owners; it does not assume CLAUDE.md is canonical. When the two files are independent, it previews the same shared principles in both while keeping each file's runtime-specific instructions. When neither exists and the project declares no owner, it proposes AGENTS.md as a portable entry point without claiming that every runtime reads it automatically. Later update and agent-context runs preserve the meaning and authority of confirmed principles without restarting the interview, and surface a conflict or suspected supersession to the author instead of silently weakening, removing, or promoting a principle.

Generate AI-readable documentation indexes

/ak:docs llms

The llms operation discovers the project's documentation authority, then creates or reconciles llms.txt and llms-full.txt in the site's public/static directory or, when there is no published site, the repository root. It keeps the curated index concise, preserves valid existing organization, validates links, and reports the full-content file's size.

Define the documentation contract

Before writing, the Skill establishes:

• Audience: Identify whether people, AI collaborators, or both consume the route.
• Outcome: State which decisions or tasks the documentation must make possible.
• Authority: Identify the repository surfaces that own durable guidance.
• Evidence: Name source, tests, scripts, manifests, generated artifacts, or live state that prove current behavior.
• State boundary: Separate evergreen intent from temporary plans, reports, audits, and release records.
• Acceptance criteria: Define the paths, links, examples, or decisions that must be verifiable afterward.

The Skill reuses an accepted plan or prior documentation contract when it already settles these questions.

Understand what happens during a run

1. The Skill confirms the contract. It runs a bounded documentation brainstorm and reopens only material missing decisions.
2. The Skill discovers the route. It reads repository instructions, the root README, the current docs index, linked docs, and relevant evidence.
3. The Skill maps ownership. It distinguishes durable why and where guidance from executable what and how details.
4. The Skill selects the smallest change. init designs a minimal route; update maps changed claims to their owners; summarize scopes a focused evidence read.
5. The Skill presents material authority changes. It shows a proposed route before replacing existing docs or changing their authority.
6. The Skill writes or summarizes. It can use a docs-manager delegate when available or perform the same evidence-first work locally.
7. The Skill validates the result. It verifies links, paths, examples, configuration keys, commands, and owning generators or contract scripts.

Keep documentation safe and maintainable

Important boundaries:

• Documentation owns durable rationale, decisions, terminology, constraints, and navigation. It should point to executable owners for current behavior.
• Machine-owned inventories and generated reference output must be changed through their manifest, generator, or source layer.
• The Skill must not create ADR collections, roadmaps, generators, bots, or docs-only CI gates unless you explicitly request that operating surface.
• Diagrams are added only when a visual materially improves understanding and must be reviewed after generation.
• When documentation or root context includes test guidance, the Skill applies test principles through the same project-specific evidence and confirmation gates instead of copying generic guidance wholesale.
• philosophy always retains its exact-diff approval gate; routine maintenance authority, flags, and advisory counsel cannot bypass it.
• No external provider, publication, credential, or paid service is required by the source-defined workflow.

Verify the result

Evidence depends on the selected operation:

A complete result also reports unresolved questions last. Short documentation is valid when the project contains little durable rationale that code cannot express.

Troubleshoot or continue

Know the current limits

• The Skill cannot recover undocumented rationale that is absent from the repository and available project context.
• Live-state claims remain limited by accessible tools, credentials, and evidence.
• Delegated documentation work depends on runtime capability and must receive the same ownership and drift-resistance rules.
• Cursor slash invocation is user-verified evidence, not proof of delegation or diagram-tool parity.