How to Extend the Functionality of reverse-skill: A Complete 7-Step Guide

Extending reverse-skill requires creating a self-contained skill module, registering it in the routing matrix, declaring dependencies in the bootstrap manifest, and validating through the case workflow system.

reverse-skill is a modular skill router developed by zhaoxuya520/reverse-skill that automatically directs security and reverse-engineering requests to appropriate sub-skills. Its four-layer architecture—routing layer, skill modules, bootstrap system, and ops contracts—provides a systematic framework for adding new capabilities without disrupting existing workflows.

Understanding the reverse-skill Architecture

Before extending functionality, you need to understand how components interact. The system architecture, documented in [docs/ARCHITECTURE.md](https://github.com/zhaoxuya520/reverse-skill/blob/main/docs/ARCHITECTURE.md), consists of:

• Routing Layer – The matrix in [skills/routing.md](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/routing.md) maps target type + user intent + toolchain to concrete skill modules, consulted by the entry point [SKILL.md](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/SKILL.md)
• Skill Modules – Complete workflows in skills/<skill-name>/ containing scripts, references, and MCP-aware tools (e.g., skills/ida-reverse/)
• Bootstrap System – skills/scripts/bootstrap-reverse.ps1 reads [skills/scripts/bootstrap-manifest.json](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/scripts/bootstrap-manifest.json) to auto-install missing tools from GitHub releases, pip, npm, or winget
• Ops Contracts & Evidence Chain – The skills/ops/ directory defines case-init processes, evidence collection, and role contracts with findings written to field-journal/

Step 1: Define the New Skill Module

Create a folder at skills/<new-skill>/ with the required structure:

• SKILL.md – Metadata including name, description, and ACTION REQUIRED steps
• scripts/ – PowerShell or Bash helper scripts
• references/ – Optional markdown cheat-sheets
• examples/ – Sample inputs (optional)

Minimal "Hello World" Skill Example

# Create the skill directory

mkdir -p skills/hello-world/scripts

Create skills/hello-world/SKILL.md:

---
name: hello-world
description: |
  Demonstrates how to add a minimal skill. Prints a greeting and logs the request.
---

# Hello World Skill

## ACTION REQUIRED

1. NOW: Read the incoming task description.
2. ACT: Output a friendly greeting.

## Script

Create skills/hello-world/scripts/run.ps1:

param([string]$Task)
Write-Host "👋 Hello from reverse-skill! You asked: $Task"

Step 2: Add Routing Entries in skills/routing.md

Extend the routing matrix to recognize when to invoke your new skill. Edit [skills/routing.md](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/routing.md) and append rows to the appropriate tables using standard markdown syntax:

By Target Type	Skill Path
Custom Firmware	skills/custom-firmware/
demo / Hello world	skills/hello-world/

By User Intent	Skill Path
"decode my .bin"	skills/custom-firmware/
"say hello"	skills/hello-world/

The router matches against target type, user intent, and available toolchain to select the appropriate skill.

Step 3: Update the Bootstrap Manifest for Tool Dependencies

If your skill requires external tools, declare them in [skills/scripts/bootstrap-manifest.json](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/scripts/bootstrap-manifest.json):

{
  "name": "my-analyser",
  "bootstrapKind": "pip-package",
  "pipPackage": "my-analyser",
  "docsUrl": "https://github.com/me/my-analyser",
  "canAutoInstall": true,
  "verifyCommand": "my-analyser"
}

Supported bootstrapKind values include:

• github-release – Download from GitHub releases with assetRegex matching
• pip-package – Install via pip
• npm-package – Install via npm
• winget – Install via Windows Package Manager
• manual – Requires user installation with documented steps

Step 4: Register Tools and Refresh the Index

Run the platform-specific refresh script to regenerate skills/tool-index.md:

Windows:

powershell -File skills/scripts/refresh-tool-index.ps1

Linux/macOS:

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

Verify the output shows your tool as available:

✅ my-analyser – verified (my-analyser --version)

The router uses skills/tool-index.md to validate tool availability before invoking a skill.

Step 5: Write Ops Contracts for Audit Compliance

Create skills/ops/<new-skill>-contract.md to declare scope boundaries, evidence requirements, and role assignments:

# Contract: hello-world

## Scope

- Input: Any text string
- Output: Console greeting + journal entry
- No privileged operations required

## Evidence Requirements

- Task description preserved
- Execution timestamp logged

## Role Mapping

- EXECUTOR: Any authenticated agent
- AUDITOR: Optional review of journal entry

This enables automatic pre-execution validation and maintains the evidence chain required for security workflows.

Step 6: Test the Complete Routing Flow

Initialize a test case and exercise the new skill path:

# Create a case workspace (generates work/<case-id>/)

powershell -File skills/scripts/case-init.ps1 -CaseName "hello-test"

# Invoke the router with intent matching your new skill

powershell -File skills/scripts/master-route.ps1 -Task "say hello"

Expected validation checklist:

• Router selects skills/hello-world/
• tool-index.md reports all required tools as available
• skills/hello-world/scripts/run.ps1 executes without error
• Journal entry appears in field-journal/hello-world.md

If routing fails, check the "Route-Not-Matched" protocol in routing.md—the system should propose your new skill rather than forcing an inappropriate match.

Step 7: Document and Publish

Add usage instructions to README.md and update CHANGELOG.md. The repository's CI pipeline automatically updates the star-history badge and changelog on push.

Document:

• When to use your new skill (target type + intent patterns)
• Required tools and installation method
• Example inputs and expected outputs
• Any security considerations or role requirements

Summary

To extend reverse-skill functionality, follow this systematic approach:

• Create a self-contained skill module in skills/<name>/ with SKILL.md, scripts, and optional references
• Register routing patterns in skills/routing.md for target type and user intent matching
• Declare tool dependencies in skills/scripts/bootstrap-manifest.json with appropriate bootstrapKind
• Refresh the tool index to validate availability via refresh-tool-index.ps1 or .sh
• Define ops contracts in skills/ops/ for scope, evidence, and role mapping
• Test end-to-end using case-init.ps1 and master-route.ps1 with sample tasks
• Document usage in README.md and push to trigger CI updates

Frequently Asked Questions

What file format does SKILL.md use?

SKILL.md uses YAML frontmatter for metadata (name, description) followed by markdown content with an ACTION REQUIRED section declaring immediate and action steps. This structure enables both human readability and automated parsing by the router.

Can I extend an existing skill instead of creating a new one?

Yes. Enhance existing skills by adding scripts to skills/<existing>/scripts/, extending the references/ documentation, or modifying the skill's SKILL.md workflow. Maintain backward compatibility—new capabilities should be additive or gated behind explicit user intent patterns in routing.md.

How does the bootstrap system handle tool version conflicts?

The bootstrap-manifest.json schema includes versionConstraint and verifyCommand fields. When canAutoInstall is true, the system attempts installation only after checking verifyCommand returns a compatible version. Conflicts are logged to field-journal/ with guidance for manual resolution.

What happens if my skill's required tool is unavailable?

The router checks skills/tool-index.md before execution. If tools are missing, it invokes bootstrap-reverse.ps1 for auto-installation (when canAutoInstall: true). For manual-only tools, the router emits a guidance message with the docsUrl from the manifest and halts execution pending user action.

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