# How to Contribute to the VulnClaw Project: A Complete Developer Guide

> Learn how to contribute to the VulnClaw project. Follow our developer guide to fork the repo, install dependencies, make changes, test, and submit a pull request.

- Repository: [Unclecheng/VulnClaw](https://github.com/Unclecheng-li/VulnClaw)
- Tags: how-to-guide
- Published: 2026-07-03

---

**Contributing to the VulnClaw project requires forking the repository, installing dependencies via Hatch, modifying the relevant modular component (Agent, CLI, or Skills), running the full pytest suite, and submitting a PR that includes updated documentation and version bumps for any public API changes.**

VulnClaw is a modular, AI-powered penetration-testing framework developed by Unclecheng-li. When you contribute to the VulnClaw project, you are extending a codebase that strictly separates concerns between task orchestration, agent logic, and markdown-driven skills. This guide provides the exact file paths and code patterns found in the source code to ensure your changes align with the architecture.

## Clone and Configure the Development Environment

Start by cloning the repository and installing Python dependencies via Hatch, the project's environment manager.

```bash
git clone https://github.com/Unclecheng-li/VulnClaw.git
cd VulnClaw
hatch env create

```

For frontend modifications, navigate to the `frontend` directory and install Node.js dependencies.

```bash
cd frontend && npm ci

```

The [`README.md`](https://github.com/Unclecheng-li/VulnClaw/blob/main/README.md) provides a quick start guide, while [`CONTRIBUTING.md`](https://github.com/Unclecheng-li/VulnClaw/blob/main/CONTRIBUTING.md) explains the repository layout in detail according to the Unclecheng-li/VulnClaw source code.

## Understand the Modular Architecture

Before modifying code, identify the correct module to avoid "spaghetti" changes. The repository organizes functionality into distinct subsystems, each owning specific behaviors.

**Key Entry Points and Subsystems:**

- **Task Orchestration** – [`vulnclaw/orchestrator.py`](https://github.com/Unclecheng-li/VulnClaw/blob/main/vulnclaw/orchestrator.py) handles the shared "run → save → summarize" workflow for CLI, Web, and REPL interfaces.
- **Agent Core** – [`vulnclaw/agent/core.py`](https://github.com/Unclecheng-li/VulnClaw/blob/main/vulnclaw/agent/core.py) and [`vulnclaw/agent/llm_client.py`](https://github.com/Unclecheng-li/VulnClaw/blob/main/vulnclaw/agent/llm_client.py) manage auto-pivot logic, tool calls, and LLM request handling with retries.
- **CLI Interface** – [`vulnclaw/cli/main.py`](https://github.com/Unclecheng-li/VulnClaw/blob/main/vulnclaw/cli/main.py) defines Typer sub-commands, while [`vulnclaw/cli/tui.py`](https://github.com/Unclecheng-li/VulnClaw/blob/main/vulnclaw/cli/tui.py) and [`vulnclaw/cli/tui_textual.py`](https://github.com/Unclecheng-li/VulnClaw/blob/main/vulnclaw/cli/tui_textual.py) manage the Textual dashboard and slash-command handling.
- **Configuration** – [`vulnclaw/config/schema.py`](https://github.com/Unclecheng-li/VulnClaw/blob/main/vulnclaw/config/schema.py) uses Pydantic models to define configuration schemas and environment variable overrides.
- **Skill System** – `vulnclaw/skills/` contains markdown-driven attack logic, with [`vulnclaw/skills/dispatcher.py`](https://github.com/Unclecheng-li/VulnClaw/blob/main/vulnclaw/skills/dispatcher.py) mapping natural-language intents to skill IDs.
- **Web Backend** – [`vulnclaw/web/app.py`](https://github.com/Unclecheng-li/VulnClaw/blob/main/vulnclaw/web/app.py) exposes FastAPI endpoints for task management, while `vulnclaw/web/services/` handles business logic.
- **Report Generation** – [`vulnclaw/report/generator.py`](https://github.com/Unclecheng-li/VulnClaw/blob/main/vulnclaw/report/generator.py) renders markdown and HTML output with PoC sections.

## Implement Changes by Subsystem

### Add a New Skill

Skills in VulnClaw are markdown-driven. To add a new capability like SQL injection payload generation:

1. Create a directory under `vulnclaw/skills/specialized/` (e.g., `sql-injection/`).
2. Add a [`SKILL.md`](https://github.com/Unclecheng-li/VulnClaw/blob/main/SKILL.md) file with YAML front-matter defining the name, description, and trigger keywords.
3. Update [`vulnclaw/skills/dispatcher.py`](https://github.com/Unclecheng-li/VulnClaw/blob/main/vulnclaw/skills/dispatcher.py) to register the intent mapping.

```markdown
---
name: sql-injection
description: Generate payloads for blind SQL injection
trigger:
  - "sql injection"
  - "sqli"
---

# SQLi Payload Generator

Step-by-step instructions here...

```

```python

# In vulnclaw/skills/dispatcher.py

SKILL_INTENT_MAP["sql-injection"] = ["sql injection", "sqli"]

```

The dispatcher acts as the bridge that turns natural-language intent into a skill lookup, as implemented in the Unclecheng-li/VulnClaw repository.

### Extend Agent Tools

To add a custom tool available to the LLM (e.g., an `nmap` wrapper), edit [`vulnclaw/agent/builtin_tools.py`](https://github.com/Unclecheng-li/VulnClaw/blob/main/vulnclaw/agent/builtin_tools.py) and use the `register_tool` function from the tool call manager.

```python

# vulnclaw/agent/builtin_tools.py

from .tool_call_manager import register_tool

def nmap_scan(target: str, ports: str = "1-65535") -> str:
    """Run nmap and return the raw stdout."""
    import subprocess, shlex
    cmd = f"nmap -p {shlex.quote(ports)} {shlex.quote(target)}"
    result = subprocess.run(cmd, shell=True, capture_output=True, text=True, timeout=120)
    return result.stdout

register_tool(
    name="nmap_scan",
    func=nmap_scan,
    description="Perform an nmap port scan on a target host."
)

```

The `tool_call_manager` handles deduplication and execution, embedding results back into the Agent's prompt loop. This pattern mirrors existing tools like `python_execute` and `mcp_bridge` defined in the same file.

### Modify CLI Behavior

For new CLI commands, edit [`vulnclaw/cli/main.py`](https://github.com/Unclecheng-li/VulnClaw/blob/main/vulnclaw/cli/main.py) using Typer to add sub-commands or modify output formatting. For TUI dashboard changes, modify [`vulnclaw/cli/tui.py`](https://github.com/Unclecheng-li/VulnClaw/blob/main/vulnclaw/cli/tui.py) to adjust layouts, slash-command handling, or popup dialogs.

## Validate Your Changes

Every contribution must pass the existing test suite and lint checks. Run the full backend test suite before submitting.

```bash
pytest -q

```

If you modified the frontend, run the Node.js test suite.

```bash
npm run test

```

The repository uses GitHub Actions ([`.github/workflows/ci.yml`](https://github.com/Unclecheng-li/VulnClaw/blob/main/.github/workflows/ci.yml)) to enforce these checks automatically. Additionally, verify that no secrets are exposed in your code, as the repository maintains a strict security policy against embedding credentials.

## Submit a Pull Request

Push your feature branch to your fork and open a PR against the `main` branch. Fill out the PR template provided in `.github/ISSUE_TEMPLATE/` and verify the following checklist from [`CONTRIBUTING.md`](https://github.com/Unclecheng-li/VulnClaw/blob/main/CONTRIBUTING.md):

- All tests pass (`pytest -q`).
- Documentation is updated (add entries to the Skill Index in [`README.md`](https://github.com/Unclecheng-li/VulnClaw/blob/main/README.md) and update CLI usage tables if flags changed).
- Version is bumped in [`pyproject.toml`](https://github.com/Unclecheng-li/VulnClaw/blob/main/pyproject.toml) and [`vulnclaw/__init__.py`](https://github.com/Unclecheng-li/VulnClaw/blob/main/vulnclaw/__init__.py) if you modified the public API.
- No security-related secrets are introduced.

## Summary

- **Fork and Branch**: Create a feature branch from your fork of Unclecheng-li/VulnClaw.
- **Target the Right Module**: Edit the component that owns the behavior—Agent logic in `vulnclaw/agent/`, Skills in `vulnclaw/skills/`, and CLI in `vulnclaw/cli/`.
- **Use the Dispatcher**: Register new skills in [`vulnclaw/skills/dispatcher.py`](https://github.com/Unclecheng-li/VulnClaw/blob/main/vulnclaw/skills/dispatcher.py) to map intents to skill IDs.
- **Register Tools**: Add custom capabilities via `register_tool()` in [`vulnclaw/agent/builtin_tools.py`](https://github.com/Unclecheng-li/VulnClaw/blob/main/vulnclaw/agent/builtin_tools.py).
- **Test Thoroughly**: Run `pytest -q` and ensure CI passes via [`.github/workflows/ci.yml`](https://github.com/Unclecheng-li/VulnClaw/blob/main/.github/workflows/ci.yml).
- **Document Changes**: Update [`README.md`](https://github.com/Unclecheng-li/VulnClaw/blob/main/README.md), skill indices, and usage tables alongside your code.

## Frequently Asked Questions

### Where should I add unit tests for new skills?

Add unit tests under [`tests/test_skills.py`](https://github.com/Unclecheng-li/VulnClaw/blob/main/tests/test_skills.py) to ensure the skill loads correctly and the dispatcher resolves intents. Verify that the skill body contains expected content and that trigger keywords map to the correct skill ID according to the [`vulnclaw/skills/dispatcher.py`](https://github.com/Unclecheng-li/VulnClaw/blob/main/vulnclaw/skills/dispatcher.py) logic.

### How do I register a new tool for the LLM Agent?

Import `register_tool` from `vulnclaw/agent/tool_call_manager` in [`vulnclaw/agent/builtin_tools.py`](https://github.com/Unclecheng-li/VulnClaw/blob/main/vulnclaw/agent/builtin_tools.py), define your function with type hints and proper shell escaping, and pass it to `register_tool()` with a name and description. The Agent will automatically discover it via the tool call manager and make it available for LLM invocation.

### What documentation must be updated when contributing to VulnClaw?

Update the Skill Index in [`README.md`](https://github.com/Unclecheng-li/VulnClaw/blob/main/README.md) (or [`README_EN.md`](https://github.com/Unclecheng-li/VulnClaw/blob/main/README_EN.md)) for new skills, modify the CLI usage table in [`vulnclaw/cli/main.py`](https://github.com/Unclecheng-li/VulnClaw/blob/main/vulnclaw/cli/main.py) if you added flags, and bump the version in [`pyproject.toml`](https://github.com/Unclecheng-li/VulnClaw/blob/main/pyproject.toml) and [`vulnclaw/__init__.py`](https://github.com/Unclecheng-li/VulnClaw/blob/main/vulnclaw/__init__.py) for public API changes. Always reference [`CONTRIBUTING.md`](https://github.com/Unclecheng-li/VulnClaw/blob/main/CONTRIBUTING.md) for the full checklist and follow the "right-place" rule to document changes in the module that owns the behavior.

### How does the Skill dispatcher map natural language to skills?

The [`vulnclaw/skills/dispatcher.py`](https://github.com/Unclecheng-li/VulnClaw/blob/main/vulnclaw/skills/dispatcher.py) file contains a `SKILL_INTENT_MAP` dictionary that associates skill IDs with trigger keywords. When the Agent receives natural language input, it searches this map to identify which skill markdown file to load and execute, enabling the modular, markdown-driven architecture of the framework.