/authoring-security-skills

name: authoring-security-skills
description: Write a new SecSkills skill end to end — choosing the plugin bucket and skill tier, writing a description that triggers correctly without stealing traffic from siblings, the required sections, registering the skill in ttp-index.json, adding routing eval cases including negative traps, and running the three validators. Use when adding a skill to this repo, splitting or merging existing skills, fixing a skill that triggers on the wrong requests, or when a new skill fails validate.py, sync_attack.py, or run_evals.py.

Authoring Security Skills

A skill earns its context budget by carrying what the model would otherwise get wrong. The model already knows what `nmap -sV` does. It does not reliably hold the *discipline* — trace to demonstrated impact before reporting, preserve before remediating, refuse to ship a rule never tested against production noise.

That judgment is the deliverable. Commands are scaffolding around it.

When to Use

• Adding a new skill to `secskills-offense`, `-defense`, or `-core`
• Splitting an overloaded skill or merging two that overlap
• Fixing a skill that loads for the wrong requests, or fails to load for the

right ones

• Resolving a failure from `validate.py`, `sync_attack.py`, or `run_evals.py`

When NOT to Use

• Fact-checking content you have written — that is `verifying-skill-accuracy`,

and it is a separate gate that runs after this one

• Editing prose in an existing, settled skill
• Repo-level work (manifests, marketplace, CI) that is not about a skill

Step 1: Pick the Plugin

A skill lives in exactly one plugin. The split exists so a blue-team user is not carrying exploitation content and vice versa.

| Plugin | Takes | Test | | --- | --- | --- | | `secskills-offense` | Exploitation, attacker tradecraft, and testing that acts against a target | Would this run against someone's system during an engagement? | | `secskills-defense` | DFIR, hunting, detection, intel, incident response | Does this read artifacts after the fact, or build detection? | | `secskills-core` | Dual-use: reverse engineering, code/crypto/supply-chain review, AI security, ATT&CK mapping, reporting | Is it equally at home on both sides? |

When it fits two, choose `core` rather than duplicating. Cross-plugin references are expected and degrade to inert text for readers who installed only one plugin — that is by design, so never duplicate a skill to avoid a cross-reference.

Step 2: Pick the Tier

**Domain skills** carry methodology for a whole area and trigger on broad, plain-language requests. Keep them few and non-overlapping.

**Procedure skills** cover one target-and-toolchain combination that is rare, exact, and unrecoverable from general knowledge — `reversing-flutter-apps` with blutter, for instance. They are *supposed* to be narrow.

Two rules keep the tiers working:

1. **Every procedure skill is reachable from its domain skill.** Add the identifying check and a routing line to the domain skill. An unreachable procedure skill is dead weight. 2. **A procedure skill hands back.** Recovering symbols is not the assessment — name the skill that continues the work.

Unsure? Ask whether it applies to most engagements in its area (domain) or only when a specific artifact is in hand (procedure).

Step 3: Write the Description

**This is the highest-leverage text in the skill.** It is how Claude decides whether to load it, and it competes with all 71 siblings. A perfect skill body behind a vague description never runs.

Rules the validator enforces: third person, 60–1024 characters, and a trigger clause. Rules it cannot enforce but reviewers will:

• Lead with what the skill *does*, then `Use when ...` naming concrete

situations.

• Build triggers from **what the user actually has in hand** — file names,

magic bytes, framework and tool names, error strings, the identifying symptom. Not abstractions.

• Name the evidence that distinguishes this skill from its nearest sibling.

# Good — names artifacts, tools, and the symptom
description: Reverse engineer and intercept traffic from Flutter/Dart mobile
  apps using blutter, reFlutter, and Frida. Use when an APK or IPA contains
  libflutter.so, libapp.so, App.framework, or flutter_assets, when jadx shows
  only a thin Dart wrapper, or when Burp sees no traffic from an app that is
  clearly online.

# Bad — overlaps the domain skill and triggers on the wrong requests
description: Advanced mobile reverse engineering techniques for modern apps.

Step 4: Write the Body

Required sections:

• **`## When to Use`** — concrete situations, not categories.
• **`## When NOT to Use`** — where a different skill is correct, **with the

sibling named in backticks**. This is what stops skills fighting over the same words.

Expected in security skills:

• **`## Rationalizations to Reject`** — the plausible-sounding shortcuts that

cause missed findings, each with why it is wrong. This is the highest-value section in the collection; it encodes judgment a command list cannot.

Offensive skills additionally need **scope and authorization framing** written to that domain's real exposure — not boilerplate. Recon has third-party estate and OSINT-as-personal-data; password cracking has account lockout as an availability risk; RF work has wiretap and spectrum law because you cannot confine a radio to the target. Generic "get permission first" text is worth nothing.

**If the skill's workflow reads public reference material** — advisories, specs, RFCs, vendor reports, ATT&CK pages — include the standard `## Reading External Sources` block before `## References`. Copy it verbatim from a skill that has it (`producing-threat-intelligence`, `auditing-supply-chain`); it must stay identical across skills so it does not drift. It routes public documentation through `defuddle.md` for a large token saving and full greppable text.

Do **not** add that block to a skill wh