Skip to main content

Agentic Development with Dochia

Modern AI-powered IDEs — Windsurf, Cursor, Claude Code, OpenAI Codex — can act as autonomous coding agents. Dochia ships first-class support for these agents through the Agent Skills specification, giving your AI assistant deep context about Dochia's commands, flags, and output formats.

Quick Start​

# Generate agent skills in your project
dochia init-skills

# Or in a specific directory
dochia init-skills --dir /path/to/project

# Commit to version control
git add .agents/
git commit -m "Add Dochia agent skills"

That's it. Your agentic IDE will automatically discover the skills on the next session.

What Are Agent Skills?​

Agent Skills are structured markdown files that teach AI coding assistants about external tools. They follow the open agentskills.io specification and are placed in .agents/skills/ at the root of your project.

Each skill file contains:

  • A description of the command and when to use it
  • Trigger phrases — natural-language patterns the agent matches against
  • Usage examples — real commands the agent can adapt and suggest
  • Options reference — flags, arguments, and their semantics
  • Output schemas — so the agent can parse and explain results

Generated Skills​

Dochia generates one skill per command:

SkillTeaches the agent to...
dochia-testRun systematic API tests, pick profiles, set quality gates, filter by paths/tags/operations, parse reports
dochia-fuzzLaunch continuous random fuzzing, set stop conditions, match specific response codes
dochia-replayReplay errors/warnings from a previous run, re-validate after fixes
dochia-listDiscover available playbooks, profiles, mutators, paths, and formats
dochia-explainExplain response codes, playbooks, mutators, and error reasons from reports

The dochia-test skill also includes a references/report-output.md file with the full JSON schemas for TestN.json and dochia-summary-report.json, plus jq recipes for common analysis tasks.

Supported IDEs​

IDE / AgentHow it discovers skills
Windsurf (Cascade)Reads .agents/skills/ automatically at session start
CursorReads .agents/skills/ automatically at session start
Claude CodeReads .agents/skills/ automatically at session start
OpenAI CodexReads .agents/skills/ automatically at session start

Agentic Workflows​

Once skills are installed, your AI assistant can handle complete testing workflows through natural-language prompts. Here are some examples:

"Test my API"​

The agent will:

  1. Locate your OpenAPI spec
  2. Construct a dochia test command with the correct contract and server URL
  3. Suggest appropriate flags (blackbox mode, authentication headers, etc.)
  4. Run the command and summarise the results

"Run a security scan on my API"​

The agent will:

  1. Use dochia test --profile security (or --profile compliance)
  2. Include authentication headers from your environment
  3. Explain any errors using dochia explain

"Why did Test 449 fail?"​

The agent will:

  1. Read dochia-report/Test449.json to get the full request/response details
  2. Identify the playbook (ZeroWidthCharsInValuesFields), the response code, and the result reason
  3. Run dochia explain --type response_code 953 if needed
  4. Explain the finding in plain language and suggest a fix

"Replay the failing tests after my fix"​

The agent will:

  1. Run dochia replay --errors -s http://localhost:8080
  2. Compare the new results to the previous run
  3. Report which tests now pass and which still fail

"Set up Dochia in my CI pipeline"​

The agent will:

  1. Generate a GitHub Actions / GitLab CI configuration
  2. Use --profile ci for a balanced test suite
  3. Add --quality-gate thresholds appropriate for the pipeline stage
  4. Configure report upload as build artifacts

"What playbooks are available for injection testing?"​

The agent will:

  1. Run dochia list --playbooks --json
  2. Filter for injection-related playbooks
  3. Suggest --profile security or a targeted --playbooks list

Keeping Skills Up to Date​

When you upgrade Dochia, skill definitions may change (new commands, new flags, updated examples). Refresh them with:

dochia init-skills --force
git add .agents/
git commit -m "Update Dochia agent skills to $(dochia --version)"

Tip: Add this to your Dochia upgrade checklist or automate it in a post-install script.

Best Practices​

  1. Commit skills to version control — every developer and CI agent picks them up automatically
  2. Refresh after upgrades — run dochia init-skills --force when you update Dochia
  3. Don't edit generated files — they are overwritten on --force. Add custom skills as separate files if needed
  4. Combine with project context — the agent works best when it can also read your OpenAPI spec, dochia.properties, and report files
  5. Use natural language — the skills teach the agent Dochia's vocabulary, so you can describe goals instead of memorising flags

How It Works Under the Hood​

┌─────────────────────────────────────────────────────────┐
│  Your IDE (Windsurf / Cursor / Claude Code / Codex)     │
│                                                         │
│  ┌─────────────────────────────────────────────────┐    │
│  │  AI Agent                                       │    │
│  │                                                 │    │
│  │  1. Reads .agents/skills/*.md at session start  │    │
│  │  2. User asks: "test my API for security"       │    │
│  │  3. Matches trigger → dochia-test skill         │    │
│  │  4. Constructs: dochia test --profile security  │    │
│  │  5. Runs command, reads report JSON             │    │
│  │  6. Summarises results in natural language      │    │
│  └─────────────────────────────────────────────────┘    │
│                                                         │
│  .agents/skills/                                        │
│  ├── dochia-test/SKILL.md                               │
│  ├── dochia-fuzz/SKILL.md                               │
│  ├── dochia-replay/SKILL.md                             │
│  ├── dochia-list/SKILL.md                               │
│  └── dochia-explain/SKILL.md                            │
└─────────────────────────────────────────────────────────┘

See Also​