Understanding the Role-Map: How Roles Are Assigned to Skills in reverse-skill

The role-map in the reverse-skill repository is a structured configuration file (skills/ops/role-map.md) that defines operational roles like lead, specialist, cre, cie, and cpe, and assigns them to specific skills through the master routing engine to ensure correct agent engagement during security workflows.

The zhaoxuya520/reverse-skill project implements a rigorous role-based access system for security investigations. At the center of this system lies the role-map, a dedicated configuration that determines which operator or agent executes each stage of a skill workflow. This article examines the structure of skills/ops/role-map.md and explains how the routing engine assigns these roles to skills during case execution.

What Is the Role-Map in reverse-skill?

The role-map serves as the authoritative source for operational role definitions within the repository. Located at skills/ops/role-map.md, this file establishes a fixed set of responsibility tiers—including lead, specialist, cre (Customer Reliability Engineering), cie (Customer Incident Engineering), and cpe (Customer Platform Engineering)—and maps each role to concrete skills that operators must execute at specific workflow stages.

Rather than allowing arbitrary role assignment, the reverse-skill framework requires that every phase of a security investigation explicitly reference this mapping. This ensures that only designated experts perform critical actions, creating an auditable chain of custody for forensic activities.

Core Components of the Role-Map Structure

The role-map defines three critical fields that govern how skills are delegated:

lead_role

The lead_role field identifies the primary executor for the current investigation phase. According to the source code in skills/ops/role-map.md, the routing logic explicitly designates the main skill and sets lead_role=lead when initiating a workflow phase. This assignment establishes who holds primary responsibility for the investigation's current stage.

specialist_roles

The specialist_roles[] array specifies optional additional experts required for complex phases. The role-map documentation describes how to "指定 specialist_roles[] 与 handoff 条件" (specify specialist_roles[] and handoff conditions), allowing the system to bring in domain-specific expertise—such as cie or cpe—when the primary skill requires supplemental capabilities.

handoff Rules

The handoff field contains transition logic that triggers role changes when specific conditions are met. When a specialist completes their assigned task, the handoff mechanism ensures the workflow returns to the lead or transitions to the next appropriate role, maintaining continuity without manual intervention.

How Roles Are Assigned to Skills

Role assignment occurs through an integrated routing system that consults the role-map at multiple execution points:

Master Routing Integration

The master routing engine (skills/MASTER-ROUTING.md) pulls lead and specialist definitions directly from the role-map when constructing primary skill requests. As implemented in the source, the routing system references the role-map definitions to set the lead and specialist parameters before dispatching any skill execution command.

Scope Contract Persistence

Once roles are determined, the scope contract (skills/ops/scope-contract.md) records the chosen lead_role for traceability. This documentation step ensures that every case file contains a permanent record of which role was responsible for each action, supporting post-incident reviews and compliance audits.

Workflow Execution Checkpoints

Throughout the workflow lifecycle—including skills/routing.md, skills/SKILL.md, and the governing RULES.md—the system references the role-map to verify the correct person or agent is engaged before any ACT operation is performed. This verification prevents unauthorized execution of sensitive forensic commands.

In practice, the workflow begins when case-init.ps1 generates a scope.md file. The operator then consults the role-map to determine which skill (primary or specialist) to launch, writes the selected roles into scope.md, and proceeds with execution only after the role-map validation confirms proper assignment.

Practical Implementation Examples

The following examples demonstrate how to assign roles using the reverse-skill framework:

# Example: Assigning a lead role for a new phishing investigation

# 1️⃣  Identify the primary skill (e.g., `phishing-analysis`)

# 2️⃣  Open the role-map and set lead_role

lead_role = lead               # see role-map.md line 22

specialist_roles = [cie, cpe] # optional specialists (line 24)

# 3️⃣  Record in the case scope

#   work/<case>/scope.md

lead_role: lead
specialist_roles:
  - cie
  - cpe

# PowerShell snippet used by the routing script

# Loads role-map values, injects them into the routing table

$roleMap = Get-Content -Path "$repoRoot/skills/ops/role-map.md"
$lead    = ($roleMap | Select-String 'lead_role').Line.Split('=')[1].Trim()
$spec    = ($roleMap | Select-String 'specialist_roles').Line -replace '.*\[(.*)\].*','$1' -split ',\s*'

# Build the routing request with the assigned roles

Invoke-MasterRoute -PrimarySkill $primary -Lead $lead -Specialists $spec

Summary

• The role-map (skills/ops/role-map.md) defines fixed operational roles including lead, specialist, cre, cie, and cpe for the reverse-skill framework.
• Role assignment occurs through the master routing engine, which consults the role-map to set lead_role and specialist_roles[] before executing any skill.
• The scope contract (skills/ops/scope-contract.md) persists role selections for audit trails, while RULES.md enforces role-map verification before any ACT operation.
• Handoff rules within the role-map manage transitions between primary and specialist roles during multi-stage investigations.

Frequently Asked Questions

What file defines the role-map in the reverse-skill repository?

The role-map is defined in skills/ops/role-map.md. This file contains the canonical definitions for all operational roles and their associated skill assignments, serving as the single source of truth for the routing engine.

How does the master routing system use the role-map?

According to skills/MASTER-ROUTING.md, the master routing system reads the lead_role and specialist_roles[] definitions from the role-map when building primary skill requests. This integration ensures that every routed skill includes the correct responsible parties before execution begins.

What is the difference between lead_role and specialist_roles?

The lead_role designates the primary executor responsible for the current investigation phase, while specialist_roles[] specifies optional domain experts brought in for specific technical requirements. The lead maintains overall case ownership, whereas specialists contribute targeted expertise under handoff conditions defined in the role-map.

Where is the assigned role recorded during a case?

Role assignments are recorded in the scope contract at skills/ops/scope-contract.md and persisted in the case-specific scope.md file generated by case-init.ps1. This documentation creates an auditable trail showing which role performed each action throughout the investigation lifecycle.

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