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:

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.

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.
• 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.
• Stable and beta package the same ak:docs modes and documentation rules.