Skip to main content

Tutorial: Install & Use

The Install stage adds a skill to your runtime's skills directory. The Use stage invokes that skill in conversation. They are tightly coupled — a skill you cannot trigger is functionally not installed — so this tutorial covers both end-to-end.

These tutorials show Skillsmith in Claude Code. For installation in your preferred runtime (Cursor, Continue, Copilot, Windsurf), see Getting Started.

What you will do

  • Install a skill into ~/.claude/skills/
  • Validate the install structure
  • Invoke the skill in a Claude Code conversation
  • Troubleshoot when a skill does not trigger

Tools that map to Install and Use

Stage Surface Tool / command Purpose
Install MCP install_skill Install a skill from the registry to the runtime's skills directory
Install MCP skill_validate Validate SKILL.md structure pre- or post-install
Install CLI skillsmith install <id> Same as MCP install_skill
Use Runtime (natural prompts) The runtime — Claude Code in this tutorial — invokes the skill via its trigger phrases

Step 1 — Install a skill

Pick a skill ID from Evaluate. We will use community/jest-helper as the running example.

Try these prompts:

  • "Install community/jest-helper"
  • "Install jest-helper to ~/.claude/skills"
  • "Install community/git-commit and overwrite if it exists"

Skillsmith downloads the skill bundle, verifies the SKILL.md structure, and writes it to your runtime's skills directory. On Claude Code that is ~/.claude/skills/<author>/<name>/.

Other runtimes write to other paths

Cursor, Copilot, and Windsurf each have their own skills directory. Set SKILLSMITH_CLIENT in your MCP server's environment config to cursor, copilot, or windsurf and Skillsmith will route the install to the right place. Defaults to claude-code. See Getting Started.

Step 2 — Validate the install

Skillsmith validates SKILL.md structure during install, but if you ever receive a skill outside the registry — for example, a teammate hands you a directory — validate it before relying on it.

Try these prompts:

  • "Validate the skill at ~/.claude/skills/community/jest-helper"
  • "Check the structure of my local ./my-skill directory"

Or from the terminal:

skillsmith author validate ~/.claude/skills/community/jest-helper

Validation checks that SKILL.md exists, has the required YAML frontmatter (name, description), and that referenced bundle files (scripts, assets) actually exist on disk.

Step 3 — Use the skill in conversation

A skill is "used" when its trigger phrases match something you say to the runtime, and the runtime loads the skill's instructions into the conversation context. With community/jest-helper installed, triggers like the following should activate it:

  • "Help me write Jest tests for this function"
  • "Set up Jest in this project"
  • "Debug a failing Jest test"

The actual trigger phrases for any installed skill live in its SKILL.md frontmatter under description. Read them once after installing: "Read me the description of jest-helper so I know how to trigger it".

The /skillsmith slash command — most reliable trigger

Claude Code installs a bundled /skillsmith slash command when you run skillsmith setup. It gives you an unambiguous way to route any lifecycle action to the right Skillsmith tool, regardless of how natural-language tool selection might drift. 

/skillsmith discover testing
/skillsmith evaluate community/jest-helper
/skillsmith install community/jest-helper
/skillsmith audit
/skillsmith create "API doc generator"

If you ever find that a bare prompt is not triggering Skillsmith reliably, fall back to the slash form.

Step 4 — Troubleshoot when a skill does not trigger

The most common Use-stage failure is "I installed it but it never fires." Walk this checklist:

Check the install actually landed

Run this in your terminal:

ls ~/.claude/skills/community/jest-helper/SKILL.md

If the file is missing, Skillsmith never wrote it. Re-run the install, this time watching the output for an error.

Restart your runtime

Claude Code, Cursor, and most other runtimes load the skills directory once at startup. After installing a new skill, restart the runtime so it can pick up the SKILL.md.

Read the skill's trigger phrases

A skill's description in SKILL.md is what the runtime matches your prompts against. If the description says "Use when asked to write Jest tests" and you are saying "add unit tests", the runtime may not connect them. Either rephrase or read the description directly: 

cat ~/.claude/skills/community/jest-helper/SKILL.md | head -10

Check for namespace collisions

If two installed skills both claim a similar trigger phrase, the runtime picks one — usually not the one you want. Run the namespace audit to surface collisions: 

skillsmith audit collisions

The Maintain tutorial covers resolving collisions in detail.

Common pitfalls

"Skill already installed" error

By default install_skill refuses to overwrite. Pass force: true in the prompt or --force on the CLI to overwrite an existing install. Combine with a diff first if you are unsure what changed.

Wrong runtime path

If SKILLSMITH_CLIENT is unset, Skillsmith defaults to Claude Code (~/.claude/skills/). Cursor users who have not set the env var will see installs land in ~/.claude/skills/ rather than Cursor's skills directory, and Cursor will never load them. Set the env var in your MCP server's config and re-install.

API rate-limit during install

The free tier (no API key) caps at 10 requests total. After that, every install fails until you configure an API key. See API key setup.

Where to next

You have a working installed skill. Keeping it healthy — updating it, pinning it, auditing it — is the Maintain stage.

Reference: MCP install_skill · CLI install · Runtime install.

Previous: Evaluate — Next: Maintain