AI agents are turning into the most impatient users your tools will ever have. They don't read READMEs top to bottom, they don't hunt for flags, and they will guess wrong unless you tell them exactly what to do. The industry's answer in 2026 is the skill: a single SKILL.md file — YAML frontmatter plus instructions — that any compatible agent can load.
I maintain AttackSurfaceX, an open-source (MIT), deliberately non-destructive attack surface scanner. Packaging it as a skill took one file and a few careful decisions. Here's the whole thing, and why each part exists.
---
name: asx-security-scan
description: "Run AttackSurfaceX (ASX), a safe non-destructive attack surface"
scanner, against authorized targets. Use when the user asks to scan or audit
a domain they own or are permitted to test...
---
[what the tool is, what it can NEVER do]
## When to use / Do NOT use
- owns-or-authorized targets only; no permission = no scan
- no exploitation, no fuzzing, no raising scan rates
## Setup / Usage / Interpreting results
- pipx install; always start with -p safe
- LOW = hardening gaps (give the exact header to add)
- if every port is "closed" and TLS always fails, say "geo-filtered", don't report TLS weakness
## Safety rules (never skip)
That's it. One file. But four decisions in it are the actual point of this post.
An agent holding a scanner is one vague prompt away from scanning something it shouldn't. So the skill opens with a gate — owns or written authorization — and a hard "Do NOT use" list. Instructions beat intentions: agents follow structure, and the structure here says permission precedes execution.
AttackSurfaceX is built so it physically cannot send state-changing requests. The skill repeats that doctrine in words, because an agent that understands why won't try to route around it. If your tool has a philosophy, write it into the skill — that's the difference between a wrapper and a capable operator.
A raw scanner dump scares users. The skill maps severities to plain language: LOW usually means hardening gaps with the exact header to add; INFO is context. It also carries two hard-won lessons from real runs:
Real-world runs showed the same finding arriving from a built-in module and a plugin, so the scanner now merges duplicates (Jaccard-similar titles, same CWE, same target). The skill tells the agent to read duplicates_suppressed so it never double-reports an issue.
The same file works across the current generation of agents — local coding agents and cloud/desktop agents alike — and the open skill hubs (skillsmp, skillsllm, lobehub) distribute exactly this format. In an agent that supports skills, you invoke it with a slash command, or the agent loads it automatically when the task matches its description.
pipx install git+https://github.com/gevarru/AttackSurfaceX.git
The skill lives at skills/asx-security-scan/SKILL.md in the repo. Fork it, adapt the gates to your own tools, and publish yours — the best agent tooling this year is going to be small, honest markdown files like this one.
⭐ github.com/gevarru/AttackSurfaceX — MIT, Python 3.11+.