SkillMD

Lint, search, and install Agent Skills — a CLI, an MCP server, and the SKILL.md engine behind skillmd.com.

---

Agent Skills are Markdown files (SKILL.md) that teach AI agents new workflows. SkillMD is the registry that lints: every skill is validated, security-scanned, and content-pinned — and this repo is the toolchain that does it, the same engine on your machine and on the registry.

Package	What it is
skillmds	One npm package, two binaries: the skillmd CLI and the skillmds MCP server
@skillmd/core	The SKILL.md engine: parser, lint rules, security scanner, quality score, SARIF/JSON/GitHub formatters
skillmds/skillmd/action	GitHub Action: lint skills in CI, results in GitHub Code Scanning

The CLI

npm i -g skillmds

skillmd lint .                 # validate SKILL.md files — diagnostics + quality score
skillmd scan .                 # what would this skill do? scripts, network, secrets
skillmd search "pdf tools"     # search the registry
skillmd add anthropic/pdf      # install — lints first, never executes scripts
skillmd init my-skill          # scaffold a new skill
skillmd publish ./my-skill     # publish to skillmd.com (blocked on lint errors)

skillmd add targets 68 agents automatically — Claude Code, Cursor, Codex, Windsurf, Gemini CLI, GitHub Copilot, Cline, Goose, Zed, and more — writing each skill to every agent detected on your machine, in that agent's own directory convention. Just skillmd opens a guided interactive menu.

Full reference: docs/cli.md

The MCP server

Give any MCP-capable agent the whole registry — search, inspect, lint, and install skills mid-conversation:

# Claude Code
claude mcp add skillmd -- npx -y skillmds

// Claude Desktop, Cursor, VS Code, … (examples/mcp/ has per-client files)
{ "mcpServers": { "skillmd": { "command": "npx", "args": ["-y", "skillmds"] } } }

Or use the hosted remote server — zero install, streamable HTTP:

https://api.skillmd.com/mcp

Tool	What the agent gets
skillmd_search	Registry search with categories, ratings, and install snippets
skillmd_get	Full skill detail: body, provenance, license, security flags
skillmd_install	Safe install: validated, SHA-256-verified, zip-slip-guarded, never executes scripts
skillmd_trending / skillmd_recommend	Leaderboard + similar-skill suggestions
skillmd_list_saved	Your saved skills (with SKILLMD_TOKEN)
skillmd_lint	Validate any SKILL.md content on the spot

Full reference: docs/mcp.md · registry entry: com.skillmd/skillmd

The engine

npm i @skillmd/core

import { lint } from "@skillmd/core";

const { ok, score, diagnostics, security } = lint(rawSkillMd, { slug: "my-skill" });

Nine lint rules, a line-aware security scanner (network_calls, executes_scripts, reads_secrets, …), a 0–100 quality score, and SARIF/JSON/GitHub-annotation formatters. ESM, typed, no runtime dependency beyond yaml, runs in Node/browsers/edge. Rules: docs/rules.md

CI for your skills

- uses: skillmds/skillmd/action@v1
  with:
    path: .

Lints every skill in the repo and uploads SARIF to GitHub Code Scanning — findings show up right in PRs. Full example: examples/github-action.yml

The registry API

Everything here is a thin client over the public API at api.skillmd.com — usable directly (GET /v1/search?q=…), described by docs/registry-api.md, https://skillmd.com/openapi.json, and https://skillmd.com/llms.txt.

Security model

Installing a skill writes files and does nothing else: no script execution, strict path containment (slug validation + zip-slip guards), SHA-256 integrity verification against the registry's content-addressed store, and companion downloads pinned to GitHub raw hosts. Details in SECURITY.md — vulnerability reports to hi@skillmd.com.

Development

npm ci
npm run build      # @skillmd/core, then skillmds
npm test           # vitest across both packages (19 test files, incl. an MCP stdio smoke test)
npm run typecheck  # strict tsc

See CONTRIBUTING.md for layout, PR guidelines, and the release process.

License

MIT © SkillMD