Expected Directory Structure for a New Skill Module in reverse-skill

A new skill module must follow a strict folder layout under skills/<new-skill-name>/ with a mandatory SKILL.md entry point and optional scripts/ and references/ subdirectories.

The zhaoxuya520/reverse-skill repository enforces this structure for automatic discovery by the AI routing system, tool-index refresh scripts, and bootstrap manifest. Deviating from this layout breaks pipeline integration.

Where Skills Live: The skills/ Directory

Every skill module resides under the top-level skills/ folder. This centralizes discovery for:

• AI routing – the routing matrix scans skills/ to build navigation paths
• Tool indexing – scripts/refresh-tool-index.ps1 crawls subdirectories for executable scripts
• Bootstrap integration – bootstrap-manifest.json references skill paths for auto-installation

The naming convention is strict: lower-case English letters and hyphens only (e.g., firmware-reverse, not firmware_reverse or 固件分析). This guarantees deterministic path resolution across Windows, Linux, and CI pipelines as defined in CONTRIBUTING.md and RULES.md.

Mandatory and Optional Subdirectories

Each skill directory contains three possible levels:

Component	Required	Purpose
SKILL.md	Yes	Manifest declaring name, description, workflow, and mandatory sections
scripts/	No	PowerShell, Bash, or other automation scripts
references/	No	Cheat-sheets, research notes, external links

Complete Directory Template

skills/
└── <new-skill-name>/
    ├── SKILL.md              # 必须：skill 入口文档

    ├── scripts/              # 可选：自动化脚本

    │   └── <workflow>.ps1
    └── references/           # 可选：参考资料、速查表

        └── <topic>.md

(Source: skills/CONTRIBUTING.md, "2. 目录结构模板")

The SKILL.md Manifest: Required Structure

SKILL.md is the non-negotiable entry point. It must contain:

1. YAML front-matter with name: and description: fields
2. ACTION REQUIRED section – immediate execution steps marked with NOW, NEXT, ACT
3. 工作流 – the step-by-step workflow
4. 任务完成自检 – self-check checklist
5. 路由上下文 – upstream/downstream routing relationships

Example: skills/firmware-reverse/SKILL.md

---
name: firmware-reverse
description: Reverse‑engineer embedded firmware images without IDA.
---

# Firmware Reverse Engineering

## ACTION REQUIRED（读完后立刻执行）

1. `NOW`：读取 `../field-journal/precedent-reverse.md`，确认授权范围。  
2. `NOW`：检查 `../tool-index.md` 中的 `binwalk` 可用性。  
3. `NEXT`：若缺工具，调用 `bootstrap-reverse.ps1` 自动安装。  
4. `ACT`：执行 `scripts/extract.ps1` 开始提取。

## 工作流

1. 使用 `binwalk` 进行固件分段。  
2. 运行自定义脚本解析文件系统。  
3. 生成阶段性报告并写入 `work/<case>/evidence/`。

## 任务完成自检

- [ ] 是否完整执行了工作流每一步？  
- [ ] 是否产出可复现的证据文件？  
- [ ] 是否更新了路由矩阵？  

## 路由上下文

**上游**: MASTER → **下游**: docs‑generator，报告输出

Populating scripts/ and references/

Adding Automation Scripts

Scripts in scripts/ are referenced from SKILL.md via relative paths:

# skills/firmware-reverse/scripts/extract.ps1

param(
    [Parameter(Mandatory)][string]$ImagePath
)

$binwalk = Resolve-Path (Join-Path $PSScriptRoot '..' '..' '..' 'tools' 'binwalk.exe')
& $binwalk $ImagePath -e -C "$ImagePath.extracted"
Write-Host "Extraction complete. Results in $ImagePath.extracted"

Referenced in SKILL.md:

## 工作流

1. `ACT`: `scripts/extract.ps1 -ImagePath <firmware.bin>`

Adding Reference Materials

The references/ folder holds supporting documentation without polluting the skill root. Typical contents include format specifications, attack technique summaries, or external URLs.

Files to Update After Creating the Directory

Creating the directory structure alone is insufficient. You must update these repository-level files:

File	Required Change
skills/routing.md	Add routing matrix entry mapping upstream/downstream relationships
skills/scripts/refresh-tool-index.ps1	Add $scriptRefs entry for any new scripts
scripts/bootstrap-manifest.json	Declare new external tools for auto-installation
skills/SKILL.md (root)	Add aggregate entry for AI's top-level menu

Summary

• All skills live under skills/<name>/ with lower-case, hyphen-separated names
• SKILL.md is mandatory and must include YAML front-matter plus four required sections
• scripts/ and references/ are optional but recommended for automation and documentation
• Four repository files need manual updates after creating the directory: routing.md, refresh-tool-index.ps1, bootstrap-manifest.json, and root SKILL.md
• The structure is enforced by discovery pipelines; deviations break routing and bootstrapping

Frequently Asked Questions

What characters are allowed in the skill directory name?

Only lower-case English letters (a-z) and hyphens (-). Underscores, Chinese characters, numbers, and spaces are prohibited. This ensures cross-platform path resolution in Windows, Linux, and CI environments as specified in CONTRIBUTING.md and RULES.md.

What happens if I omit SKILL.md?

The skill becomes invisible to the AI routing system. The routing matrix, bootstrap manifest, and documentation pipelines all depend on parsing SKILL.md for metadata. Without it, the directory is treated as orphaned data.

Can I use Python scripts instead of PowerShell in scripts/?

Yes. The directory structure accepts any executable file type. However, refresh-tool-index.ps1 specifically catalogs script references, so cross-platform skills should provide both PowerShell and Bash variants when targeting mixed Windows/Kali deployments.

How does the references/ folder differ from external links in SKILL.md?

The references/ folder stores local, version-controlled content (cheat-sheets, research notes) referenced via relative paths. External links in SKILL.md point to external URLs. Local references ensure offline availability and audit trails critical to security workflows.

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