SkillMD

https://skillmd.com/docs
Admin
SkillMD is an open registry and CLI for AI Agent Skills, enabling users to discover, validate, and...
Tokens:16,077
Snippets:154
Trust Score:6.2
Update:1 month ago
Show doc for...
Tokens:
Raw
### Install skills from various sources

Source: https://skillmd.com/docs/cli

Installs skills using registry slugs, GitHub repositories, or local paths. Includes options for targeting specific agents, installing from packs, listing contents, and configuring installation modes.

```bash
skillmd add anthropic/pdf
skillmd add anthropic/pdf -a claude-code cursor -g
skillmd add anthropic/pdf-pack -s changelog release-notes
skillmd add owner/repo/skills/pdf#main -p
skillmd add owner/repo --list
skillmd add ./local-skill --skip-lint
skillmd add owner/repo --deny executes_scripts
```

--------------------------------

### SKILL.md frontmatter and instructions example

Source: https://skillmd.com/docs/what-is-an-agent-skill

Example SKILL.md file with YAML frontmatter (name, description, license) and Markdown instructions. The agent uses the description to decide when to load the skill.

```markdown
---
name: dockerfile-optimizer
description: Reviews and optimizes Dockerfiles for smaller, faster builds. Use when the user asks to improve a Dockerfile.
license: MIT
---

# Dockerfile optimizer

When asked to optimize a Dockerfile:
1. Pin the base image and prefer slim variants.
2. Order layers from least to most frequently changed.
3. ...
```

--------------------------------

### skillmd list usage examples

Source: https://skillmd.com/docs/cli

Shows basic usage of the list command, filtering by project and agent, and outputting JSON for global skills. The list command lists installed skills across both scopes by default.

```bash
skillmd list
skillmd list -p -a claude-code
skillmd list -g --json
```

--------------------------------

### Fuller example of skill metadata

Source: https://skillmd.com/docs/format

A comprehensive example of a skill metadata file including frontmatter and a structured body with overview, steps, and error handling sections.

```markdown
---
name: pdf-table-extract
description: "Extracts tabular data from PDF documents and returns it as clean CSV or JSON, handling multi-page tables and merged cells."
license: MIT
---

## Overview

This skill extracts tables from PDF files, including tables that span
multiple pages or contain merged header cells. Use it whenever a task
asks for structured data pulled out of a PDF report, invoice, or form.

## Steps

First, identify every page that contains a table. Then extract each
table's rows and columns, preserving column order and header labels.
Merge tables that continue across a page break into a single result.
Normalize whitespace and currency formatting before returning output.

## Error handling

If a page is scanned as an image with no extractable text layer, say so
explicitly instead of returning empty or guessed data. If a table's
structure is ambiguous, such as cells that visually merge but have no
clear delimiter, flag the ambiguity in the output rather than silently
picking one interpretation.
```

--------------------------------

### skillmd_install

Source: https://skillmd.com/docs/mcp

Install a skill on local disk. It runs the same installer the CLI does: lint and validation first, so a broken skill never lands on disk silently, then one canonical copy at `.agents/skills/<name>` with a link to it from each chosen agent's skills directory. It never executes scripts, and the slug is validated to block path traversal.

```APIDOC
## skillmd_install

### Description
Install a skill on local disk. It runs the same installer the CLI does: lint and validation first, so a broken skill never lands on disk silently, then one canonical copy at `.agents/skills/<name>` with a link to it from each chosen agent's skills directory. It never executes scripts, and the slug is validated to block path traversal.

### Parameters
- **slug** (string) - Required - Format `<owner>/<name>`.
- **scope** (string) - Optional - `project` writes into the working directory's agent folders; `global` writes into the user's home-level ones. Defaults to `project` when the working directory looks like a project, otherwise `global`.
- **agents** (array) - Optional - Agent ids to link the skill into. Defaults to every agent detected on the machine.
- **mode** (string) - Optional - `link` (default) or `copy`.
- **force** (boolean) - Optional - Replace a skill installed from a different source, or a directory that isn't tracked.
- **deny** (array) - Optional - Refuse the install if the skill carries any of these security flags.
- **dest** (string) - Optional - **Deprecated.** An explicit skills directory, accepted only when it is a known agent's skills directory. Use `scope` and `agents` instead.

### Response
The response reports the skill's capability flags (`docs_only`, `network_calls`, `executes_scripts`, `reads_secrets`) as information. They don't block the install.

### Notes
This tool writes to whatever machine is running the server. If your MCP client connects to a remote or hosted server, the files land on that server's disk, not on your laptop. Check where the install resolves before relying on the output.
```

--------------------------------

### Install CLI and add a skill

Source: https://skillmd.com/docs

Install the skillmd CLI globally via npm, then search for a verified skill and add it to your agent. Without the -a flag, the CLI installs to detected agent directories, defaulting to Claude Code.

```bash
# install the CLI
npm i -g skillmds@latest

# find a skill, then add it to your agent
skillmd search "pdf extraction" --verified
skillmd add anthropic/docx -a claude-code
```

--------------------------------

### skillmd_lint example call using slug

Source: https://skillmd.com/docs/mcp

Example JSON payload for the skillmd_lint tool when passing a slug to fetch the skill from the registry before linting. The slug format is <owner>/<name>.

```json
{
  "slug": "anthropic/pdf"
}
```

--------------------------------

### Run the MCP server with no arguments (npx -y skillmds)

Source: https://skillmd.com/docs/mcp

Start the `skillmds` MCP server. The command takes no arguments; any argument routes to the `skillmd` CLI instead.

```bash
npx -y skillmds
```

--------------------------------

### Install SkillMD CLI globally

Source: https://skillmd.com/docs/getting-started

Install the skillmd CLI globally using npm. Requires Node 18 or later.

```bash
npm i -g skillmds
```

--------------------------------

### Add skill to specific agents or user-level directory

Source: https://skillmd.com/docs/getting-started

Target specific agents with -a or install to the user-level skills directory with -g. -a takes one or more agent names.

```bash
skillmd add anthropic/pdf -a claude-code cursor
skillmd add anthropic/pdf -g
```

--------------------------------

### Get skill registry details

Source: https://skillmd.com/docs/cli

Displays registry details for a specific skill using its slug. Supports an optional --json flag for machine-readable output.

```bash
skillmd info anthropic/pdf
skillmd info anthropic/pdf --json
```

--------------------------------

### skillmd CLI global options usage examples

Source: https://skillmd.com/docs/cli

Shows two commands using global options: one with --json for machine-readable output and one with --token and --api to override the stored token and API base URL. The token is resolved from --token, then SKILLMD_TOKEN, then ~/.skillmd/config.json. The API base is resolved from --api, then SKILLMD_API, then stored config, then https://api.skillmd.com. Using --token on the command line is discouraged because it appears in shell history and process listings.

```bash
skillmd lint . --json
skillmd add anthropic/pdf --token sk_live_xxxxx --api https://staging.skillmd.com
```

--------------------------------

### skillmd_search

Source: https://skillmd.com/docs/mcp

Search the registry by name, description, or task. This is the entry point for most agent workflows: describe what you need, get back candidates.

```APIDOC
## skillmd_search

### Description
Search the registry by name, description, or task. This is the entry point for most agent workflows: describe what you need, get back candidates.

### Parameters
- **query** (string) - Required - Free-text search term.
- **category** (string) - Optional - Restrict results to one category.
- **verified_only** (boolean) - Optional - Only return skills that passed safety review.
- **type** (string) - Optional - `single` or `pack`.
- **min_rating** (number) - Optional - Floor on average rating.
- **limit** (number) - Optional - Default 20.
```

--------------------------------

### skillmd lint command usage examples

Source: https://skillmd.com/docs/cli

Shows three lint invocations: basic linting of a target path, SARIF output for CI annotations, and strict mode with fail-on-warning. The --format flag accepts text, json, sarif, or github, defaulting to text. Use --format sarif or --format github to feed results into CI annotations.

```bash
skillmd lint ./my-skill
skillmd lint ./my-skill --format sarif
skillmd lint . --strict --fail-on-warning
```

--------------------------------

### skillmd update usage examples

Source: https://skillmd.com/docs/cli

Shows updating all tracked skills, updating a specific global skill, and checking for updates without writing. Untracked skills are skipped; exit code is 0 when all handled and 1 if any failed.

```bash
skillmd update
skillmd update anthropic-pdf -g
skillmd update --check --json
```

--------------------------------

### skillmd check: report available updates

Source: https://skillmd.com/docs/cli

Use to list installed skills that have updates available without modifying anything. Accepts optional skill names and supports flags -g, -p, and --json, same as the update command.

```bash
skillmd check
skillmd check -p --json
```

--------------------------------

### skillmd_lint

Source: https://skillmd.com/docs/mcp

Validate a SKILL.md and get back a score, diagnostics, and any security flags. Pass either raw content or a slug to fetch from the registry first.

```APIDOC
## skillmd_lint

### Description
Validate a SKILL.md and get back a score, diagnostics, and any security flags. Pass either raw content or a slug to fetch from the registry first.

### Parameters
- **content** (string) - One of content/slug - Raw SKILL.md text.
- **slug** (string) - One of content/slug - Fetches the file from the registry before linting.

### Example Call Using `slug`
```
{
  "slug": "anthropic/pdf"
}
```
```

--------------------------------

### skillmd remove usage examples

Source: https://skillmd.com/docs/cli

Shows removal of skills with optional names, agent-specific unlinking, global scope, and removing all project skills with confirmation skipped. Without -y it confirms first and exits 1 when nothing matched.

```bash
skillmd remove
skillmd remove my-skill
skillmd remove my-skill -a cursor
skillmd rm my-skill other-skill -g
skillmd rm --all -p -y
```

--------------------------------

### Initialize a new SKILL.md

Source: https://skillmd.com/docs/cli

Scaffolds a new SKILL.md file from a template. Use the --yes flag to skip interactive prompts.

```bash
skillmd init my-skill --description "Helps with X" --yes
skillmd init --name my-skill --license Apache-2.0
```

--------------------------------

### init

Source: https://skillmd.com/docs/cli

Scaffolds a new SKILL.md from a template. Supports flags for name, description, license, and skipping prompts.

```APIDOC
## init

### Description
Scaffolds a new SKILL.md from a template.

### Method
CLI command

### Endpoint
`skillmd init [name]`

### Parameters
#### Arguments
- **name** (string) - Optional - Skill name.

#### Flags
- **--name** (string) - Optional - Skill name, if not passed as argument.
- **--description** (string) - Optional - Description written into the frontmatter.
- **--license** (string) - Optional - License identifier. Default `MIT`.
- **-y, --yes** (boolean) - Optional - Skip prompts and use the values passed as flags.

### Request Example

skillmd init my-skill --description "Helps with X" --yes
skillmd init --name my-skill --license Apache-2.0


### Response
#### Success Response
Writes a new SKILL.md file to `<dir>/<slug>/SKILL.md`, where `<slug>` is derived from the name.

#### Response Example
(No explicit response example provided in source.)
```

--------------------------------

### Create a SKILL.md file

Source: https://skillmd.com/docs/getting-started

A skill is a single SKILL.md file with YAML frontmatter and markdown instructions underneath.

```markdown
---
name: my-skill
description: What this skill does and when to use it.
license: MIT
---

Instructions the agent reads when it loads this skill.
```

--------------------------------

### Scaffold, validate, and publish a skill

Source: https://skillmd.com/docs/getting-started

Four commands to scaffold, lint, login, and publish a skill. Lint checks the file against the SKILL.md format and prints a quality score.

```bash
skillmd init my-skill
skillmd lint
skillmd login
skillmd publish
```

--------------------------------

### Generic MCP client config with mcpServers

Source: https://skillmd.com/docs/mcp

Add an entry under `mcpServers` in a JSON config file for MCP clients that read JSON config. The command and args launch the server via npx.

```json
{
  "mcpServers": {
    "skillmds": {
      "command": "npx",
      "args": ["-y", "skillmds"]
    }
  }
}
```

--------------------------------

### List or inspect lint rules

Source: https://skillmd.com/docs/cli

Lists all available lint rules or provides details for a specific rule ID. Use the --json flag for machine-readable output.

```bash
skillmd rules
skillmd rules SK010 --json
```

--------------------------------

### Search and add a skill

Source: https://skillmd.com/docs/getting-started

Search the registry for skills and add one. The --verified flag restricts results to skills that passed safety review.

```bash
npm i -g skillmds@latest
skillmd search "pdf extraction" --verified
skillmd add anthropic/pdf
```

--------------------------------

### Run SkillMD CLI commands

Source: https://skillmd.com/docs/format

Use the CLI to lint directories or inspect rules. The --strict flag treats warnings as failures, and --format supports machine-readable output.

```bash
npx skillmds lint ./my-skill
npx skillmds lint ./my-skill --strict
npx skillmds lint . --format sarif
npx skillmds rules SK010
```

--------------------------------

### Scan a skill for security issues

Source: https://skillmd.com/docs/cli

Runs a security scan over a skill. Use the --deny flag to exit non-zero if specific security flags are detected, which is useful for CI gates.

```bash
skillmd scan .
skillmd scan . --deny executes_scripts network_access
```

--------------------------------

### Add MCP server to Claude Code (claude mcp add skillmd)

Source: https://skillmd.com/docs/mcp

Register the server with Claude Code as `skillmd`. Uses `@latest` to ensure the latest version.

```bash
claude mcp add skillmd -- npx -y skillmds@latest
```

--------------------------------

### skillmd_recommend

Source: https://skillmd.com/docs/mcp

Similar-skill and trending recommendations anchored on a skill you already know.

```APIDOC
## skillmd_recommend

### Description
Similar-skill and trending recommendations anchored on a skill you already know.

### Parameters
- **based_on** (string) - Required - A slug to anchor recommendations on.
- **limit** (number) - Optional - Result count.
```

--------------------------------

### rules

Source: https://skillmd.com/docs/cli

Lists every lint rule the CLI checks, or shows one rule in detail when given a rule ID. Supports JSON output.

```APIDOC
## rules

### Description
Lists every lint rule the CLI checks, or shows one rule in detail.

### Method
CLI command

### Endpoint
`skillmd rules [id]`

### Parameters
#### Arguments
- **id** (string) - Optional - Rule ID such as `SK010`.

#### Flags
- **--json** (boolean) - Optional - Output in JSON format.

### Request Example

skillmd rules
skillmd rules SK010 --json


### Response
#### Success Response
List of rules or detailed rule information.

#### Response Example
(No explicit response example provided in source.)
```

--------------------------------

### Use @skillmds/core library

Source: https://skillmd.com/docs/format

Import the lint function to analyze source code programmatically. The result object provides status, diagnostics, security findings, and a quality score.

```javascript
import { lint } from "@skillmds/core";

const result = lint(source, { slug: "pdf-table-extract" });

result.ok;                 // false when any diagnostic is an error
result.diagnostics;        // [{ id: "SK011", severity: "warn", message: "..." }]
result.security.flags;     // ["executes_scripts", "network_calls"]
result.security.findings;  // every match, with its line number and snippet
result.score;              // 84
```

--------------------------------

### Configure SkillMD GitHub Action

Source: https://skillmd.com/docs/format

Integrate SkillMD into CI workflows to lint files and upload SARIF results to the GitHub Code scanning tab.

```yaml
- uses: skillmds/skillmd/action@v1
  with:
    path: skills
    strict: "true"
```

--------------------------------

### Search the public registry

Source: https://skillmd.com/docs/cli

Searches for skills in the public registry with optional filters for category, verification status, type, and rating.

```bash
skillmd search "pdf extraction" --verified --limit 10
skillmd search "changelog" --category writing --type single
```

--------------------------------

### skillmd_get

Source: https://skillmd.com/docs/mcp

Fetch one skill's full record: the SKILL.md body, provenance, license, and any security flags.

```APIDOC
## skillmd_get

### Description
Fetch one skill's full record: the SKILL.md body, provenance, license, and any security flags.

### Parameters
- **slug** (string) - Required - Format `<owner>/<name>`.
```

--------------------------------

### skillmd publish and submit: publish a skill to the registry

Source: https://skillmd.com/docs/cli

Publishes a skill to the registry. Requires a stored token and refuses to publish if lint reports errors. The --dry-run flag runs lint only without publishing; --force overrides lint warnings but not errors. The submit alias works the same way.

```bash
skillmd publish ./my-skill --dry-run
skillmd publish ./my-skill --type pack
skillmd submit ./my-skill --force
```

--------------------------------

### Set SKILLMD_API for a custom API base URL

Source: https://skillmd.com/docs/mcp

Override the default API base URL to point to staging or a self-hosted registry. The default is `https://api.skillmd.com`.

```bash
SKILLMD_API=https://staging.example.com npx -y skillmds@latest
```

--------------------------------

### Set SKILLMD_TOKEN for authenticated access

Source: https://skillmd.com/docs/mcp

Pass a bearer token as an environment variable to access authenticated endpoints. Without a token, `skillmd_list_saved` returns a notice to sign in instead of an error.

```bash
SKILLMD_TOKEN=your-token npx -y skillmds@latest
```

--------------------------------

### skillmd_list_saved

Source: https://skillmd.com/docs/mcp

List the signed-in user's saved skills. Requires `SKILLMD_TOKEN` to be set on the server process. Without it, the tool returns a notice explaining that, rather than failing.

```APIDOC
## skillmd_list_saved

### Description
List the signed-in user's saved skills. Requires `SKILLMD_TOKEN` to be set on the server process. Without it, the tool returns a notice explaining that, rather than failing.
```

--------------------------------

### Minimal SkillMD skill file

Source: https://skillmd.com/docs/format

The smallest file that passes validation. It has no license field, so skillmd lint would flag SK011 as a warning, not an error.

```markdown
---
name: my-skill
description: "One clear sentence describing exactly what this skill does and when to use it."
---

## What this does

This skill helps an agent complete a specific, narrow task. Explain the
task here in plain language, so the agent knows when to reach for it.

## Instructions

Write the actual steps the agent should follow. Be specific about inputs,
outputs, and any edge cases the agent needs to handle along the way.

```

--------------------------------

### search

Source: https://skillmd.com/docs/cli

Searches the public registry with filters for category, verification, type, rating, and limit. Supports JSON output.

```APIDOC
## search

### Description
Searches the public registry.

### Method
CLI command

### Endpoint
`skillmd search <query>`

### Parameters
#### Arguments
- **query** (string) - Required - Search query.

#### Flags
- **--category** (string) - Optional - Restrict to one category (slug).
- **--verified** (boolean) - Optional - Restrict to skills that passed safety review.
- **--type** (string) - Optional - `single` or `pack`.
- **--min-rating** (number) - Optional - Minimum rating threshold.
- **--limit** (number) - Optional - Maximum results. Default `20`.
- **--json** (boolean) - Optional - Machine-readable output.

### Request Example

skillmd search "pdf extraction" --verified --limit 10
skillmd search "changelog" --category writing --type single


### Response
#### Success Response
Search results from the registry.

#### Response Example
(No explicit response example provided in source.)
```

--------------------------------

### skillmd login: store a personal access token

Source: https://skillmd.com/docs/cli

Stores a personal access token for authenticated commands. You can pass the token directly with --token and optionally store an API base with --api. The token is written to ~/.skillmd/config.json with file mode 0600.

```bash
skillmd login
skillmd login --token sk_live_xxxxx --api https://api.skillmd.com
```

--------------------------------

### skillmd_trending

Source: https://skillmd.com/docs/mcp

Leaderboard of top skills.

```APIDOC
## skillmd_trending

### Description
Leaderboard of top skills.

### Parameters
- **range** (string) - Optional - `30d` or `all`, default `all`.
- **category** (string) - Optional - Restrict to one category.
- **limit** (number) - Optional - Result count.
```
Tokens:
Raw