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

The reverse-skill router parses user hints to select a PRIMARY SKILL.md file via keyword matching in routing.json, validates its existence, and emits a route-scope.md report for downstream execution.

The zhaoxuya520/reverse-skill repository implements a deterministic skill routing system where 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 files.

Stage 1: Hint Normalization

The router normalizes user input to ensure consistent matching:

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

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

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

- 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 follows a strict YAML front-matter + markdown body architecture designed to separate machine-readable metadata from human-readable workflows.

Machine-Readable Front-Matter

---
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 generation

The router itself never parses the body content—only routing.json determines which 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 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 by scanning all SKILL.md files:

# 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 -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 reveals the ## ACTION REQUIRED block directing the analyst's first move.

---

Key Implementation Files

Path	Function
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 resolution
skills/scripts/extract-summaries.ps1	Front-matter extractor for INDEX.md generation
skills/MASTER-ROUTING.md	Human documentation of routing contracts
skills/*/SKILL.md	Individual execution modules

---

Summary

• Structure: SKILL.md files combine YAML front-matter (name, description) with free-form markdown bodies
• Processing: The router uses routing.json keyword rules to select, resolve, and validate SKILL.md paths without parsing body content
• Verification: Missing files trigger exit code 2; successful routing emits 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, 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. 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 for matching. The 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 with proper front-matter, then register it in 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.

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