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.

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.

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.

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.
• 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.