Skills - Findy Library

Overview

A skill is a reusable unit of workflow knowledge for an AI agent, defined as a directory holding a required SKILL.md file and optional supporting files. The SKILL.md encodes the procedure: step-by-step guidance, a fixed output format, and the decision points that genuinely need a human. Once written, it is invoked as a command or triggered automatically, and produces similar results no matter who runs it. This page explains the principles behind skills, their structure, and how to create and invoke one.

Design principles

A skill exists to give an agent the context it otherwise lacks for real work: the domain expertise and procedures specific to your organization. Its design rests on four principles.

Domain expertise

Capture your organization’s procedural knowledge in a version-controlled form, so the agent works from supplied context instead of guesswork.

Repeatable workflows

Turn multi-step tasks into consistent, auditable procedures that run the same way no matter who invokes them.

Cross-product reuse

Write a skill once and use it with any skills-compatible agent or product.

Progressive disclosure

Only the name and description load at startup; the body and supporting files load only when they become relevant.

Anatomy of a skill

A skill lives in its own directory (in Claude Code, .claude/skills/<skill-name>/) and consists of a SKILL.md file plus optional supporting files.

Directory layout

.claude/skills/
└── commit-message/
    ├── SKILL.md                       # Required. Frontmatter + instructions
    ├── references/                    # Optional. Read only when the body links to them
    │   └── semantic_versioning.md
    └── scripts/                       # Optional. Executed, not loaded into context
        └── check_format.sh

Part	Role
`SKILL.md`	The required file, holding the frontmatter that identifies the skill and the instructions for the agent.
`references/`	Optional supporting documents — full rule tables, templates, long examples — linked from the body and read only when needed.
`scripts/`	Optional utility scripts the body tells the agent to run. Only their output enters the context, not their source.

Structure of SKILL.md

SKILL.md has two parts: YAML frontmatter that identifies the skill, and a Markdown body with the instructions and examples.

SKILL.md

---
name: commit-message
description: Generate commit messages that follow semantic versioning rules. Use when committing changes or when asked to write a commit message.
---

# Instructions

1. Inspect the staged diff and classify the change as major, minor, or patch.
2. Combine it with a type prefix (feat, fix, docs, ...) per
   references/semantic_versioning.md.
3. Output a single-line message in the form `<level>-<type>: <summary>`.

Part	Role
`name`	The identifier, kept matching the directory name — which is also where the invoking command (`/commit-message` in Claude Code) comes from.
`description`	When the skill applies. The agent matches requests against this text, so it decides whether the skill triggers at all.
`allowed-tools`	Optional. The tools the skill is allowed to use. An experimental field, so support varies between implementations; see “Keep tool permissions minimal” below for how to scope it.
Body	The instructions the agent follows once the skill is active: steps, output format, examples.

Progressive disclosure

A skill is loaded in stages rather than all at once. At session start the agent reads only the frontmatter of every installed skill. The body is read when a request matches the description, and files under references/ are read only when the body points to them. Instructions that would otherwise sit permanently in a system prompt or an MCP tool definition therefore cost almost no context until the moment they are needed.

Creating a skill

Name and describe for discovery

The name and description are the only parts loaded before the skill is chosen, so they carry the whole burden of discovery.

Name skills after the action, in lowercase and hyphens. Avoid vague names such as helper or utils.
Write the description in third person, state both what the skill does and when to use it, and include the words a user would actually say.

Write for a capable reader

The agent already has general programming knowledge, so include only what it cannot infer: your conventions, your constraints, your procedures. Concise instructions outperform thorough ones.

Keep the SKILL.md body under roughly 500 lines; move bulk material to references/ files.
Keep references one level deep — every supporting file should be linked directly from SKILL.md, because nested reference chains get read partially.
Use one term per concept throughout (always “field”, not a mix of “field”, “box”, and “element”).
Avoid time-sensitive statements (“before August, use the old API”) that silently become wrong.
Heavy use of “MUST”, “NEVER”, and “ALWAYS” is a warning sign. Explaining why a rule exists works better than stacking prohibitions, because the agent can then judge unforeseen situations correctly.
Also state what to do off the happy path — a missing argument, an external service returning an error. When the instructions cover only the normal case, the behavior in exceptional cases varies from run to run.

Provide a template for the output format

When output consistency matters, provide a template for the output format and match its strictness to the task — anywhere from a loose example of the structure to an exact template the agent must always follow.

Where downstream processing or tools depend on the shape of the output — data formats, standardized reports — use a strict template and state that this exact structure must always be used.
Where the structure may reasonably vary with the content, present the template as a sensible default and note that it can be adapted to the situation.

A strict template (for report generation)

## Report structure

ALWAYS use this exact template structure:

# [Analysis Title]

## Executive summary
[One-paragraph overview of key findings]

## Key findings
- Finding 1 with supporting data

## Recommendations
1. Specific actionable recommendation

Show with input/output examples

Elements that resist description — style, tone, level of detail — are best conveyed as input/output pairs. Showing the desired output carries more reliably than describing it.

Examples in the body (for commit-message)

# Examples

- Input: fix a typo in the README installation steps
  Output: `patch-docs: fix typo in installation steps`
- Input: add JWT-based login to the auth service
  Output: `minor-feat: add JWT login to auth service`

When the output must always follow the same structure, use the template from the previous section instead of examples. Examples also consume context every time the body loads, so move long or numerous examples into a references/ file that is read only when needed.

Match freedom to fragility

Decide how much latitude the instructions leave, based on how fragile the task is. Where many approaches are valid — a code review, an analysis — give heuristics and let the agent choose the route. Where the operation is fragile or must be consistent — a migration, a release step — give the exact command and state that it must not be modified. When several tools could work, name one default and mention an alternative only for the cases where the default fails.

Keep tool permissions minimal

Grant a skill only the tools its workflow actually uses. In Claude Code, declare them as allowed-tools in the frontmatter of SKILL.md:

allowed-tools: Read, Glob, Bash(git status*), Bash(git diff*)

Do not allow tools that never appear in the procedure. A skill that only reads has no need for Write or Edit.
Scope Bash per command: split a broad pattern like Bash(git *) into specific ones such as Bash(git status*) and Bash(git diff*).
As a rule, do not allow destructive commands such as rm or git push --force.

A skill that only provides knowledge and uses no tools needs no allowed-tools declaration at all.

Build in verification

Multi-step skills drift without checkpoints. Two patterns keep them on track:

Checklists. Have the skill emit its step list and check items off as it progresses, so skipped steps become visible.
Feedback loops. Pair each output with a validation step — a validator script, a lint run, a checklist review — and instruct the agent to fix and re-validate until it passes before moving on.

Orchestrate sub-agents

A skill with many steps runs more reliably as an orchestrator — the SKILL.md body directs the flow while independent subtasks are handed off to sub-agents — than as one long procedure executed by a single agent.

Run subtasks with no dependencies between them in parallel; per-dimension reviews or multi-area investigations have no reason to run in sequence.
Make each sub-agent’s instructions self-contained. Sub-agents cannot see the calling conversation, so pass all necessary context in the prompt.
Always follow a parallel phase with a step that consolidates the results.
Spell out in the body how data crosses steps — which later step consumes the output of an earlier one.

Keep the parallel count to a handful; beyond that, the cost of consolidation outweighs the gain from parallelism.

Create with skill-creator

skill-creator is a tool from Anthropic that supports writing a new skill. In Claude Code, install it from the official marketplace:

/plugin install skill-creator@claude-plugins-official

Describing the skill you want starts an interactive flow. skill-creator confirms the purpose and the decisions the skill should surface, then scaffolds the directory — SKILL.md, references/ files, and scripts/ when needed — in the structure described earlier on this page, and cleans up files that turn out to be unnecessary.

Invoking a skill

A skill is invoked in two ways. Explicitly, as a command, or automatically, when the agent matches the request against the skill’s description. Both paths run the same SKILL.md; the command is simply the direct handle. A skill is not limited to a single-shot task. Its body can drive a longer, interactive flow that asks clarifying questions, runs sub-agents in parallel, and calls other skills as steps.

See Vibe Coding for the collaboration basics that skills build on, and Agentic Workflow for the delegation model where multi-step skills run.

​Overview

​Design principles

Domain expertise

Repeatable workflows

Cross-product reuse

Progressive disclosure

​Anatomy of a skill

​Directory layout

​Structure of SKILL.md

​Progressive disclosure

​Creating a skill

​Name and describe for discovery

​Write for a capable reader

​Provide a template for the output format

​Show with input/output examples

​Match freedom to fragility

​Keep tool permissions minimal

​Build in verification

​Orchestrate sub-agents

​Create with skill-creator

​Invoking a skill

Overview

Design principles

Anatomy of a skill

Directory layout

Structure of SKILL.md

Progressive disclosure

Creating a skill

Name and describe for discovery

Write for a capable reader

Provide a template for the output format

Show with input/output examples

Match freedom to fragility

Keep tool permissions minimal

Build in verification

Orchestrate sub-agents

Create with skill-creator

Invoking a skill