Repository navigation
28 of 78 SKILL.md files lack YAML frontmatter — npx skills add silently installs only 50 skills #28
Description
Summary
The README advertises 78 skills, but npx skills add SnailSploit/Claude-Red (the CLI at https://www.skills.sh/docs/cli) only discovers 50. The remaining 28 skills are silently unscannable by any spec-compliant skills installer, because their SKILL.md files have no YAML frontmatter.
Reproduction
$ bunx skills add SnailSploit/Claude-Red
◇ Repository cloned
⚠ Skipped .../skills\web\offensive-xss\SKILL.md — missing required frontmatter field(s): name, description
⚠ Skipped .../skills\infrastructure\offensive-edr-evasion\SKILL.md — missing required frontmatter field(s): name, description
...
◇ Found 50 skills28 warnings, then Found 50 skills — no more (see full output below).
Verification
I cloned the repo at HEAD and parsed every SKILL.md:
| Metric | Count |
|---|---|
SKILL.md files in Skills/ |
78 |
With valid name + description frontmatter |
50 |
| Without YAML frontmatter (skipped by CLI) | 28 |
The 50/28 split matches the CLI output exactly — the 28 warnings are precisely the 28 frontmatter-less files. This is a repo-side data defect, not a CLI bug.
Per-category breakdown:
| Category | Total | Installable | Skipped |
|---|---|---|---|
| web | 16 | 5 | 11 |
| wireless | 14 | 14 | 0 |
| infrastructure | 7 | 2 | 5 |
| exploit-dev | 6 | 1 | 5 |
| fuzzing | 4 | 1 | 3 |
| post-exploitation | 3 | 3 | 0 |
| api / auth / cicd / container / crypto / privesc / recon / social-engineering / supply-chain / utility | 2 each | — | ai, auth, recon, utility lose 1 each |
| active-directory / cloud / iot / mobile / network | 1 each | 1 | 0 |
| Total | 78 | 50 | 28 |
Root cause
Two incompatible metadata formats coexist in the repo.
Correct (50 files) — leading YAML frontmatter:
---
name: offensive-sqli
description: "SQL injection testing skill for offensive security assessments..."
---Broken (28 files) — a Markdown ## Metadata section instead, SKILL.md starts with a heading:
# SKILL: Cross-Site Scripting (XSS)
## Metadata
- **Skill Name**: xss
- **Folder**: offensive-xss
- **Source**: https://github.com/SnailSploit/offensive-checklist/blob/main/xss.md
## Description
Cross-Site Scripting testing checklist: stored/reflected/DOM/blind XSS discovery, ...The CLI (correctly, per the Agent Skills spec) requires name and description in frontmatter and skips files without them.
Affected files (all 28)
Each already contains the data needed to build the frontmatter — Skill Name and Description are present in the body. A mechanical fix is enough.
| File | existing Skill Name |
|---|---|
Skills/ai/offensive-ai-security/SKILL.md |
ai-security |
Skills/auth/offensive-oauth/SKILL.md |
oauth-attacks |
Skills/exploit-dev/offensive-basic-exploitation/SKILL.md |
basic-exploitation |
Skills/exploit-dev/offensive-crash-analysis/SKILL.md |
crash-analysis |
Skills/exploit-dev/offensive-exploit-dev-course/SKILL.md |
exploit-dev-curriculum |
Skills/exploit-dev/offensive-exploit-development/SKILL.md |
exploit-development |
Skills/exploit-dev/offensive-mitigations/SKILL.md |
security-mitigations |
Skills/fuzzing/offensive-bug-identification/SKILL.md |
bug-identification |
Skills/fuzzing/offensive-fuzzing-course/SKILL.md |
fuzzing-course |
Skills/fuzzing/offensive-vuln-classes/SKILL.md |
vulnerability-classes |
Skills/infrastructure/offensive-edr-evasion/SKILL.md |
edr-evasion |
Skills/infrastructure/offensive-initial-access/SKILL.md |
initial-access |
Skills/infrastructure/offensive-keylogger-arch/SKILL.md |
keylogger-architecture |
Skills/infrastructure/offensive-windows-boundaries/SKILL.md |
windows-boundaries |
Skills/infrastructure/offensive-windows-mitigations/SKILL.md |
windows-mitigations |
Skills/recon/offensive-osint-methodology/SKILL.md |
osint-methodology |
Skills/utility/offensive-fast-checking/SKILL.md |
fast-checking |
Skills/web/offensive-file-upload/SKILL.md |
file-upload |
Skills/web/offensive-idor/SKILL.md |
idor |
Skills/web/offensive-open-redirect/SKILL.md |
open-redirect |
Skills/web/offensive-parameter-pollution/SKILL.md |
parameter-pollution |
Skills/web/offensive-race-condition/SKILL.md |
race-condition |
Skills/web/offensive-rce/SKILL.md |
rce |
Skills/web/offensive-request-smuggling/SKILL.md |
request-smuggling |
Skills/web/offensive-ssrf/SKILL.md |
ssrf |
Skills/web/offensive-waf-bypass/SKILL.md |
waf-bypass |
Skills/web/offensive-xss/SKILL.md |
xss |
Skills/web/offensive-xxe/SKILL.md |
xxe |
Impact
npx skills add SnailSploit/Claude-Redinstalls a silently truncated pack — 36% of the library is missing, with no error, only warnings that scroll past.- The loss is concentrated in the highest-value categories: 11 of 16 web skills and 5 of 7 infrastructure skills never arrive. Users believe they have full red-team coverage; they do not.
- The README badge (
skills-78-red.svg) and the Skill Index link to all 78 files, so the docs contradict what an installer actually gets. Skills/exploit-dev/is worse than "partly broken": 5 of 6 skills fail, so the course/curriculum track is effectively absent.
Proposed fix
Primary (repo side) — add the missing frontmatter to all 28 files. Derive name from the directory name and description from the existing ## Description section, e.g.:
---
name: offensive-xss
description: Cross-Site Scripting testing checklist: stored/reflected/DOM/blind XSS discovery, polyglot payloads, CSP bypass, XSS filter bypass, event handler injection, DOM clobbering, mutation XSS, and impact escalation.
---Then enforce it so this cannot regress:
- Add a CI check that walks
Skills/**/SKILL.md, requires leading YAML frontmatter with non-emptynameanddescription, and fails the build otherwise. - Add a lint script asserting
count(SKILL.md) == README badge number, so the advertised total can never drift from reality again. - Consider carrying the skill count into the CI check as a single source of truth, and generate the README badge/table from it.
Secondary (tooling side) — the CLI could be more helpful. The current warning is easy to miss and doesn't summarize. If the installer reported something like Found 50 skills (28 skipped — missing frontmatter) and exited non-zero when files were skipped, this class of defect would surface immediately instead of at install time. Likewise, tolerating the legacy ## Metadata format or offering a --lenient migration path would have made importing this repo painless. This is a request, not a bug report against the CLI — the fix belongs in this repo first.
Related
Issue #8 ("Claude Skill Requirment") already identified the frontmatter requirement but did not quantify the gap or enumerate the affected files. This report supersedes it with the exact count (50/78), the full file list, and a regression guard.
Full CLI output
$ bunx skills add SnailSploit/Claude-Red
███████╗██╗ ██╗██╗██╗ ██╗ ███████╗
██╔════╝██║ ██╔╝██║██║ ██║ ██╔════╝
███████╗█████╔╝ ██║██║ ██║ ███████╗
╚██████║██╔═██╗ ██║██║ ██║ ╚██████║
███████║██║ ██╗██║███████╗███████╗███████║
╚══════╝╚═╝ ╚═╝╚═╝╚══════╝╚══════╝╚══════╝
┌ skills
│
◇ Source: https://github.com/SnailSploit/Claude-Red.git
│
◇ Repository cloned
│
⚠ Skipped C:\Users\insda\AppData\Local\Temp\skills-3mMaRn\skills\ai\offensive-ai-security\SKILL.md — missing required frontmatter field(s): name, description
⚠ Skipped C:\Users\insda\AppData\Local\Temp\skills-3mMaRn\skills\auth\offensive-oauth\SKILL.md — missing required frontmatter field(s): name, description
⚠ Skipped C:\Users\insda\AppData\Local\Temp\skills-3mMaRn\skills\exploit-dev\offensive-basic-exploitation\SKILL.md — missing required frontmatter field(s): name, description
⚠ Skipped C:\Users\insda\AppData\Local\Temp\skills-3mMaRn\skills\exploit-dev\offensive-crash-analysis\SKILL.md — missing required frontmatter field(s): name, description
⚠ Skipped C:\Users\insda\AppData\Local\Temp\skills-3mMaRn\skills\exploit-dev\offensive-exploit-dev-course\SKILL.md — missing required frontmatter field(s): name, description
⚠ Skipped C:\Users\insda\AppData\Local\Temp\skills-3mMaRn\skills\exploit-dev\offensive-exploit-development\SKILL.md — missing required frontmatter field(s): name, description
⚠ Skipped C:\Users\insda\AppData\Local\Temp\skills-3mMaRn\skills\exploit-dev\offensive-mitigations\SKILL.md — missing required frontmatter field(s): name, description
⚠ Skipped C:\Users\insda\AppData\Local\Temp\skills-3mMaRn\skills\fuzzing\offensive-bug-identification\SKILL.md — missing required frontmatter field(s): name, description
⚠ Skipped C:\Users\insda\AppData\Local\Temp\skills-3mMaRn\skills\fuzzing\offensive-fuzzing-course\SKILL.md — missing required frontmatter field(s): name, description
⚠ Skipped C:\Users\insda\AppData\Local\Temp\skills-3mMaRn\skills\fuzzing\offensive-vuln-classes\SKILL.md — missing required frontmatter field(s): name, description
⚠ Skipped C:\Users\insda\AppData\Local\Temp\skills-3mMaRn\skills\infrastructure\offensive-edr-evasion\SKILL.md — missing required frontmatter field(s): name, description
⚠ Skipped C:\Users\insda\AppData\Local\Temp\skills-3mMaRn\skills\infrastructure\offensive-initial-access\SKILL.md — missing required frontmatter field(s): name, description
⚠ Skipped C:\Users\insda\AppData\Local\Temp\skills-3mMaRn\skills\infrastructure\offensive-keylogger-arch\SKILL.md — missing required frontmatter field(s): name, description
⚠ Skipped C:\Users\insda\AppData\Local\Temp\skills-3mMaRn\skills\infrastructure\offensive-windows-boundaries\SKILL.md — missing required frontmatter field(s): name, description
⚠ Skipped C:\Users\insda\AppData\Local\Temp\skills-3mMaRn\skills\infrastructure\offensive-windows-mitigations\SKILL.md — missing required frontmatter field(s): name, description
⚠ Skipped C:\Users\insda\AppData\Local\Temp\skills-3mMaRn\skills\recon\offensive-osint-methodology\SKILL.md — missing required frontmatter field(s): name, description
⚠ Skipped C:\Users\insda\AppData\Local\Temp\skills-3mMaRn\skills\utility\offensive-fast-checking\SKILL.md — missing required frontmatter field(s): name, description
⚠ Skipped C:\Users\insda\AppData\Local\Temp\skills-3mMaRn\skills\web\offensive-file-upload\SKILL.md — missing required frontmatter field(s): name, description
⚠ Skipped C:\Users\insda\AppData\Local\Temp\skills-3mMaRn\skills\web\offensive-idor\SKILL.md — missing required frontmatter field(s): name, description
⚠ Skipped C:\Users\insda\AppData\Local\Temp\skills-3mMaRn\skills\web\offensive-open-redirect\SKILL.md — missing required frontmatter field(s): name, description
⚠ Skipped C:\Users\insda\AppData\Local\Temp\skills-3mMaRn\skills\web\offensive-parameter-pollution\SKILL.md — missing required frontmatter field(s): name, description
⚠ Skipped C:\Users\insda\AppData\Local\Temp\skills-3mMaRn\skills\web\offensive-race-condition\SKILL.md — missing required frontmatter field(s): name, description
⚠ Skipped C:\Users\insda\AppData\Local\Temp\skills-3mMaRn\skills\web\offensive-rce\SKILL.md — missing required frontmatter field(s): name, description
⚠ Skipped C:\Users\insda\AppData\Local\Temp\skills-3mMaRn\skills\web\offensive-request-smuggling\SKILL.md — missing required frontmatter field(s): name, description
⚠ Skipped C:\Users\insda\AppData\Local\Temp\skills-3mMaRn\skills\web\offensive-ssrf\SKILL.md — missing required frontmatter field(s): name, description
⚠ Skipped C:\Users\insda\AppData\Local\Temp\skills-3mMaRn\skills\web\offensive-waf-bypass\SKILL.md — missing required frontmatter field(s): name, description
⚠ Skipped C:\Users\insda\AppData\Local\Temp\skills-3mMaRn\skills\web\offensive-xss\SKILL.md — missing required frontmatter field(s): name, description
⚠ Skipped C:\Users\insda\AppData\Local\Temp\skills-3mMaRn\skills\web\offensive-xxe\SKILL.md — missing required frontmatter field(s): name, description
◇ Found 50 skills
◆ Select skills to install
│ Search:
│ ↑↓ move, space select, enter confirm
│
│ ❯ ● Select All (50/50)
│ ────────────────────────────────────
│ ● offensive-active-directory
│ ● offensive-advanced-redteam
│ ● offensive-anti-forensics
│ ● offensive-api-abuse
│ ● offensive-api-security
│ ● offensive-bluetooth-ble
│ ● offensive-bluetooth-classic
│ ● offensive-business-logic
│ ● offensive-c2-frameworks
│ ● offensive-cicd-pipeline
│ ● offensive-cicd-secrets
│ ● offensive-cloud
│ ● offensive-container-escape
│ ● offensive-crypto-attacks
│ ● offensive-data-exfiltration
│ ● offensive-deauth-disassoc
│ ● offensive-dependency-confusion
│ ● offensive-deserialization
│ ● offensive-evil-twin
│ ● offensive-fuzzing
│ ↓ 30 more
│
│ Description
│ Select or clear all 50 skills.
│
└
Activity
chore: validate against the full Agent Skills spec, not just field pr…
KS-OTO commentedon Sep 15, 2026
Status update — confirmed on a clean clone, fix opened
Reproduced your report from scratch (clone HEAD, parse every
Skills/**/SKILL.md) and the numbers line up exactly:SKILL.mdfiles underSkills/name+descriptionfrontmatterThe 28 files the installer skips match the 28 warning paths one-for-one, so the cause is unambiguous: those files still use the pre-conversion layout (a
# SKILL:heading plus## Metadata/## Descriptionsections) instead of leading YAML frontmatter. Every spec-compliant installer requiresnameanddescriptionin frontmatter, so they are skipped.The repo's own generated manifest already agreed:
claude-skills.jsonlists all 78 skills but with 28 empty descriptions — the same 28 files.One detail worth flagging for the tooling side: the CLI exits
0when it skips files. The 28 losses produce only warnings that scroll past and a successful exit code, which is why this stayed invisible. A skipped-file count in the summary, or a non-zero exit, would have surfaced it immediately.Fix — PR #29
#29
name(skill directory name — the convention all 50 already-migrated skills use) anddescription(first paragraph of the existing## Description) into the 28 files. 4 added lines each, document bodies untouched.tools/validate_skills.py(stdlib-only) andtools/backfill_frontmatter.py(idempotent migration).READMEskills-NNbadge must equal the actual number ofSKILL.mdfiles, so the advertised count can never silently drift again.tools/build_manifest.py: it wrote backslash paths on Windows and forward slashes on Linux into a committed file.Verified end to end with
skills@1.5.26:Also: all 78 frontmatter blocks parse under a strict YAML parser with 78 unique slugs; backfill is idempotent; the manifest build is byte-identical across runs.
Separate follow-up: 18 descriptions exceed the 1024-character spec limit (longest 1522). They predate this fix and are unaffected by it — filing separately rather than bundling, since it needs its own decision.