Claude-Red Skill File Structure: Anatomy of a SKILL.md Document

A Claude-Red skill is a Markdown document (SKILL.md) with required YAML front-matter and a standardized body structure that lives under Skills/<category>/<skill-folder>/.

The SnailSploit/Claude-Red repository defines a strict format for offensive security skills used by Claude. Each skill follows a predictable structure defined in CONTRIBUTING.md that enables the AI to match techniques against operator conversations and deliver actionable, copy-paste-ready guidance.

File Location and Naming Requirements

Every skill must reside at a specific path within the repository hierarchy. According to CONTRIBUTING.md, the canonical file path is:

Skills/<category>/<skill-folder>/SKILL.md

The folder name must exactly match the name: field specified in the YAML front-matter. For example, a skill named offensive-sqli would live at Skills/web/offensive-sqli/SKILL.md. The claude-skills.json manifest file maps these paths and identifiers for the Claude Skills system to locate each document.

Required YAML Front-Matter

Every SKILL.md must begin with a YAML front-matter block delimited by triple dashes. This header provides the machine-readable identifier that Claude matches against during conversations.

---
name: offensive-<bug-class-or-domain>
description: "One paragraph (50-500 words) describing the surface, techniques covered, and when to use this skill."
---

The name field uses the offensive- prefix convention followed by the technique or domain identifier. The description provides the semantic context necessary for skill matching algorithms to surface the correct document.

Standard Body Sections

After the front-matter, the document follows a standardized Markdown structure designed for operator consumption.

Title and Framing Paragraph

The document body opens with an H1 title and a concise framing paragraph:

# <Short Skill Title>

One-sentence framing that tells the operator why this technique matters and what makes this skill unique.

The framing paragraph explains the attack surface and establishes the operational context for the techniques described.

Quick Workflow

The ## Quick Workflow section provides a numbered list of steps an operator should follow in the field:

## Quick Workflow

1. Enumerate the target surface
2. Identify the vulnerable component
3. Exploit the weakness
4. Document and clean up

This section appears early in the document to support time-constrained operations.

Technical Content Sections

The main content uses H2 headings (## <Section>) to organize techniques by phase or cluster (e.g., Detection, Exploitation, Post-Exploitation). Each section contains concrete, copy-paste-ready commands in fenced code blocks with explicit language identifiers:

# Example from offensive-sqli skill

sqlmap -u "http://target.com/page.php?id=1" --dbs

Code blocks must specify the language (e.g., bash, sql, python) to ensure proper syntax highlighting and parsing.

Optional Enhancements

While not strictly required, several optional sections add significant value for red team operations.

Detection and Defender View

The ## Detection / Defender View section lists logs, alerts, or artifacts that defenders might observe during execution. This helps operators understand their visibility footprint and potential detection points.

Engagement Cheatsheet

The ## Engagement Cheatsheet provides a condensed, ready-to-use summary of the methodology for quick reference during active operations.

Key References

Every skill should conclude with ## Key References, listing MITRE ATT&CK IDs, CVE numbers, academic papers, and tool documentation:

## Key References

- MITRE ATT&CK: T1190 - Exploit Public-Facing Application
- CVE-2023-22578
- https://github.com/sqlmapproject/sqlmap

Complete Skill Template

Below is a minimal skeleton you can copy-paste to start a new skill, as defined in the CONTRIBUTING.md standards:

---
name: offensive-example
description: "Brief description of the attack surface, techniques covered, and usage scenario."
---

# Example Offensive Skill

One-sentence framing that tells the operator why this technique matters.

## Quick Workflow

1. Enumerate the target.
2. Identify the vulnerable component.
3. Exploit the weakness.
4. Clean up and document findings.

---

## Detection / Defender View

*List of logs, alerts, or artifacts a defender might see.*

---

## Engagement Cheatsheet

```bash

# Quick command chain

tool --option target

---

Key References

• MITRE ATT&CK: T1190 – Exploit Public-Facing Application
• CVE-2024-12345 – Example vulnerability
• https://example.com/tool-doc

## Summary

- **File Path**: `Skills/<category>/<skill-folder>/SKILL.md` where the folder name matches the `name:` field
- **Front-Matter**: Required YAML block with `name` and `description` fields
- **Structure**: H1 title, framing paragraph, Quick Workflow, sectioned technical content, and Key References
- **Code Blocks**: Must use fenced blocks with language tags (e.g., `bash`, `sql`)
- **Manifest**: [`claude-skills.json`](https://github.com/SnailSploit/Claude-Red/blob/main/claude-skills.json) indexes all skills for the Claude system
- **Standards**: Defined in [`CONTRIBUTING.md`](https://github.com/SnailSploit/Claude-Red/blob/main/CONTRIBUTING.md) with real-world examples in [`Skills/web/offensive-sqli/SKILL.md`](https://github.com/SnailSploit/Claude-Red/blob/main/Skills/web/offensive-sqli/SKILL.md)

## Frequently Asked Questions

### What file extension does a Claude-Red skill use?

A Claude-Red skill uses the `.md` Markdown extension. The specific filename must be [`SKILL.md`](https://github.com/SnailSploit/Claude-Red/blob/main/SKILL.md) (case-sensitive) to be recognized by the skill indexing system.

### Is the Detection / Defender View section mandatory?

No, the `## Detection / Defender View` section is optional but highly recommended. Including defender visibility artifacts helps operators understand potential detection points and forensic artifacts generated by the techniques described.

### How does Claude locate available skills within the repository?

Claude uses the [`claude-skills.json`](https://github.com/SnailSploit/Claude-Red/blob/main/claude-skills.json) manifest file located in the repository root. This JSON file lists every skill’s name, category, and relative path, allowing the system to map natural language queries to the correct [`SKILL.md`](https://github.com/SnailSploit/Claude-Red/blob/main/SKILL.md) documents.

### Can I use indented code blocks instead of fenced code blocks?

No. The [`CONTRIBUTING.md`](https://github.com/SnailSploit/Claude-Red/blob/main/CONTRIBUTING.md) specifications require fenced code blocks using triple backticks (```) with explicit language identifiers. Indented code blocks do not provide the necessary language metadata for proper parsing and syntax highlighting.

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