# SKILL.md Structure and Router Processing in reverse-skill: A Complete Guide

> Understand the SKILL.md structure and how the reverse-skill router processes it. Learn how hints, routing.json, and route-scope.md enable skill execution.

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

---

**The reverse-skill router parses user hints to select a PRIMARY [`SKILL.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/SKILL.md) file via keyword matching in [`routing.json`](https://github.com/zhaoxuya520/reverse-skill/blob/main/routing.json), validates its existence, and emits a [`route-scope.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/route-scope.md) report for downstream execution.**

The [zhaoxuya520/reverse-skill](https://github.com/zhaoxuya520/reverse-skill) repository implements a deterministic skill routing system where [`SKILL.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/SKILL.md) files serve as execution entry points. Understanding the structure and processing of these files reveals how the system transforms free-form user input into concrete analytical workflows.

---

## How the Router Processes SKILL.md Files

The routing pipeline in `skills/scripts/master-route.ps1` follows five deterministic stages to process [`SKILL.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/SKILL.md) files.

### Stage 1: Hint Normalization

The router normalizes user input to ensure consistent matching:

```powershell
$hintNormalized = $Hint.ToLowerInvariant()

```

This standardized string feeds into the regex-based keyword matching engine.

### Stage 2: Route Scoring

Each route in [`skills/config/routing.json`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/config/routing.json) carries matching rules:

- **`must`** – regex that must match (adds to score)
- **`mustAll`** – all patterns must match for consideration
- **`exclude`** – disqualifies the route if matched

The script increments a per-route score for every hit, then selects the highest-scoring route that appears earliest in the `priority` array.

### Stage 3: Path Resolution

Once a primary route ID is selected, the router resolves the actual file path:

```powershell
$primaryPath = $cfg.routes.$primary.skill          # "attack-chain/SKILL.md"

$skillAbs = Join-Path $skillsRoot (
              $primaryPath -replace '/', 
              [IO.Path]::DirectorySeparatorChar)  # → /.../skills/attack-chain/SKILL.md

```

The `skill` field in [`routing.json`](https://github.com/zhaoxuya520/reverse-skill/blob/main/routing.json) stores a relative path that gets converted to an absolute path for verification.

### Stage 4: Existence Verification

The router validates the target file before proceeding:

```powershell
if (-not (Test-Path $skillAbs)) {
    Write-Host "ERROR: PRIMARY skill file not found: $skillAbs" -ForegroundColor Red
    exit 2
}

```

Failure aborts with exit code 2, preventing downstream errors.

### Stage 5: Report Generation

The router writes [`route-scope.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/route-scope.md) containing:

```markdown
- primary_skill: skills/attack-chain/SKILL.md
- confidence: high
- secondary_candidates: skills/reverse-core/SKILL.md, skills/dynamic-analysis/SKILL.md

```

This machine-readable report enables subsequent tools like `case-init.ps1` to load the correct execution context.

---

## SKILL.md File Structure and Format

Every [`SKILL.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/SKILL.md) follows a strict **YAML front-matter + markdown body** architecture designed to separate machine-readable metadata from human-readable workflows.

### Machine-Readable Front-Matter

```yaml
---
name: attack-chain
description: |
  Use for authorized multi-stage attack-path planning and vulnerability chaining assessments
---

```

**Front-matter fields:**

- **`name`** – optional human identifier; defaults to the containing folder name if omitted
- **`description`** – searchable summary extracted by `extract-summaries.ps1` for [`INDEX.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/INDEX.md) generation

The router itself never parses the body content—only [`routing.json`](https://github.com/zhaoxuya520/reverse-skill/blob/main/routing.json) determines which [`SKILL.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/SKILL.md) executes.

### Human-Readable Body Sections

| Section | Purpose |
|---------|---------|
| `# <Skill Name>` | Document title for visual identification |

| `## ACTION REQUIRED` | **Critical:** the immediate next step for the analyst |

| `## 何时路由到本 Skill` | Routing criteria narrative (mirrors [`routing.json`](https://github.com/zhaoxuya520/reverse-skill/blob/main/routing.json) rules) |

| Workflow sections (`## 编排原则`, `## 完整攻击链阶段`) | Detailed playbooks for execution |

This structure enables authors to write rich documentation without affecting routing logic.

---

## SKILL.md Indexing and Discovery

The `extract-summaries.ps1` script (lines 41-73) generates a browsable [`INDEX.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/INDEX.md) by scanning all [`SKILL.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/SKILL.md) files:

```powershell

# Read first 15 lines to locate front-matter

$content = Get-Content $skillFile -TotalCount 15
if ($content[0] -match '^---') {
    $inFrontMatter = $true
    foreach ($line in $content[1..($content.Length-1)]) {
        if ($line -match '^---') { break }
        if ($line -match '^name:\s*(.+)') { $name = $matches[1].Trim() }
        if ($line -match '^description:\s*[|]?\s*(.+)') { $desc = $matches[1].Trim() }
    }
}

```

This lightweight parser intentionally limits scope to maintain performance across the skill library.

---

## Running the Router: Complete Example

Execute the routing pipeline with a user hint:

```powershell
powershell -NoProfile -ExecutionPolicy Bypass `
    -File skills\scripts\master-route.ps1 -Hint "apk reverse and root detection"

```

**Expected output:**

```

PRIMARY -> skills/apk-reverse/SKILL.md
Label: APK reverse | confidence: high
ACTION: Open PRIMARY SKILL.md now and execute ACTION REQUIRED.

```

The router creates a timestamped workspace:

```

work/
└── master-route-20260818-123456/
    └── route-scope.md    # Contains primary_skill reference

```

Opening [`skills/apk-reverse/SKILL.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/apk-reverse/SKILL.md) reveals the `## ACTION REQUIRED` block directing the analyst's first move.

---

## Key Implementation Files

| Path | Function |
|------|----------|
| [`skills/config/routing.json`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/config/routing.json) | Single source of truth: route definitions, keyword rules, priority ordering |
| `skills/scripts/master-route.ps1` | Core router: hint matching, scoring, [`SKILL.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/SKILL.md) resolution |
| `skills/scripts/extract-summaries.ps1` | Front-matter extractor for [`INDEX.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/INDEX.md) generation |
| [`skills/MASTER-ROUTING.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/MASTER-ROUTING.md) | Human documentation of routing contracts |
| `skills/*/SKILL.md` | Individual execution modules |

---

## Summary

- **Structure:** [`SKILL.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/SKILL.md) files combine YAML front-matter (`name`, `description`) with free-form markdown bodies
- **Processing:** The router uses [`routing.json`](https://github.com/zhaoxuya520/reverse-skill/blob/main/routing.json) keyword rules to select, resolve, and validate [`SKILL.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/SKILL.md) paths without parsing body content
- **Verification:** Missing files trigger exit code 2; successful routing emits [`route-scope.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/route-scope.md) for downstream consumption
- **Indexing:** `extract-summaries.ps1` scans front-matter to build navigation indexes
- **Separation of concerns:** Machine-visible contracts ([`routing.json`](https://github.com/zhaoxuya520/reverse-skill/blob/main/routing.json), front-matter) remain distinct from human-visible playbooks (markdown body)

---

## Frequently Asked Questions

### What happens if two routes have the same score?

The router selects whichever route appears **earlier in the `priority` array** in [`routing.json`](https://github.com/zhaoxuya520/reverse-skill/blob/main/routing.json). This deterministic tie-breaker ensures consistent behavior.

### Can the router parse SKILL.md body content to improve matching?

No. The `master-route.ps1` script exclusively uses [`routing.json`](https://github.com/zhaoxuya520/reverse-skill/blob/main/routing.json) for matching. The [`SKILL.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/SKILL.md) body is purely for human consumption, though authors should align their `## 何时路由到本 Skill` sections with the actual routing rules.

### How do I add a new skill to the system?

Create a new folder under `skills/`, add your [`SKILL.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/SKILL.md) with proper front-matter, then register it in [`skills/config/routing.json`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/config/routing.json) with appropriate `must`/`exclude` patterns and a priority position.

### What is the purpose of the route-scope.md file?

It serves as a **machine-readable handoff document** that records the primary skill path, confidence level, and secondary candidates. Downstream tools like case initialization scripts consume this to establish the correct execution context without re-running the router.