One SKILL.md, every AI agent: I packaged my open-source security scanner as a portable skill

The maintainer of AttackSurfaceX, an MIT-licensed non-destructive attack surface scanner, packaged the tool as a portable agent skill in a single SKILL.md file containing YAML frontmatter and instructions. The skill gates scanning behind an ownership-or-authorization check, restates the scanner's non-destructive design, maps severities to plain-language guidance, and instructs agents to read the scanner's duplicates_suppressed field to avoid double-reporting findings. The format is distributed through open skill hubs such as skillsmp, skillsllm and lobehub and works across local and cloud agents.

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+.