# One SKILL.md, every AI agent: I packaged my open-source security scanner as a portable skill > Source: > Published: 2026-11-11 02:11:37+00:00 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](https://github.com/gevarru/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... --- # ASX Security Scan [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](https://github.com/gevarru/AttackSurfaceX) — MIT, Python 3.11+.