{"slug": "one-skill-md-every-ai-agent-i-packaged-my-open-source-security-scanner-as-a", "title": "One SKILL.md, every AI agent: I packaged my open-source security scanner as a portable skill", "summary": "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.", "body_md": "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.\n\nI 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.\n\n```\n---\nname: asx-security-scan\ndescription: \"Run AttackSurfaceX (ASX), a safe non-destructive attack surface\"\n  scanner, against authorized targets. Use when the user asks to scan or audit\n  a domain they own or are permitted to test...\n---\n\n# ASX Security Scan\n[what the tool is, what it can NEVER do]\n\n## When to use / Do NOT use\n- owns-or-authorized targets only; no permission = no scan\n- no exploitation, no fuzzing, no raising scan rates\n\n## Setup / Usage / Interpreting results\n- pipx install; always start with -p safe\n- LOW = hardening gaps (give the exact header to add)\n- if every port is \"closed\" and TLS always fails, say \"geo-filtered\", don't report TLS weakness\n\n## Safety rules (never skip)\n```\n\nThat's it. One file. But four decisions in it are the actual point of this post.\n\nAn 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*.\n\nAttackSurfaceX 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.\n\nA 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:\n\nReal-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.\n\nThe 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.\n\n```\npipx install git+https://github.com/gevarru/AttackSurfaceX.git\n```\n\nThe 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.\n\n⭐ [github.com/gevarru/AttackSurfaceX](https://github.com/gevarru/AttackSurfaceX) — MIT, Python 3.11+.", "url": "https://wpnews.pro/news/one-skill-md-every-ai-agent-i-packaged-my-open-source-security-scanner-as-a", "canonical_source": "https://dev.to/gevarru/one-skillmd-every-ai-agent-i-packaged-my-open-source-security-scanner-as-a-portable-skill-1e8i", "published_at": "2026-11-11 02:11:37+00:00", "updated_at": "2026-11-11 02:22:27.545969+00:00", "lang": "en", "topics": ["ai-agents", "ai-tools", "agent-protocols", "developer-tools", "ai-safety"], "entities": ["AttackSurfaceX", "skillsmp", "skillsllm", "lobehub", "GitHub"], "also_reported_by": [], "alternates": {"html": "https://wpnews.pro/news/one-skill-md-every-ai-agent-i-packaged-my-open-source-security-scanner-as-a", "markdown": "https://wpnews.pro/news/one-skill-md-every-ai-agent-i-packaged-my-open-source-security-scanner-as-a.md", "text": "https://wpnews.pro/news/one-skill-md-every-ai-agent-i-packaged-my-open-source-security-scanner-as-a.txt", "jsonld": "https://wpnews.pro/news/one-skill-md-every-ai-agent-i-packaged-my-open-source-security-scanner-as-a.jsonld"}}