# What Is the Purpose of AGENTS.md in the reverse-skill Repository? > Discover AGENTS.md's purpose in the reverse-skill repository. It outlines security task routing, authorization, and platform-agnostic initialization for reverse engineering and pen testing. - Repository: [ZhaoXu/reverse-skill](https://github.com/zhaoxuya520/reverse-skill) - Tags: deep-dive - Published: 2026-08-29 --- **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`](https://github.com/zhaoxuya520/reverse-skill/blob/main/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`](https://github.com/zhaoxuya520/reverse-skill/blob/main/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`](https://github.com/zhaoxuya520/reverse-skill/blob/main/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`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/config/routing.json). When a task request enters the system, the primary entry point is [`skills/MASTER-ROUTING.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/MASTER-ROUTING.md) or its platform-specific script equivalents: ```bash # Linux/macOS entry bash skills/scripts/master-route.sh --hint "" # Windows PowerShell entry powershell -NoProfile -ExecutionPolicy Bypass -File skills/scripts/master-route.ps1 -Hint "" ``` ### 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`](https://github.com/zhaoxuya520/reverse-skill/blob/main/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`](https://github.com/zhaoxuya520/reverse-skill/blob/main/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//scope.md` via platform-specific initialization scripts: ```bash # Initialize case scope (Linux/macOS) bash skills/scripts/case-init.sh --hint "" # Initialize case scope (Windows) powershell -File skills/scripts/case-init.ps1 -Hint "" ``` ### 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`](https://github.com/zhaoxuya520/reverse-skill/blob/main/AGENTS.md) specifies an initialization sequence that generates [`skills/tool-index.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/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: ```bash # 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`](https://github.com/zhaoxuya520/reverse-skill/blob/main/AGENTS.md) mandates **routing and bootstrap tests** to guarantee parity across operating systems: ```bash # 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`](https://github.com/zhaoxuya520/reverse-skill/blob/main/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`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/INDEX.md) is generated from all [`SKILL.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/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`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/config/routing.json) through [`skills/MASTER-ROUTING.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/MASTER-ROUTING.md) or platform-specific scripts like [`master-route.sh`](https://github.com/zhaoxuya520/reverse-skill/blob/main/master-route.sh) and `master-route.ps1`. - **Authorization gates** enforce case-specific scope creation at `work//scope.md` via unbypassable `case-guard --force` checks. - **First-run initialization** generates [`skills/tool-index.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/tool-index.md) through refresh scripts that handle cross-platform tool installation. - **Testing requirements** include [`test-routing.sh`](https://github.com/zhaoxuya520/reverse-skill/blob/main/test-routing.sh), `test-routing.ps1`, and [`test-bootstrap-manifest.sh`](https://github.com/zhaoxuya520/reverse-skill/blob/main/test-bootstrap-manifest.sh) to maintain OS parity. - **Client agnosticism** ensures compatibility with Claude Code, Codex, Cursor, and OpenCode through dynamic [`SKILL.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/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`](https://github.com/zhaoxuya520/reverse-skill/blob/main/AGENTS.md), every action phase requires a valid `work//scope.md` file created through the initialization scripts ([`case-init.sh`](https://github.com/zhaoxuya520/reverse-skill/blob/main/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`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/config/routing.json) serves as the machine-readable **single source of truth** for routing rules, [`AGENTS.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/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`](https://github.com/zhaoxuya520/reverse-skill/blob/main/AGENTS.md) explicitly states that the repository is **decoupled from AI client implementations**. The framework generates [`skills/INDEX.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/INDEX.md) dynamically from [`SKILL.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/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.