Keep marketing project knowledge current with ak:docs

Use ak:docs to create, reconcile, or summarize project documentation without forcing a standard folder tree. The Skill keeps decisions, constraints, terminology, and navigation in prose while pointing current behavior to its executable evidence.

Choose ak:docs for evidence-backed documentation

Use ak:docs when

• A marketing project needs a minimal documentation route for people, AI collaborators, or both.
• An approved workflow, configuration, public contract, or operating constraint changed and nearby documentation may be stale.
• You need a focused summary of current project evidence.
• Existing docs copy mutable commands, inventories, or implementation behavior.
• You explicitly want to establish durable product principles through the philosophy author interview.

Choose another workflow when

• Your vision should become a README, strategy, or other document through an interview rather than a product-principles contract. Use ak:interview-docs.
• You need a research assignment. Use ak:research-prompt.
• You want product code implemented. ak:docs explicitly excludes that work.
• You only need a diagram. Use ak:mermaidjs-v11 or ak:tech-graph.

Prepare the project and runtime

Identify the audience, the decision the docs must support, the sources that prove current behavior, and the acceptance criteria. Run from the project whose instructions and evidence should govern the result.

The Skill reads repository instructions such as AGENTS.md or CLAUDE.md, the root README.md, existing docs navigation, nearby docs, then relevant source, tests, scripts, generated artifacts, and live state. It does not assume a filename, file count, or universal docs tree.

See Runtime adapters for component-level differences.

Run the Skill

The first argument selects init, update, summarize, agent-context, agents, philosophy, or llms. Empty or unclear input makes the Skill ask; it never assumes init.

/ak:docs update Reconcile the launch docs with the approved campaign workflow. Change only claims proven by current project evidence, preserve unrelated docs, and do not publish

/ak:docs update Reconcile the launch docs with the approved campaign workflow. Change only claims proven by current project evidence, preserve unrelated docs, and do not publish

$ak:docs update Reconcile the launch docs with the approved campaign workflow. Change only claims proven by current project evidence, preserve unrelated docs, and do not publish

For root context, /ak:docs agent-context --advice asks kongming before a proposed write. /ak:docs agent-context --audit presents one keep, cut, fix, or migrate decision at a time and applies only confirmed changes. /ak:docs agents includes its kongming review by default; --advice is redundant. It mines the smaller of 90 days or 300 commits by default and at most 200 CI runs. If gh is unauthenticated, it falls back to Git-only mining and reports that CI signals were skipped. --source adds read-only source-tree mining; --dry-run stops after signal ranking, makes no rule proposals, spawns no advisor, and writes no file; --audit confirms one proposed rule at a time. /ak:docs llms reconciles both llms.txt and llms-full.txt instead of replacing curated content blindly. Use $ak:docs in Codex. Deterministic settings and Hook configuration are recommend-only, and no Cursor root context filename is defined. Use ak:folder-context only for subfolders.

init, update, and agent-context share one write-authority ladder: routine, in-scope maintenance is self-authorized, and the Skill confirms first only before replacing existing prose, an owning document, or a correction you already gave. That includes self-maintenance after other authorized work, even when no source file changed; when nothing durable changed, the run writes nothing. For an operational route, such as how to retrieve a secret or which log source to read for an environment, the Skill keeps the lookup detail in the project's own operational guide and leaves only a one-line pointer in the root context file. It redacts observed output before retention, delegation, or publication, and never writes a credential value, tokenized URL, account or project ID, or customer name into a repository file.

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.

Follow the evidence-first stages

1. Set the contract. Bound audience, outcome, authority, evidence, scope, and acceptance criteria.
2. Discover the route. Read project instructions and navigation before selecting documents.
3. Map claims to owners. Use source, tests, schemas, manifests, generators, and live state for current behavior.
4. Choose the smallest change. Reuse coherent routes; avoid empty indexes, speculative roadmaps, and automatic ADR collections.
5. Author or summarize. Point to executable owners instead of copying mutable behavior.
6. Validate. Check links, paths, examples, configuration keys, commands, and owning scripts where practical.

When affected docs include test setup, execution, or structure, the Skill also applies its bundled practical testing principles while keeping the result project-specific and evidence-backed.

Keep documentation changes within authority

Do not place credentials, private customer data, or secret URLs in docs. Keep plans, audits, research, and release evidence separate from evergreen authority. Review any proposal that would replace an established docs route before writing. philosophy always retains its exact-diff approval gate; routine maintenance authority, flags, and advisory counsel cannot bypass it.

Verify outputs and evidence

Output paths depend on the operation: llms has the fixed llms.txt and llms-full.txt pair, while other operations follow the project route or return a response. A complete run should identify:

• docs created, changed, retained, or removed;
• the audience and decision served by each changed document;
• the evidence owner for each current claim;
• links, paths, examples, and validators checked; and
• remaining uncertainty or actions that still need approval.

For philosophy, expect confirmed boundaries and priorities with implementation freedom, sanitized session attribution and coverage gaps, and the approved destination diff or a proposal-only/no-op outcome.

For summarize, expect a response unless you named a durable target. For init, update, agent-context, agents, philosophy, or llms, inspect the diff and confirm no product code or unrelated documentation changed.

Troubleshoot and understand limits

The Skill can verify only evidence and live state accessible in the current session. It cannot make unsupported claims true or decide publication policy.

Continue with the Marketing Kit overview, Marketing Kit Agents, or Installing kits.