# How SKILL.md Files Serve as Entry Points for Each Skill in the Reverse-Skill Framework

> Discover how SKILL.md files act as entry points in the Reverse-Skill Framework, connecting routing logic to specific skill actions. Learn more about this efficient system.

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

---

**Each [`SKILL.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/SKILL.md) file acts as the canonical entry point that bridges abstract routing logic with concrete, skill-specific actions after the router identifies the appropriate skill from [`config/routing.json`](https://github.com/zhaoxuya520/reverse-skill/blob/main/config/routing.json).**

The `reverse-skill` repository implements a modular, contract-driven architecture where every functional module—such as `reverse-engineering`, `apk-reverse`, or `windows-ad`—contains its own [`SKILL.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/SKILL.md). This markdown file becomes the single source of truth for executing workflows, validating contracts, and guiding operators or AI assistants through structured action blocks.

## Routing to the SKILL.md Entry Point

The platform-neutral router ([`scripts/master-route.sh`](https://github.com/zhaoxuya520/reverse-skill/blob/main/scripts/master-route.sh) or `scripts/master-route.ps1`) handles the initial handoff to the [`SKILL.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/SKILL.md) entry point. The process follows three distinct stages:

1. **Parse [`config/routing.json`](https://github.com/zhaoxuya520/reverse-skill/blob/main/config/routing.json)** – The router matches the user-provided hint against route definitions and selects a primary route ID (e.g., `R11`).

2. **Resolve skill path** – It extracts the `route["skill"]` value (e.g., `"reverse-engineering/SKILL.md"`) and writes it into [`route-scope.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/route-scope.md) as `primary_skill: skills/<skill-path>/SKILL.md`.

3. **Trigger action prompt** – The router outputs the mandatory instruction forcing the next step:

```bash

# From scripts/master-route.sh (lines 60-67)

echo "ACTION: Open PRIMARY SKILL.md now and execute ACTION REQUIRED."

```

This explicit prompt ensures no workflow proceeds without consulting the [`SKILL.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/SKILL.md) entry point, as implemented in the `reverse-skill` source code.

## SKILL.md Structure and Capabilities

Each [`SKILL.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/SKILL.md) follows a standardized structure that enables both human operators and automated systems to execute skill-specific workflows:

- **Front-matter metadata** – Skill name and description for indexing and validation
- **Capability list** – Supported toolchains, file formats, and environment requirements
- **Actionable sections** – `## ACTION REQUIRED` and `## NEXT STEPS` blocks containing executable instructions

- **Routing metadata** – References used by [`INDEX.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/INDEX.md) generators and contract validators

The master skill manifest at [`skills/SKILL.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/SKILL.md) enumerates all sub-skills and codifies the entry point workflow:

```markdown
---
name: skill-system
description: Master index and workflow orchestrator for all reverse-engineering skills.
---

# SKILL System Master Index

## Workflow

1. Run the router (`scripts/master-route.sh`)
2. Initialise the case (`scripts/case-init.sh`)
3. **Open the PRIMARY `SKILL.md`** identified in `route-scope.md`

```

This hierarchy ensures that [`SKILL.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/SKILL.md) functions as the gate between routing decisions and concrete execution.

## Contract Validation and the SKILL.md Entry Point

Helper scripts enforce the [`SKILL.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/SKILL.md) entry point contract before any action executes. The `verify-routing-coherence.ps1` script validates that [`route-scope.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/route-scope.md) contains a properly formed `primary_skill:` reference:

```powershell

# From scripts/verify-routing-coherence.ps1 (lines 33-38)

$skillHits = [regex]::Matches($Text, '(?m)^- primary_skill:\s*skills/(\S+)\s*$')
foreach ($hit in $skillHits) {
    $skillPath = $hit.Groups[1].Value
    # Validate that referenced SKILL.md exists and is readable

}

```

Similarly, [`case-init.sh`](https://github.com/zhaoxuya520/reverse-skill/blob/main/case-init.sh) and `case-init.ps1` write the `primary_skill:` marker into [`scope.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/scope.md) during case initialization, preventing any ACT step from proceeding without a validated entry point.

## SKILL.md Entry Point Example: Reverse Engineering Module

The [`reverse-engineering/SKILL.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/reverse-engineering/SKILL.md) demonstrates how an entry point translates routing decisions into actionable workflows:

```markdown
---
name: reverse-engineering
description: Core reverse-engineering workflow, static & dynamic analysis, de-obfuscation.
---

# Reverse Engineering

## ACTION REQUIRED

- Run static analysis with `r2` or `IDA`
- If dynamic hooks are needed, launch Frida scripts
- Document findings in `field-journal/_template.md`

## NEXT STEPS

- Cross-reference with `apk-reverse/SKILL.md` if Android-specific
- Escalate to `windows-ad/SKILL.md` for Active Directory artifacts

```

This structure allows the router to remain agnostic of implementation details while ensuring each skill module defines its own execution path.

## Key Files Supporting the SKILL.md Entry Point Pattern

| File | Role in Entry Point Flow |
|------|--------------------------|
| [`skills/SKILL.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/SKILL.md) | Master index listing all sub-skills and defining the entry-point workflow |
| `skills/<sub-skill>/SKILL.md` | Skill-specific entry point with capabilities and ACTION blocks |
| [`scripts/master-route.sh`](https://github.com/zhaoxuya520/reverse-skill/blob/main/scripts/master-route.sh) / `master-route.ps1` | Router that writes `primary_skill:` to [`route-scope.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/route-scope.md) and prompts for SKILL.md opening |
| [`config/routing.json`](https://github.com/zhaoxuya520/reverse-skill/blob/main/config/routing.json) | Route ID to skill path mappings (`"skill": "reverse-engineering/SKILL.md"`) |
| `scripts/verify-routing-coherence.ps1` | Validates `primary_skill:` presence and correctness in scope contracts |
| [`scripts/case-init.sh`](https://github.com/zhaoxuya520/reverse-skill/blob/main/scripts/case-init.sh) / `case-init.ps1` | Initializes cases with `primary_skill:` markers before ACT execution |

## Summary

- **[`SKILL.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/SKILL.md) is the canonical entry point** for every skill module in the `reverse-skill` framework, enforced by explicit router prompts and contract validation.
- **The router ([`master-route.sh`](https://github.com/zhaoxuya520/reverse-skill/blob/main/master-route.sh)/`master-route.ps1`) remains workflow-agnostic**, delegating all execution details to the referenced [`SKILL.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/SKILL.md).
- **Contract validators** (`verify-routing-coherence.ps1`, [`case-init.sh`](https://github.com/zhaoxuya520/reverse-skill/blob/main/case-init.sh)) ensure no action proceeds without a verified `primary_skill:` reference pointing to a valid [`SKILL.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/SKILL.md).
- **Standardized front-matter and ACTION blocks** enable both human operators and automated systems to parse and execute skill workflows consistently.

## Frequently Asked Questions

### What happens if the SKILL.md file is missing?

The `verify-routing-coherence.ps1` script fails validation when it cannot locate the file referenced by `primary_skill:`. This prevents case initialization from completing and blocks any subsequent ACT steps until the routing configuration is corrected.

### Can multiple SKILL.md files be active simultaneously?

The routing system designates a single **primary** [`SKILL.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/SKILL.md) per case via `primary_skill:` in [`route-scope.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/route-scope.md). However, the `## NEXT STEPS` sections within any [`SKILL.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/SKILL.md) can reference and direct workflow to other skill modules as needed.

### How does the router know which SKILL.md to select?

The router parses [`config/routing.json`](https://github.com/zhaoxuya520/reverse-skill/blob/main/config/routing.json), which maps route IDs to skill paths. When a user provides a hint matching a route pattern, the router extracts the `skill` field value and resolves it relative to the `skills/` directory root.

### Is the SKILL.md format compatible with automated parsing?

Yes. The front-matter block uses standard YAML syntax, while `## ACTION REQUIRED` and `## NEXT STEPS` headers provide predictable anchor points for parsing. The `verify-routing-coherence.ps1` script demonstrates programmatic extraction of skill references using regular expressions.