Try It

The parser validates SKILL.md structure against the Agent Skills spec:

Check	Rule
Frontmatter	Must exist as YAML between --- delimiters
name	Required. 1-64 chars, lowercase alphanumeric + hyphens. No leading/trailing hyphens, no consecutive hyphens (--)
description	Required. Max 1,024 characters
Body	Required. Markdown content after frontmatter
File references	Paths starting with scripts/, references/, assets/ must resolve to existing files

Rule	Severity	What it catches
no-secrets	error	11 patterns: sk-* (OpenAI), sk_live_* / sk_test_* (Stripe), ghp_* / gho_* / github_pat_* (GitHub), xoxb-* / xoxp-* (Slack), AKIA* (AWS), -----BEGIN PRIVATE KEY-----, JWT patterns
no-hardcoded-paths	error	/Users/..., /home/..., C:\Users\..., /var/, /tmp/...
description-specificity	warning	Generic verbs in description: manage, handle, process, deal with, work with, do stuff, help with, assist with, take care of
description-length-optimal	info	Description outside 50–300 char sweet spot. Too short wastes routing accuracy; too long wastes metadata tier budget
description-trigger-keywords	warning	Needs a trigger phrase (use when, use for, invoke when, trigger when) OR an action verb (deploy, test, build, run, create, generate, analyze, review, format, lint, fix, check, commit, push, pull, fetch, install, configure, setup, search, find, list, delete, update, migrate, convert, export, import)
progressive-disclosure	warning	>500 lines without references/ or scripts/ file references
instructions-has-examples	info	No code blocks (```), inline code (`..`), or numbered steps (1. ...)
instructions-has-error-handling	info	No error handling heading or keywords (error, fail, troubleshoot, "if X fails", "common issues")
consistent-headings	info	Heading levels that skip (e.g. H1 directly to H4)

Scores are computed by deterministic code. No LLMs involved.

Description Quality 30 pts

• Length 50-300 chars = 8 pts · 30-400 = 5 pts · ≥10 = 2 pts
• Action verbs: ≥2 = 8 pts · ≥1 = 5 pts
• Trigger phrase ("use when" / "use for" / "invoke when" / "when the user") = 8 pts
• Name uniqueness: <50% name parts in description = 6 pts · <80% = 3 pts

Instruction Clarity 25 pts

• Code blocks: ≥2 = 7 pts · ≥1 = 4 pts
• Numbered steps: ≥3 = 6 pts · ≥1 = 3 pts
• Error handling heading = 6 pts · keywords only = 3 pts
• Body word count: ≥100 = 6 pts · ≥50 = 4 pts · ≥20 = 2 pts

Spec Compliance 20 pts

• Has name = 5 pts
• Has description = 5 pts
• ≤5,000 tokens = 5 pts · ≤7,500 = 2 pts
• ≤500 lines = 5 pts · ≤750 = 2 pts

Progressive Disclosure 15 pts

• ≤100 lines = 15 pts (auto-pass)
• 100-500 lines with refs = 15 pts · without = 8 pts
• >500 lines with refs = 10 pts · without = 2 pts

Security 10 pts

• Starts at 10. Any secret pattern = 0 (immediate).
• Hardcoded paths = −3 · rm -rf / = −2 · curl | bash = −2 · eval $ = −2
• Floor: 0

Okapi BM25 full-text search. No LLMs, no embeddings, no API calls.

Parameters

Param	Default	Role
k1	1.2	Term frequency saturation. Higher = more weight to repeated terms.
b	0.75	Length normalization. 0 = ignore length, 1 = fully normalize.

Formulas

IDF(t) = log((N - df(t) + 0.5) / (df(t) + 0.5) + 1)

score(q, d) = Σ IDF(t) × (tf(t,d) × (k1 + 1)) / (tf(t,d) + k1 × (1 - b + b × |d| / avgdl))

normalized = score / max_score   # top result = 1.0

Contextual Enrichment v0.2.2

Context terms are extracted deterministically from the skill body and prepended to the description before indexing:

• Name parts — skill name split on - and _
• Section headings — all markdown headings
• Inline code refs — backtick-wrapped terms from body

Max 80 context tokens. Deduped against description to avoid inflating term frequency. Disable with context: false.

Generates a spec-compliant SKILL.md from an MCP tools/list JSON response. Same algorithm as @skill-tools/gen.

Input

Paste the JSON from an MCP server's tools/list response. Accepts {"tools": [...]} or a bare [...] array.

Pipeline

• Parse — Extract tool name, description, inputSchema, and annotations from each tool entry
• Cluster — Tokenize tool names (snake_case, camelCase, kebab-case, MCP __ namespaces), strip 42 known verb prefixes, group by remaining domain tokens
• Merge singletons — Tools with unique domain tokens are merged into larger groups sharing a prefix, or collected into "Other"
• Render SKILL.md — Frontmatter, quick start (top 5 tools), grouped tool tables, CRUD workflows, error handling
• Render references/TOOLS.md — Per-tool parameter tables with types, required flags, enum values, and defaults