skillmarkdown

skillmarkdown is the CLI for creating, validating, publishing, discovering, and installing SKILL.md skills.

Use it when you want agent capabilities to live as reviewable files, move cleanly between repos, and stay pinned like normal project dependencies.

Website: www.skillmarkdown.com

Why Skillmarkdown

• Author skills as plain project files, not hidden UI state.
• Validate skill packages before they reach teammates or users.
• Publish versioned skills to your Skillmarkdown account.
• Install exact skill versions into a workspace or user-level skill directory.
• Keep skills.json and skills-lock.json as the visible dependency contract for agent skills.

Install

npm i -g skillmarkdown

Or run one-off commands:

npx skillmarkdown <command>

The package installs the skill binary.

skill --version

First Run

Start on the web, then finish in the terminal.

1. Open www.skillmarkdown.com.
2. Choose Sign Up and create your account.
3. Complete the browser account setup flow, including email verification if prompted.
4. Install the CLI.
5. Run skill login and use the same account.
6. Confirm the active account with skill whoami.

npm i -g skillmarkdown
skill login
skill whoami --json

After login, publishing and account-backed installs use your Skillmarkdown session.

Create And Publish A Skill

Create a new skill directory, inspect the generated files, validate the package, then publish.

skill create agent-code-audit --template minimal
cd agent-code-audit

skill validate --strict
skill publish --version 1.0.0 --tag latest

Prefer starting inside an existing directory?

mkdir my-skill
cd my-skill

skill init --template minimal
skill validate --strict
skill publish --version 1.0.0 --tag latest

Useful checks after publishing:

skill whoami
skill view agent-code-audit

Install Skills Into A Workspace

Install one skill directly:

skill install agent-code-audit

Install a specific version, tag, or semver range:

skill install agent-code-audit --version 1.0.0
skill install agent-code-audit --spec latest
skill install agent-code-audit --spec ^1.0.0

Installed workspace skills are written under:

.agents/skills/<skill-id>

User-level installs use:

skill install -g agent-code-audit

and write under:

$HOME/.agents/skills/<skill-id>

Workspace Dependencies

Use skills.json when a repo should declare the skills it needs. The CLI resolves those declarations into skills-lock.json.

{
  "version": 1,
  "defaults": {},
  "dependencies": {
    "research-skill": {
      "spec": "latest"
    },
    "@acme/ops-skill": {
      "spec": "^1.2.0"
    }
  }
}

# Install every declared dependency
skill install

# Remove undeclared lock/install entries
skill install --prune

Commit both files when dependency state matters:

• skills.json is the desired skill set.
• skills-lock.json is the exact resolved set.

Day-To-Day Commands

# Account
skill login
skill whoami
skill logout

# Authoring
skill create my-skill --template minimal
skill init --template verbose
skill validate --strict

# Publishing
skill publish --version 1.0.0 --tag latest
skill publish --version 1.0.1 --dry-run --json

# Discovery and installs
skill view my-skill
skill install my-skill
skill list
skill update --all
skill remove my-skill

Authentication

skill login signs you in for platform-backed commands.

Automation and non-interactive login are supported with environment variables:

[email protected] \
SKILLMD_LOGIN_PASSWORD='your-password' \
skill login

For API-calling commands, auth precedence is:

| Priority | Source | Example | | -------- | ----------------- | ---------------------------------------------------- | | 1 | CLI flag | skill --auth-token <token> publish --version 1.2.3 | | 2 | Environment | export SKILLMD_AUTH_TOKEN=<token> | | 3 | Signed-in session | skill login |

Command Summary

| Area | Commands | | -------------------- | ------------------------------------------ | | Create and validate | init, create, validate | | Session | login, logout, whoami | | Publish | publish | | Inspect | view | | Install and maintain | install, list, remove, update | | Global auth input | skill --auth-token <token> <command> ... |

Run any command with invalid or missing arguments to see its usage string.

Troubleshooting

• If publish, install, or view says you are not logged in, complete signup at www.skillmarkdown.com, then run skill login.
• If skill login succeeds but account-backed commands still fail, run skill whoami to confirm the active account.
• If a new skill fails validation, run skill validate --strict in the skill directory and fix issues before publishing.
• Published skills should stay text-first and reviewable. Do not include binary media files like png, jpg, gif, mp3, or mp4; use text, markdown, csv, json, or svg assets instead.

Support

• Website: www.skillmarkdown.com
• Security policy: SECURITY.md
• Issues: GitHub Issues

License

MIT