Skip to main content

Improve your documentation with an AI agent

Your analytics show where Kapa falls short: Coverage Gaps, uncertain and downvoted answers, Top Questions and Source Analytics. This guide hands all of them to a coding agent working in your documentation repository. The agent combines them into one list of topics, checks each one against your pages, and works through the list with you, editing the documentation where it needs it. There is nothing to export first.

Before you start​

  • A coding agent with the Kapa plugin installed and signed in, such as Claude Code, Codex or Cursor. See If your agent needs help connecting.
  • Permission to read your project's analytics.
  • A local copy of the repository your documentation is built from.
  • Optional: a second Kapa project that indexes your internal knowledge, such as support tickets, an internal wiki or Slack. The agent uses it to tell documentation that is missing from features that are not supported.

Run the skill​

  1. Open your coding agent at the root of your documentation repository.
  2. Ask it to improve your documentation, for example: "Improve our documentation from what people asked Kapa last month." In Claude Code you can also run /kapa:kapa-improve-docs.
  3. Answer the agent's questions: which project holds your public traffic, the period to look at, and your internal project, if you have one.
  4. Review the ranked list of topics the agent shows you, with the users or conversations behind each, and choose where to start.
  5. For each topic, read the agent's recommendation and its evidence: the questions users asked, what your documentation says today, and the change it proposes. Accept it, edit it, or decline it.

Before the agent searches a project, it tells you which one and roughly how many searches it plans, and waits for your go-ahead. Each search is a real query on that project: it counts toward its quota and appears in its analytics.

The agent treats anything it finds in an internal project as confidential. It proposes only statements that belong in public documentation and never quotes internal content, but review those changes yourself before you publish them.

Verify​

The agent edits the pages you accepted, and records every decision, including the topics you declined, in .kapa/docs-improvements.md in your repository. Commit that file with your changes: the next run reads it, so it does not propose the same topics again unless they grow.