Agent tools for testing documentation procedures and validating that documented workflows match actual application behavior. Compatible with Gemini CLI, Claude Code, Cursor, Codex, OpenCode, GitHub Copilot, and other AI coding agents that support plugins, skills, or commands.

• Set up Doc Detective for a project. Initialize Doc Detective in a project with automatic documentation detection, config generation, and test creation.
• Generate tests. Convert documentation into executable test specifications.
• Run tests. Execute tests against your application and report results.
• Inject tests into your docs content. Embed test steps close to associated documentation content.
• Install the Doc Detective GitHub Action. Add a Doc Detective GitHub Actions workflow for automated documentation testing in CI.

1. Open Claude Code:

   claude

2. Add the Doc Detective marketplace and plugin:

   /plugin marketplace add doc-detective/agent-tools
   /plugin install doc-detective@doc-detective
   

3. Ask about Doc Detective, or use the init command to get started:

   /doc-detective-init
   

1. Install the extension and open Gemini CLI:

   gemini extensions install https://github.com/doc-detective/agent-tools.git --auto-update
   gemini

2. Ask about Doc Detective, or use the init command to get started:

   /doc-detective-init
   

1. Open Copilot CLI:

   copilot

2. Install the Doc Detective plugin:

   /plugin marketplace add doc-detective/agent-tools
   /plugin install doc-detective@doc-detective
   

3. Ask about Doc Detective, or use the init command to get started:

   /doc-detective-init
   

1. Install the plugin and open Qwen Code:

   qwen extensions install https://github.com/doc-detective/agent-tools
   qwen extensions install doc-detective:doc-detective
   qwen

2. Ask about Doc Detective, or use the init command to get started:

   /doc-detective-init
   

1. Clone the repository:

   git clone https://github.com/doc-detective/agent-tools.git

2. Copy the plugin contents to your project's .opencode/ directory:

   mkdir -p .opencode/plugins
   cp agent-tools/plugins/doc-detective/opencode-plugin.mjs .opencode/plugins/
   cp -r agent-tools/plugins/doc-detective/hooks .opencode/
   cp -r agent-tools/plugins/doc-detective/skills .opencode/
   cp -r agent-tools/plugins/doc-detective/agents .opencode/

3. Start OpenCode and ask about Doc Detective, or use the init command:

1. Clone the repo and copy the plugin and marketplace into your project:

   git clone https://github.com/doc-detective/agent-tools.git
   cp -r agent-tools/plugins/doc-detective ./plugins/doc-detective
   mkdir -p .agents/plugins
   cp agent-tools/.agents/plugins/marketplace.json .agents/plugins/marketplace.json

2. Open Codex and install the plugin from the marketplace:

   codex

3. Ask about Doc Detective, or use the init command to get started:

   /doc-detective-init
   

What installing the plugin gives you:

• Skills. Running codex plugin marketplace add <path> then codex plugin add doc-detective@doc-detective loads the Doc Detective skills into Codex.
• MCP tools. The plugin bundles its MCP server in plugins/doc-detective/.mcp.json, so the remote MCP tools auto-register on install — no manual ~/.codex/config.toml edit required.
• Hooks. Codex supports lifecycle hooks, but the tool-matched guardrails (validation, anti-pattern blocking, etc.) key on Claude's Edit/Write tool names, which Codex does not use — so they do not currently fire on Codex. They run on Claude Code, Gemini CLI, and OpenCode.

Doc Detective ships as a Cursor plugin (Cursor 2.5+).

This is the method for an individual machine. It needs no marketplace and no Teams plan.

1. Clone the repo:

   git clone https://github.com/doc-detective/agent-tools.git

2. Copy the plugin folder into Cursor's local plugins directory. Copy plugins/doc-detective itself (the folder that contains .cursor-plugin/plugin.json):

   macOS / Linux:

   mkdir -p ~/.cursor/plugins/local                 # create the dir on a fresh install
   rm -rf ~/.cursor/plugins/local/doc-detective     # remove any previous copy first
   cp -r agent-tools/plugins/doc-detective ~/.cursor/plugins/local/doc-detective

   Windows (PowerShell):

   $dest = "$HOME\.cursor\plugins\local\doc-detective"
   New-Item -ItemType Directory -Force -Path "$HOME\.cursor\plugins\local" | Out-Null
   Remove-Item -Recurse -Force $dest -ErrorAction SilentlyContinue
   Copy-Item -Recurse agent-tools\plugins\doc-detective $dest

   (Creating the directory first handles a fresh Cursor install; removing any previous copy avoids nesting the plugin inside an existing doc-detective/ folder.)

   When done, the manifest must sit at ~/.cursor/plugins/local/doc-detective/.cursor-plugin/plugin.json (on Windows, %USERPROFILE%\.cursor\plugins\local\doc-detective\.cursor-plugin\plugin.json) — i.e. not double-nested under a second doc-detective/ folder.

3. Reload Cursor: open the Command Palette (Cmd/Ctrl+Shift+P) and run Developer: Reload Window (or quit and reopen Cursor).

4. Verify: in Agent chat, type / and confirm the /doc-detective-* commands appear. Then get started:

   /doc-detective-init
   

Developing on the plugin? Symlink instead of copying so edits show up on reload:

mkdir -p ~/.cursor/plugins/local
rm -rf ~/.cursor/plugins/local/doc-detective   # clear any existing copy first
ln -s "$PWD/agent-tools/plugins/doc-detective" ~/.cursor/plugins/local/doc-detective

The Cursor CLI has no marketplace — load the plugin with --plugin-dir (this loads the skills, agent, rule, and MCP server):

cursor-agent --plugin-dir "$PWD/agent-tools/plugins/doc-detective"

Cursor can load resources from other ecosystems. In Settings → Rules, Skills, Subagents, enable "Include third-party Plugins, Skills and other configs" — Cursor then imports skills and subagents from Claude Code's ~/.claude/skills and ~/.claude/agents (and Codex configs). So if you already run Doc Detective in Claude Code (or npx skills add doc-detective/agent-tools), this toggle surfaces it in Cursor with no separate Cursor plugin. (It imports everything from those ecosystems, so the dedicated Cursor plugin above is more targeted.)

Team Marketplaces are not available on individual (Free/Pro) plans — if you don't see the option below, use the local install above. On a Teams or Enterprise plan, an admin can import this repo as a custom marketplace from the web dashboard (not the in-app settings):

1. Go to cursor.com → Dashboard → Settings → Plugins → Team Marketplaces → Import.
2. Paste https://github.com/doc-detective/agent-tools and review the parsed plugins (Cursor reads the repo's .cursor-plugin/marketplace.json).
3. Assign access groups, mark the plugin Required or Optional, and save.

(Auto-refresh needs the Cursor GitHub App and updates at most every 10 minutes; re-import the URL to pick up newly added plugins.)

After the plugin is listed on the Cursor marketplace, install it with /add-plugin doc-detective in Agent chat, or "Add to Cursor" on the marketplace page.

What installing the plugin gives you:

• Skills. The Doc Detective skills load into Cursor and are invocable as slash commands (/doc-detective-test, /doc-detective-generate, /doc-detective-validate, /doc-detective-inject, /doc-detective-init, /doc-detective-install-github-action).
• Agent. The doc-detective-specialist subagent is available for documentation-testing tasks.
• Rule. A persistent "docs as tests" rule reminds the agent to validate and test documented procedures (and to use the correct { "action-name": ... } spec format) when you edit docs or test specs.
• MCP tools. The plugin registers the Doc Detective remote MCP server inline in its manifest, so the MCP tools are available without a manual .cursor/mcp.json edit.
• Hooks. Cursor's hook protocol differs from Claude's, so the plugin routes Cursor's sessionStart and afterFileEdit events through an adapter (hooks/scripts/cursor-hook-adapter.js) that reuses the shared hook scripts — giving you install detection, spec validation, formatting, and anti-pattern guidance. See docs/README.cursor.md for details.

Install these skills with the skills package from Vercel. This works with Claude Code, Cursor, Codex, OpenCode, and other AI coding tools.

npx skills add doc-detective/agent-tools

Follow the prompts. The CLI auto-detects which AI tools you have installed and places the skills in the appropriate directories.

git clone https://github.com/doc-detective/agent-tools.git

cp -r agent-tools/agents .{agent-dir}/agents      # Agents
cp -r agent-tools/commands .{agent-dir}/commands  # Commands
cp -r agent-tools/skills .{agent-dir}/skills      # Skills
cp -r agent-tools/hooks .{agent-dir}/hooks        # Hooks

/doc-detective-init

Initializes Doc Detective in your repository by:

1. Detecting documentation files
2. Generating a minimal configuration
3. Creating tests for identified procedures
4. Running tests
5. Iteratively fixing failures with confidence-based suggestions

/doc-detective-generate path/to/documentation.md

Identify testable procedures and convert them into Doc Detective test specifications.

/doc-detective-test path/to/documentation.md

Runs tests from docs or test specification files:

1. Extracts step-by-step procedures from your documentation.
2. Converts them to Doc Detective test specifications.
3. Validates the test specs.
4. Executes tests using Doc Detective.
5. Reports results with any failures mapped back to documentation sections.

/doc-detective-validate test-spec.json

Validates structure before execution:

• Required fields present
• Action types recognized
• Parameter types correct

/doc-detective-inject tests/spec.yaml docs/procedure.md --apply

Takes a well-formed test specification and injects test steps as inline comments into the associated documentation content so you don't have to maintain separate files.

/doc-detective-install-github-action [options]

Installs a Doc Detective GitHub Actions workflow for automated documentation testing in CI:

1. Detects project context (config files, docs directory, existing workflows).
2. Generates a workflow YAML with configurable triggers and optional features.
3. Writes the workflow to .github/workflows/doc-detective.yml.
4. Reports manual steps needed (e.g., enabling Actions permissions).

The plugin includes complete documentation for Doc Detective actions:

See skills/doc-detective-doc-testing/references/actions.md for detailed documentation.

The plugin includes hooks that activate automatically when installed. Hooks provide deterministic guardrails that run at key points during your agent session — no configuration required.

Hooks are supported in Claude Code, Gemini CLI, and OpenCode. Other agents can use the shared scripts in hooks/scripts/ with their own hook configuration.

Inject test steps from separate spec files directly into documentation as inline comments:

/doc-detective-inject tests/login.yaml docs/login.md --apply

Before:

1. Go to [Login Page](https://example.com/login).
2. Click **Sign In**.

After:

1. Go to [Login Page](https://example.com/login).
<!-- step {"goTo":"https://example.com/login"} -->
2. Click **Sign In**.
<!-- step {"click":"Sign In"} -->

Steps are matched to content using semantic patterns (links, bold text, action verbs) and placed close to their associated documentation.

Documentation:

# Login Procedure

1. Navigate to https://example.com/login
2. Enter your username
3. Enter your password
4. Click "Sign In"
5. Verify you see the Dashboard

Use the skill:

/doc-detective-test path/to/file.md this login procedure from our docs to make sure it still works

Create a test specification file workflows.json:

{
  "tests": [
    {
      "testId": "signup-flow",
      "description": "New user signup",
      "steps": [
        { "goTo": "https://example.com/signup" },
        { "find": "Create Account" },
        { "type": { "keys": "newuser@example.com", "selector": "#email" } },
        { "click": "Sign Up" },
        { "find": "Welcome" }
      ]
    },
    {
      "testId": "password-reset",
      "description": "Forgot password flow",
      "steps": [
        { "goTo": "https://example.com/login" },
        { "click": "Forgot Password" },
        { "type": { "keys": "user@example.com", "selector": "#email" } },
        { "click": "Reset" },
        { "find": "Check your email" }
      ]
    }
  ]
}

Then execute:

/doc-detective-test workflows.json

• Doc Detective Documentation
• Doc Detective GitHub
• Test Specification Format
• Actions Reference

Doc Detective hosts a remote Model Context Protocol server at https://agency.doc-detective.com/mcp that exposes three tools to MCP-compatible clients:

When you install the plugin or extension, the MCP server is auto-registered for:

• Claude Code (via plugin)
• Gemini CLI (via extension)
• Qwen Code (via extension)
• OpenCode (via plugin)
• Codex (via the plugin's bundled .mcp.json)

For the hosts below, paste the snippet into the indicated config file:

{
  "mcpServers": {
    "doc-detective": {
      "url": "https://agency.doc-detective.com/mcp",
      "headers": { "X-DD-Client": "cursor" }
    }
  }
}

Installing the Codex plugin auto-registers the MCP server from its bundled .mcp.json. If you installed only the skills (e.g. via npx skills), register it manually instead:

[mcp_servers.doc-detective]
url = "https://agency.doc-detective.com/mcp"
http_headers = { "X-DD-Client" = "codex" }

{
  "mcpServers": {
    "doc-detective": {
      "type": "http",
      "url": "https://agency.doc-detective.com/mcp",
      "headers": { "X-DD-Client": "copilot-cli" }
    }
  }
}

The server only receives the arguments you pass to its tools. The X-DD-Client header identifies the host (e.g., claude-code, gemini-cli) — no personally identifying information. The log_observation tool is reserved for abstract feedback only — never file paths, URLs, selectors, or spec contents. To opt out, remove the mcpServers (or mcp) entry from your host's config.

Source content lives in src/. The build system (npm run build) generates downstream artifact directories that consumers install:

AGPL3

To contribute improvements to this plugin, submit issues or pull requests to the repository.