CLI reference

This page documents every skillmd command, its arguments, and its flags. If a flag isn't listed here, it doesn't exist.

Install

The package is skillmds on npm. It installs a binary named skillmd. You need Node 18 or later.

npm i -g skillmds

Running skillmd with no arguments opens an interactive menu when you're in a terminal. Every command below also works non-interactively, which is what you want in scripts and CI.

Command overview

Command	Alias	Purpose
`lint [target]`	`check`	Validate a SKILL.md and print a quality score
`scan [target]`		Scan for scripts, network calls, and secret access
`rules [id]`		List lint rules, or show details for one
`init [name]`		Scaffold a new SKILL.md
`search <query>`		Search the registry
`info <slug>`		Show registry details for one skill
`add <source>`		Install a skill from the registry, GitHub, or a local path
`list`	`ls`	List installed skills
`remove <names...>`	`rm`	Remove installed skills
`update [names...]`		Re-fetch installed skills from the registry
`publish [target]`	`submit`	Publish a skill to the registry
`login`		Store a personal access token
`logout`		Remove the stored token

Global options

These work with any subcommand. Put them after the subcommand name.

Flag	Effect
`--json`	Print machine-readable output instead of text
`--token <token>`	Use this token for this call instead of the stored one
`--api <url>`	Use this API base URL instead of the default
`--version`	Print the installed CLI version

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

Only publish requires a token. Every other command works unauthenticated. The CLI resolves the token in this order: --token, then the SKILLMD_TOKEN environment variable, then ~/.skillmd/config.json, then nothing. It resolves the API base the same way: --api, then SKILLMD_API, then the stored config, then https://api.skillmd.com.

lint

Alias: check. Validates a SKILL.md against the format rules and prints a quality score.

Argument: [target], a local path or GitHub source. Defaults to ..

Flag	Effect
`--format <fmt>`	`text`, `json`, `sarif`, or `github`. Default `text`.
`--strict`	Treat warnings as failures
`--fail-on-warning`	Exit non-zero if any warning is reported
`--fix`	Apply safe fixes automatically, such as inserting a missing license
`--errors-only`	Suppress warnings from the output

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

Use --format sarif or --format github to feed lint results into CI annotations.

scan

Runs a security scan over a skill: scripts it executes, network calls it makes, and secret access it declares.

Argument: [target], defaults to ..

Flag	Effect
`--deny <flags...>`	Exit non-zero if any of the named flags is present, for example `executes_scripts`
`--format <fmt>`	`text` or `json`

skillmd scan .
skillmd scan . --deny executes_scripts network_access

--deny is what you wire into a CI gate: fail the build if a skill executes scripts or reaches the network, without reading the full report by hand.

rules

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

Argument: [id], a rule id such as SK010.

Flag: --json.

skillmd rules
skillmd rules SK010 --json

Run skillmd rules with no argument when a lint error references a rule id you don't recognize.

init

Scaffolds a new SKILL.md from a template.

Argument: [name].

Flag	Effect
`--name <name>`	Skill name, if you didn't pass it as the argument
`--description <text>`	Description written into the frontmatter
`--license <license>`	License identifier. Default `MIT`.
`-y`, `--yes`	Skip confirmation prompts

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

The file is written to <dir>/<slug>/SKILL.md, where <slug> is derived from the name.

search

Searches the public registry.

Argument: <query>, required.

Flag	Effect
`--category <slug>`	Restrict to one category
`--verified`	Restrict to skills that passed safety review
`--type <type>`	`single` or `pack`
`--min-rating <n>`	Minimum rating threshold
`--limit <n>`	Maximum results. Default `20`.
`--json`	Machine-readable output

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

info

Shows registry details for one skill: description, rating, verification status, and version history.

Argument: <slug>, required, in <owner>/<name> form.

This command only takes the global options.

skillmd info anthropic/pdf
skillmd info anthropic/pdf --json

add

Installs a skill from a registry slug, a GitHub source, or a local path. The CLI lints the skill before writing it to disk.

Argument: <source>, required. A registry slug like anthropic/pdf, a GitHub reference, or a local directory.

Flag	Effect
`-g`, `--global`	Install to your user-level skills directory instead of the current project
`-a`, `--agent <agents...>`	Target one or more agents by name
`-s`, `--skill <names...>`	From a pack, install only the named skills. Use `*` for all.
`--copy`	Copy the skill's files into the target directory. This is the default behavior.
`-y`, `--yes`	Skip confirmation prompts
`--skip-lint`	Skip the pre-install lint check
`--deny <flags...>`	Refuse to install if a scan flag is present, for example `network_access`

skillmd add anthropic/pdf
skillmd add anthropic/pdf -a claude-code cursor -g
skillmd add anthropic/pdf-pack -s changelog release-notes
skillmd add ./local-skill --skip-lint
skillmd add owner/repo --deny executes_scripts

Without -a, add writes to whichever agent skills directory already exists in your project, falling back to Claude Code's. Skills land at <agent-dir>/<skill-name>/SKILL.md:

Agent	Skills directory
Claude Code	`.claude/skills`
Cursor	`.cursor/skills`
Codex	`.codex/skills`
Windsurf	`.windsurf/skills`
OpenCode	`.opencode/skills`

-g uses the equivalent directory under your home directory instead of the project.

list

Alias: ls. Lists installed skills across every agent directory the CLI detects.

Flag	Effect
`-g`, `--global`	List from your user-level skills directories instead of the project
`--json`	Machine-readable output

skillmd list
skillmd list -g --json

remove

Alias: rm. Removes installed skills by name.

Argument: <names...>, required, one or more skill names.

Flag: -g, --global, removes from the user-level directory instead of the project.

skillmd remove my-skill
skillmd rm my-skill other-skill -g

update

Re-fetches installed skills from the registry and rewrites them on disk if the registry copy changed.

Argument: [names...], defaults to every installed skill.

Flag: -g, --global, updates the user-level installs instead of the project.

skillmd update
skillmd update anthropic-pdf -g

publish

Alias: submit. Publishes a skill to the registry. Requires a stored token, and refuses to publish if lint reports errors.

Argument: [target], defaults to ..

Flag	Effect
`--type <type>`	`single` or `pack`. Default `single`.
`--force`	Publish despite lint warnings. Does not override lint errors.
`--dry-run`	Run the lint check only, without publishing

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

Every publish goes through a safety review before it becomes visible in search. --dry-run is how you check lint status ahead of time without triggering that review.

login

Stores a personal access token for authenticated commands.

Flag	Effect
`--token <token>`	Pass the token directly instead of typing it at a masked prompt
`--api <url>`	Store this API base alongside the token

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

The token is written to ~/.skillmd/config.json with file mode 0600.

logout

Removes the stored token. Takes no arguments beyond the global options.

skillmd logout