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

> Learn to extend the functionality of reverse-skill with our 7-step guide. Master skill module creation, registration, and validation for enhanced capabilities. Enhance your reverse-skill project today.

- Repository: [ZhaoXu/reverse-skill](https://github.com/zhaoxuya520/reverse-skill)
- Tags: how-to-guide
- Published: 2026-08-04

---

**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](https://github.com/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)](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)](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/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/`](https://github.com/zhaoxuya520/reverse-skill/tree/main/skills/ida-reverse))
- **Bootstrap System** – [`skills/scripts/bootstrap-reverse.ps1`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/scripts/bootstrap-reverse.ps1) reads [[`skills/scripts/bootstrap-manifest.json`](https://github.com/zhaoxuya520/reverse-skill/blob/main/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`](https://github.com/zhaoxuya520/reverse-skill/blob/main/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

```bash

# Create the skill directory

mkdir -p skills/hello-world/scripts

```

Create [`skills/hello-world/SKILL.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/hello-world/SKILL.md):

```markdown
---
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`:

```powershell
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)](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)](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/scripts/bootstrap-manifest.json):

```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`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/tool-index.md):

**Windows:**

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

```

**Linux/macOS:**

```bash
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`](https://github.com/zhaoxuya520/reverse-skill/blob/main/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:

```markdown

# 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:

```powershell

# 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`](https://github.com/zhaoxuya520/reverse-skill/blob/main/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`](https://github.com/zhaoxuya520/reverse-skill/blob/main/field-journal/hello-world.md)

If routing fails, check the **"Route-Not-Matched"** protocol in [`routing.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/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`](https://github.com/zhaoxuya520/reverse-skill/blob/main/README.md) and update [`CHANGELOG.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/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`](https://github.com/zhaoxuya520/reverse-skill/blob/main/SKILL.md), scripts, and optional references
- Register routing patterns in [`skills/routing.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/routing.md) for target type and user intent matching
- Declare tool dependencies in [`skills/scripts/bootstrap-manifest.json`](https://github.com/zhaoxuya520/reverse-skill/blob/main/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`](https://github.com/zhaoxuya520/reverse-skill/blob/main/README.md) and push to trigger CI updates

## Frequently Asked Questions

### What file format does SKILL.md use?

[`SKILL.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/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`](https://github.com/zhaoxuya520/reverse-skill/blob/main/SKILL.md) workflow. Maintain backward compatibility—new capabilities should be additive or gated behind explicit user intent patterns in [`routing.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/routing.md).

### How does the bootstrap system handle tool version conflicts?

The [`bootstrap-manifest.json`](https://github.com/zhaoxuya520/reverse-skill/blob/main/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`](https://github.com/zhaoxuya520/reverse-skill/blob/main/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.