Docs, for Moxie Docs

Integrate MCP agents with Moxie Docs

3 min readUpdated

This page shows you how to connect MCP-compatible tools and agents to Moxie Docs using exported prompt descriptors and SKILL.md so agents can act on your docs and pull requests with confidence.

What you’ll set up

  • Use SKILL.md and PR guidance blocks that Moxie renders into your repo to steer agents.
  • Reference Moxie’s exported prompt descriptors from your MCP agent configuration.
  • Let agents call Moxie’s MCP server to answer codebase questions and keep docs and code changes in lockstep.

Prerequisites

  • You connected your GitHub repository to Moxie Docs via the GitHub App and Moxie has finished its initial indexing.
  • You have an MCP-compatible agent or tool that supports prompt descriptors and skills (for example, a local agent runner or IDE assistant that can read SKILL.md and PR guidance blocks).

Where Moxie publishes guidance for agents

When you connect a repo, Moxie renders:

  • SKILL.md content that explains the repo’s documentation conventions and how agents should operate.
  • PR guidance blocks in pull requests that outline how to review, adjust, and finalize doc changes.
  • Prompt descriptors that define the available MCP tools for asking this codebase questions and proposing documentation updates.

Agents should read SKILL.md in the repo and follow any PR guidance blocks when preparing or reviewing changes.

Configure your MCP agent

Point your agent to Moxie’s exported prompt descriptors and ensure it ingests the repo’s SKILL.md.

  1. Locate the SKILL.md and any PR guidance blocks in your connected repository. These are rendered by Moxie and are safe to commit and consume.
  2. Enable prompt descriptor ingestion in your agent. Provide the path or URL to Moxie’s exported prompt descriptors referenced by SKILL.md or the PR guidance blocks.
  3. Grant your agent access to the repository (read) and to open or comment on pull requests if it will propose changes.
  4. Start the agent with the repo root as context. Verify it loads SKILL.md and registers the Moxie tools defined by the prompt descriptors.

Example MCP agent snippet (pseudo-configuration):

  • skills: load ./SKILL.md
  • prompts: include descriptors referenced in SKILL.md
  • tools: enable “ask-this-codebase”, “propose-doc-update”, and any PR review helpers exposed by the descriptors

Your agent should now be able to: ask the codebase questions, generate or update docs, and follow PR guidance blocks in review flows.

Use Moxie tools from an agent

  • Ask questions about the codebase to ground documentation changes.
  • Generate or refresh documentation sections flagged as out of date.
  • Open a pull request with proposed changes and include Moxie’s PR guidance blocks for reviewers.
  • Respond to review comments by re-running the agent with the same SKILL.md and descriptors.

Tip: Keep SKILL.md current in your default branch so all agents share the same conventions and constraints.

Review and merge safely

  • In the Moxie dashboard, review agent-proposed changes, tune automation, and track the changelog.
  • Use the PR guidance blocks to validate scope, tone, and structure before merging.
  • If code changes later cause drift, Moxie will surface updates and your agents can re-run with the same guidance.

Troubleshooting

  • Agent ignores SKILL.md: Ensure the agent is started from the repo root and has permission to read repository files.
  • Tools not available: Confirm the agent is loading the prompt descriptors referenced by SKILL.md.
  • Low-quality PRs: Re-run the agent after updating SKILL.md conventions; reviewers should follow PR guidance blocks to request targeted revisions.

Was this page helpful?

Let us know if you found what you were looking for.

Related articles

GuidesBilling, trial, or access issuesThis guide helps you fix problems starting a trial, completing a subscription through Stri
GuidesConfigure PR automation and detectorsUse Moxie Docs’ repository automation to keep docs PRs consistent, tune drift detectors, a
GuidesFix missing or outdated docs in the dashboardUse this guide if documentation collections look empty, out of date, or a collection you e