Skip to content

28 of 78 SKILL.md files lack YAML frontmatter — npx skills add silently installs only 50 skills #28

Open
#29
Open
28 of 78 SKILL.md files lack YAML frontmatter — npx skills add silently installs only 50 skills#28
#29

Description

@KS-OTO
KS-OTO
opened on Sep 15, 2026

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 skills

28 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-Red installs 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:

  1. Add a CI check that walks Skills/**/SKILL.md, requires leading YAML frontmatter with non-empty name and description, and fails the build otherwise.
  2. Add a lint script asserting count(SKILL.md) == README badge number, so the advertised total can never drift from reality again.
  3. 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

  1. KS-OTO
    added a commit that references this issue on Sep 15, 2026

    chore: validate against the full Agent Skills spec, not just field pr…

    b585541

  2. KS-OTO commented on Sep 15, 2026

    @KS-OTO
    KS-OTO
    on Sep 15, 2026
    Author

    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:

    Metric Count
    SKILL.md files under Skills/ 78
    With valid name + description frontmatter 50
    Without any frontmatter 28

    The 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 / ## Description sections) instead of leading YAML frontmatter. Every spec-compliant installer requires name and description in frontmatter, so they are skipped.

    The repo's own generated manifest already agreed: claude-skills.json lists all 78 skills but with 28 empty descriptions — the same 28 files.

    One detail worth flagging for the tooling side: the CLI exits 0 when 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

    • Backfills name (skill directory name — the convention all 50 already-migrated skills use) and description (first paragraph of the existing ## Description) into the 28 files. 4 added lines each, document bodies untouched.
    • Adds tools/validate_skills.py (stdlib-only) and tools/backfill_frontmatter.py (idempotent migration).
    • Adds a validator assertion that the README skills-NN badge must equal the actual number of SKILL.md files, so the advertised count can never silently drift again.
    • Fixes a platform-drift bug in 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:

    discovery   before: Found 50 skills  + 28 warnings
            after:  Found 78 skills  +  0 warnings

install     skills add --skill '*' --agent claude-code --copy -y
            -> 78 skill directories, 78 entries in skills-lock.json

    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.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions