Skills

Anatomy of a skill

A skill is a single .md file. The top of the file is a YAML frontmatter block delimited by --- lines; everything after is the markdown body the agent reads when it loads the skill. The full bundled refactor skill, verbatim:

---
name: refactor
description: Systematic refactoring pattern — find, read, plan, apply, verify
---
# Refactor skill

When refactoring:
1. Search the codebase for the target pattern (Grep).
2. Read affected files (Read).
3. Plan the edits.
4. Apply edits (Edit) one file at a time.
5. Run tests (Bash) to verify.

The frontmatter is a flat mapping. The loader recognises five keys; everything else is ignored:

If pyyaml is installed the frontmatter is parsed as real YAML. If not, Fulcrum falls back to a flat key: value parser that handles plain scalars, quoted strings, and inline lists — enough for the documented schema. Either way, malformed lines are skipped silently rather than failing the whole skill.

Bundled skills

These ship inside the Fulcrum binary. They have the lowest precedence in the loader — anything you write into ~/.fulcrum/skills/ with the same name shadows them. The current bundle is deliberately small; the assumption is teams will accumulate their own.

Adding your own skill

Three shapes, depending on how big the skill is and where it comes from. All three end up in ~/.fulcrum/skills/, which the loader scans on every session start.

A. Drop a markdown file

The simplest form. One file, one skill. Good for workflows that fit in a couple of paragraphs.

mkdir -p ~/.fulcrum/skills
$EDITOR ~/.fulcrum/skills/code-review.md

Frontmatter (name, description) plus the markdown body the agent will follow:

---
name: code-review
description: Use when the user asks for a code review of a diff or PR.
---
# Code review checklist

When reviewing a diff:
1. Run `git diff` against the merge base to get the full change set.
2. For each touched file, read the surrounding 50 lines for context.
3. Flag: unhandled errors, missing tests, N+1 queries, security issues.
4. Group findings by severity. Quote the exact lines you're flagging.
5. Never approve silently — always explain your reasoning.

Restart Fulcrum, then run /skills to confirm it loaded.

B. Folder-style skill

For longer skills with supplementary files. Drop a directory under ~/.fulcrum/skills/ with a top-level SKILL.md as the entry point; the loader picks it up by recursing one to three levels deep looking for SKILL.md files.

~/.fulcrum/skills/
  deployment-playbook/
    SKILL.md         # frontmatter + body — the entry point
    rollback.md      # referenced from SKILL.md by relative path
    smoke-tests.md

Only SKILL.md needs frontmatter. Supplementary files are referenced from the body by relative path; the agent will read them with the Read tool when it actually needs them, which keeps the initial skill load cheap.

C. Install from a marketplace

A marketplace is any git repo with a .claude-plugin/marketplace.json at its root listing plugins. Add the marketplace once, then install plugins by name. Installed plugins are copied into ~/.fulcrum/skills/<plugin>/ so they show up in /skills alongside everything else; uninstalling is just deleting the directory.

/marketplace add https://github.com/alirezarezvani/claude-skills
/marketplace search focused-fix
/marketplace install engineering-advanced-skills
/skills    # confirm they loaded

Marketplaces are cloned into ~/.fulcrum/marketplaces/ and tracked in ~/.fulcrum/marketplaces.json. Pulling the latest version of a marketplace does not auto-update installed plugins — re-run install with --force to refresh.

What makes a good skill

A skill the agent never loads is wasted. A skill the agent loads at the wrong time is worse than nothing. The difference is almost entirely in how you write the description and the body.

• Action-oriented description. "Use when the user wants to rename, extract, or move code" beats "This skill helps with refactoring." The model picks skills by matching intent to description; lead with the trigger, not the topic.
• Concrete steps, not principles. The agent reads the body and follows it. "Always run tests after editing" is fine; "Quality matters" is noise.
• Cite tools by name. If the skill should call Grep, write "run Grep with pattern X". Don't say "search for X" — the model has to guess which tool you meant.
• Constraints up front. "Never edit files outside src/" is more useful as the first paragraph of the body than as a footnote at the bottom.
• Tight scope.One skill per workflow. Don't write a 3000-word universal skill; write three 800-word focused ones. The model is much better at picking the right narrow skill than at navigating a long broad one.

How skills get triggered

Skills are surfaced to the agent as a tool. When you start a turn, the agent looks at every loaded skill's description and decides whether any of them matches the work — if one does, it invokes the Skilltool with that name and the body is rendered into the conversation. You can also force it: name a skill explicitly in your prompt ("use the refactor skill") and Fulcrum will prioritise it.

Source precedence on name collision is: bundled < Claude Code plugins < ~/.claude/skills/ < ~/.fulcrum/skills/. Your user skills always win. Plugin skills are namespaced <plugin>:<name> so they never collide with anything else.

Inspecting installed skills

The /skills slash command lists every loaded skill with its origin tag (bundled, claude, fulcrum) and one-line description. Use it after editing a skill file to confirm Fulcrum picked up your change:

/skills

loaded 3 skill(s):
  refactor                         [bundled]  Systematic refactoring pattern …
  code-review                      [fulcrum]  Use when the user asks for a code review …
  engineering:focused-fix          [claude]   Tightly-scoped bug fix loop …

For the full body of any skill, just catthe file — there's no special encoding. The agent sees the same markdown you do.

Skills vs. plugins vs. MCP

Three extension points, often confused. The deciding question is what kind of thing you're adding:

A rule of thumb: if you're writing instructions, use a skill. If you're writing a command, use a plugin. If you're writing a tool the model should call, use MCP.

Next steps

• Tools → The built-in tools your skills can cite by name — Grep, Read, Edit, Bash, and the rest.
• Memory & knowledge → The other half of ~/.fulcrum/ — knowledge that persists across sessions, separate from skills.
• Best practices → How to compose skills, memory, and sub-agents into a workflow that actually saves you time.