What Is the Purpose of AGENTS.md in the reverse-skill Repository?

AGENTS.md serves as the architectural blueprint and high-level entry point for the reverse-skill repository, defining how security-task routing, authorization gates, and platform-agnostic initialization work across reverse engineering and penetration testing workflows.

The reverse-skill repository is a platform-agnostic framework designed for security professionals performing reverse engineering, penetration testing, and security analysis tasks. Located at the repository root, AGENTS.md acts as the single source of human-readable documentation that governs how the system routes requests, enforces authorization, and maintains compatibility across different operating systems and AI client implementations.

Architectural Overview of AGENTS.md

AGENTS.md functions as the central orchestration guide that sits above the implementation layer. According to the reverse-skill source code, this file documents the core architectural concepts that drive the entire repository, ensuring that both automated agents and human operators understand the initialization sequence, security boundaries, and routing conventions before executing any security tasks.

The document establishes six critical pillars: project scope definition, routing pipeline logic, authorization hard rules, first-run tooling setup, cross-platform testing requirements, and strict decoupling from specific AI client implementations.

Routing Logic and Entry Points

The routing system described in AGENTS.md determines which script or configuration executes when a user request matches security-related keywords.

Primary Routing Pipeline

The single source of truth for routing rules resides in skills/config/routing.json. When a task request enters the system, the primary entry point is skills/MASTER-ROUTING.md or its platform-specific script equivalents:

# Linux/macOS entry

bash skills/scripts/master-route.sh --hint "<task>"

# Windows PowerShell entry

powershell -NoProfile -ExecutionPolicy Bypass -File skills/scripts/master-route.ps1 -Hint "<task>"

Fallback Mechanisms

When requests are ambiguous or do not match primary routing patterns, the system falls back to the full routing matrix defined in skills/routing.md. This ensures comprehensive coverage while maintaining a clean primary execution path for common security tasks.

Authorization Gates and Security Controls

Before any act phase executes, AGENTS.md mandates a strict authorization gate that cannot be bypassed.

Case Scope Initialization

The repository enforces the creation of a case-specific scope file at work/<case>/scope.md via platform-specific initialization scripts:

# Initialize case scope (Linux/macOS)

bash skills/scripts/case-init.sh --hint "<task>"

# Initialize case scope (Windows)

powershell -File skills/scripts/case-init.ps1 -Hint "<task>"

The Hard Rule Enforcement

The authorization guard (case-guard --force) represents a hard rule that must pass before action execution. For offline samples, users must specify an explicit offline-sample preset and obtain a granted auth.status. This design ensures that only authorized contexts with properly defined scopes can execute potentially destructive security operations, preventing accidental execution against unintended targets.

First-Run Setup and Tool Indexing

AGENTS.md specifies an initialization sequence that generates skills/tool-index.md on first use. This dynamic index catalogs available security tools and their configurations.

Users must refresh this index using platform-appropriate scripts when tools are added or updated:

# Refresh tool index (Linux/macOS)

bash skills/scripts/refresh-tool-index.sh

# Refresh tool index (Windows)

powershell -NoProfile -ExecutionPolicy Bypass -File skills/scripts/refresh-tool-index.ps1

Missing tools are automatically installed via bootstrap scripts specific to each platform, ensuring the environment meets the requirements documented in the master routing configuration.

Testing Requirements for Routing Parity

Any modification to routing logic, skill definitions, or bootstrap configurations requires validation through a standardized test suite. AGENTS.md mandates routing and bootstrap tests to guarantee parity across operating systems:

# Run routing regression tests (Linux/macOS)

bash skills/scripts/test-routing.sh

# Run routing regression tests (Windows)

powershell -NoProfile -ExecutionPolicy Bypass -File skills/scripts/test-routing.ps1

# Verify bootstrap manifest

bash skills/scripts/test-bootstrap-manifest.sh

These tests ensure that behavior remains consistent whether the repository runs on Linux, macOS, or Windows environments.

Client Agnostic Design

A critical architectural decision documented in AGENTS.md is the deliberate decoupling of core logic from AI client implementations. The routing, testing, and tool-manifest systems function independently of specific clients such as Claude Code, Codex, Cursor, or OpenCode.

The dynamic skills/INDEX.md is generated from all SKILL.md files throughout the repository, maintaining a client-agnostic interface. This abstraction layer allows the reverse-skill framework to operate across different AI-assisted development environments without vendor lock-in or client-specific modifications.

Summary

• AGENTS.md is the architectural entry point for the reverse-skill repository, documenting platform-agnostic security task routing.
• Routing logic flows from skills/config/routing.json through skills/MASTER-ROUTING.md or platform-specific scripts like master-route.sh and master-route.ps1.
• Authorization gates enforce case-specific scope creation at work/<case>/scope.md via unbypassable case-guard --force checks.
• First-run initialization generates skills/tool-index.md through refresh scripts that handle cross-platform tool installation.
• Testing requirements include test-routing.sh, test-routing.ps1, and test-bootstrap-manifest.sh to maintain OS parity.
• Client agnosticism ensures compatibility with Claude Code, Codex, Cursor, and OpenCode through dynamic SKILL.md indexing.

Frequently Asked Questions

What happens if I try to run a security task without initializing a case scope first?

The case-guard --force mechanism will block execution. According to the authorization rules in AGENTS.md, every action phase requires a valid work/<case>/scope.md file created through the initialization scripts (case-init.sh or case-init.ps1). This hard rule prevents unauthorized operations against undefined targets.

How does AGENTS.md differ from the routing.json configuration file?

While skills/config/routing.json serves as the machine-readable single source of truth for routing rules, AGENTS.md provides the human-readable architectural context explaining how to use those rules. The markdown file documents the intent behind the routing pipeline, authorization requirements, and testing protocols, whereas the JSON file contains the structured data that scripts consume.

Can I use reverse-skill with AI clients other than Claude Code?

Yes. AGENTS.md explicitly states that the repository is decoupled from AI client implementations. The framework generates skills/INDEX.md dynamically from SKILL.md files, making it compatible with Claude Code, Codex, Cursor, OpenCode, and future clients without requiring modifications to the core routing logic.

What is the offline-sample preset mentioned in AGENTS.md?

The offline-sample preset is a specific authorization mode required when working with offline sample data. When this preset is active, the system additionally checks for a granted auth.status before permitting the case-guard --force validation to pass, adding an extra layer of verification for detached analysis environments.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}