Doc Detective Agent Tools

Agent tools for testing documentation procedures and validating that documented workflows match actual application behavior. Compatible with Claude Code, Cursor, Codex, OpenCode, GitHub Copilot, and other AI coding assistants 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.

Installation

Option 1: Claude Code Plugin

1. Open Claude Code:

   claude

2. Add the Doc Detective plugin to Claude Code's plugin marketplace:

   /plugin marketplace add doc-detective/agent-tools
   

3. Then install specific skill sets via:

   /plugin install doc-detective@doc-detective
   

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

   /doc-detective:init
   

Option 2: Install with npx skills

Warning

npx skills only installs skills, not agents, commands, or other tools. For full functionality, consider manual installation.

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.

Option 3: Manual Installation

Copy to your project directory

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

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

Important

Adjust the path based on your agent's expected skill/plugin directory. For example, .github/ for GitHub Copilot, .cursor/ for Cursor, etc.

Load locally during development with Claude Code

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

Usage

Bootstrap Doc Detective for a Project

/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

Convert Documentation to Tests

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

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

Run Tests

/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.

Validate Test Specifications

/doc-detective:validate test-spec.json

Validates structure before execution:

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

Inject Tests into Documentation

/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 Actions Reference

The plugin includes complete documentation for Doc Detective actions:

Action	Purpose
goTo	Navigate to a URL
click	Click an element (prefer text-based)
find	Verify an element exists
type	Type text input
httpRequest	Make HTTP requests
runShell	Execute shell commands
screenshot	Capture screenshots
wait	Pause or wait for elements
checkLink	Verify URL returns OK
loadVariables	Load environment variables
saveCookie/loadCookie	Manage session persistence
record/stopRecord	Video recording

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

Inline Test Injection

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.

Examples

Test a Login Procedure

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

Test Multiple Workflows

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

Resources

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

License

AGPL3

Contributing

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