Authoring Security Skills

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.

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 whose network activity is aimed at a target. Cloud metadata endpoints, the target's own services, exfil hosts, phishing URLs, and C2 must be fetched directly — routing them through a third-party extractor breaks the command, leaks engagement URLs, and for live adversary infrastructure tips off the operator.

Order steps by when they happen, and say so. A skill body that reads as an unordered pile of techniques gets sampled, not followed. Mark the first actions as immediate, the ones that depend on their output as following, and the ones that touch the target as acting — then a reader who loads the skill mid-task knows where they are. The ordering also carries the safety property: anything in the acting group is gated on authorization being granted, which is only legible if the groups are distinguishable.

A skill is a set of instructions to carry out, not a document to acknowledge. Loading one and replying that it has been read and understood is a failure mode worth naming in the body when the first step is easy to skip — a skill whose opening move is "record scope before touching anything" is exactly the skill a hurried reader will summarise instead of doing.

Write for judgment, not recall:

Keep SKILL.md under 600 lines; move payload lists and long tables into a references/ directory, which loads only when pointed at. Do not chain them: SKILL.md may point at a reference file, but that file must not send the reader on to a third one.

Note that the validator resolves every backtick-quoted reference path as a real file — so an illustrative path in prose will fail the build. Name real files only.