Claude Code skills
Claude Code skills: how they work and the skills Nimbalyst ships
Nimbalyst is an open-source visual workspace that runs Claude Code and OpenAI Codex side by side, with pluggable agent harnesses. The desktop and iOS apps are MIT licensed.
Definition
What are Claude Code skills?
A Claude Code skill is a reusable agent capability stored as a folder. The folder contains a SKILL.md file and can also include scripts, examples, templates, or reference files.
The current Claude Code layout supports three locations:
- Project skills:
.claude/skills/<skill-name>/SKILL.md - User skills:
~/.claude/skills/<skill-name>/SKILL.md - Plugin skills:
<plugin>/skills/<skill-name>/SKILL.md
SKILL.md is the contract. It tells Claude what the skill is for, when to use it, and what workflow to follow once loaded. A good skill defines three things: a trigger (the description Claude matches against), a workflow (what to read, run, and output), and any extra context (supporting files in the same folder).
Skills turn repeated prompt patterns into named, versioned workflows that live in a repo, can be reviewed in Git, and are reused across sessions.
Mechanism
How Claude Code skills work
Claude Code uses YAML frontmatter in SKILL.md as the configuration surface. The most important field is description, because Claude uses it to decide when to auto-load the skill.
A minimal skill looks like this:
---
name: release-notes
description: Draft release notes from merged pull requests. Use when the user asks for release notes, changelog copy, or a ship summary.
---
# Release Notes Skill
1. Read the recent merged PRs.
2. Group changes by user-visible impact.
3. Draft concise release notes.When Claude Code encounters a relevant request, the flow is:
- Match the request against available skill descriptions.
- Load the matching
SKILL.md. - Pull in supporting files only when the instructions require them.
- Keep running as the same agent, with the skill instructions in context.
Skills can auto-load from their description, so you do not need to rely only on a manual slash invocation. Older custom command files under .claude/commands/*.md still work, but the modern skill layout is .claude/skills/<name>/SKILL.md, especially when the workflow needs supporting files.
Examples
Skills Nimbalyst ships
The Nimbalyst open-source repo ships true folder-based Claude Code skills under packages/extensions/*/claude-plugin/skills/*/SKILL.md. The clearest visual examples produce output that opens in a dedicated editor inside the workspace.
Visual skills
/mockup
Generate UI mockups and wireframes from a text description. Output opens in Nimbalyst's mockup editor.
/excalidraw
Produce architecture diagrams, flowcharts, and system maps. Output opens in Excalidraw.
/datamodel
Design database schemas as Prisma files. Output renders as a visual ERD.
Developer skills
/design
Create structured implementation plans with architecture decisions.
/implement
Execute plan documents with progress tracking.
/commit
AI-assisted git commits with impact-focused messages.
/review-branch
Comprehensive read-only code review of branch changes.
/bug-report
Guided bug report creation with codebase investigation.
/playwright
Write and manage E2E tests with Playwright.
Product management skills
/prd
Create structured Product Requirements Documents.
/track
Track bugs, tasks, ideas, and decisions in markdown.
/roadmap
Generate product roadmaps from plans and priorities.
/triage-requests
Triage, deduplicate, and prioritize feature requests.
For the full catalog of skills shipped with Nimbalyst, see the complete skills index.
Build your own
Building your own Claude Code skill
The shortest useful recipe:
- Create a folder at
.claude/skills/<name>/. - Add a
SKILL.mdfile with YAML frontmatter. - Write a precise
descriptionso Claude knows when to use the skill. - Add the workflow steps in the body.
- Drop examples or scripts into the same folder when the workflow needs more context.
- Test on a real task and tighten the instructions where Claude improvises badly.
If the workflow is one short markdown file, a command under .claude/commands/ may still be enough. When the workflow needs reference files, templates, or a reusable package of context, prefer a skill folder.
Inside Nimbalyst, project .claude/skills, user ~/.claude/skills, project .claude/commands, and extension-provided workflows all feed a shared workflow registry, so the same workspace can expose Claude-compatible workflows to Claude Code sessions and export generated skills for Codex sessions when needed.
Comparison
Subagents vs skills
Skills, commands, and subagents are three separate Claude Code primitives. They get mixed up constantly.
Skills
Reusable capabilities defined by a folder and a SKILL.md file. Best for workflows you want Claude to learn and reuse. Live in .claude/skills/.
Commands
Slash-triggered markdown files, usually one file each. Live in .claude/commands/. Still supported and common in older repos.
Subagents
Fresh agent instances with their own context window, tool permissions, and instructions. Live in .claude/agents/. A parent agent can dispatch several in parallel.
A skill extends what one agent knows how to do. A subagent creates another agent to do part of the work. A command is a slash-triggered workflow file, usually without the richer folder structure of a skill. The two systems cooperate: a skill can instruct Claude to fork a context, and a subagent can preload one or more skills.
FAQ
Frequently asked questions
What is a Claude Code skill?
A Claude Code skill is a reusable folder with a SKILL.md file plus any supporting files the workflow needs. Claude can auto-load the skill when a request matches its description, or you can invoke it directly from slash command typeahead.
Where do Claude Code skills live?
Project skills live in .claude/skills/<name>/SKILL.md. User skills live in ~/.claude/skills/<name>/SKILL.md. Plugin-bundled skills live in a plugin's skills/<name>/SKILL.md directory.
What is inside SKILL.md?
SKILL.md contains YAML frontmatter plus a markdown body. The frontmatter defines the skill metadata, especially the description that Claude uses for matching. The body contains the workflow, examples, and references.
How does Claude Code load a skill?
Claude matches the request against available skill descriptions, loads the relevant SKILL.md, then reads supporting files only if the instructions call for them. The same agent keeps running with that skill in context.
Are .claude/commands obsolete?
No. Command files still work and many repos still rely on them. The skill folder layout is better when you want a richer package with supporting files instead of a single markdown command.
How are Claude Code skills different from subagents?
Skills extend one agent's capabilities. Subagents create fresh agent instances with their own context window, tool permissions, and instructions. Skills live under .claude/skills/. Subagents live under .claude/agents/.
Does Nimbalyst support both Claude Code and Codex?
Yes. Nimbalyst is an open-source visual workspace that runs Claude Code and OpenAI Codex side by side, with pluggable agent harnesses.
Is Nimbalyst open source?
Yes. The desktop and iOS apps are MIT licensed.
Which folder-based Claude Code skills does Nimbalyst ship today?
The current open-source repo includes mockuplm, excalidraw, datamodellm, planning, git-commit, feedback-intake, and extension-development as folder-based skills.
What is the best example of a visual Claude Code skill in Nimbalyst?
MockupLM, Excalidraw, and DataModelLM are the strongest examples because the skill output opens in a dedicated visual editor instead of staying as raw text in the transcript.