What is an agent skill made of?
The required file has two parts. At the top, a short block of settings identifies the skill and describes when to use it. This is called YAML frontmatter. Below it, the procedure is written in Markdown, a plain-text format with headings and lists. Optional folders can hold scripts, reference documents and templates.
---
name: monthly-close-report
description: Builds the month-end close packet from the exported ledger CSV. Use when someone asks for close, month-end, or the finance summary.
license: Proprietary. LICENSE.txt has complete terms
compatibility: Requires Python 3.14+ and read access to /finance/exports
allowed-tools: Read Bash(python:*)
---
# Monthly close report
1. Read /finance/exports/ledger-<month>.csv.
2. Reconcile against last month's closing balance in references/BALANCES.md.
3. Stop and ask before writing anything to the shared drive.The settings must follow the format expected by the tool you use. A naming or formatting error can prevent the skill from loading, so check the fields before testing it.
| Field | Required | Limit | What it controls |
|---|---|---|---|
| name | Yes | 64 characters | Must match the parent folder name exactly. Lowercase, numbers, single hyphens. |
| description | Yes | 1024 characters | The trigger. States what the skill does and when to use it. |
| allowed-tools | No | Space separated | Pre-approves tools. Experimental, so support varies by host. |
| compatibility | No | 500 characters | Environment the skill assumes: runtime, packages, network. |
| license | No | Short string | License name, or the bundled file carrying the terms. |
The skill name must match the folder name and follow the permitted naming format. Check those details if an installed skill is not being found.
How does an agent decide to use one?
The agent software, also called the host, can first read short descriptions of available skills. It then opens the full instructions when they are relevant to the task. This avoids loading every procedure at once. Supporting scripts can perform work and return results without putting all their code into the conversation.
A vague description such as “helps with reports” gives the agent little basis for choosing the skill. Name the kind of report, the information it needs and the requests it should handle. Then test whether it is selected for the right task.
What a skill cannot do
The host provides capabilities such as file access, a browser or connected business tools. MCP, the Model Context Protocol, is one way tools can be connected. A skill describing email steps cannot send mail unless an email tool and the required access are also available.
- It cannot grant a credential, an API key, or network access the host withholds.
- It cannot raise a permission ceiling. Approval prompts still fire on write, send, spend, delete, and deploy.
- It cannot rescue a bad procedure. Weak steps get followed faithfully, at speed.
- It cannot travel between surfaces. Claude Code, claude.ai, and the API hold separate copies.
The same skill can reach different files and tools depending on where it runs. A hosted service may restrict network and file access, while a local agent may have access to parts of your computer. Review the actual permissions of the installation you plan to use.
Where do skills install?
| Host | Personal location | Project location | Note |
|---|---|---|---|
| Claude Code | ~/.claude/skills/ | .claude/skills/ | Found on the file system at startup. No upload step. |
| Hermes | ~/.hermes/skills/ | skills/ in the project root | Installs from a repository path. Each skill is also a slash command. |
| OpenClaw | ~/.openclaw/skills | workspace skills folder | Workspace copies win name conflicts. Cross-agent discovery is unconfirmed. |
Do not assume a skill installed in one product appears in another. Keep a master copy with a change history, and record where each version is installed.
How do you review one before installing it?
unzip -l vendor-skill.zip
find ./vendor-skill -type f | sort
grep -rniE 'curl|wget|fetch|requests\.|urllib|https?://' ./vendor-skill
grep -rniE 'rm -rf|chmod|sudo|[.]env|api_key|token|credential' ./vendor-skill
skills-ref validate ./vendor-skillA format checker can catch naming and structure errors, but it cannot establish that the instructions are trustworthy. Review what the skill reads and what it may do with that information. A webpage or document it opens may contain instructions aimed at the agent; those should be treated as source content, not as permission to take a new action.
What makes a skill easier to maintain?
Record what the skill needs, what it produces, where it pauses for approval and what it cannot do. Give it a version number and a change history so you can compare revisions and return to an earlier version. Another person should be able to understand the procedure too.
A reusable skill should make its purpose, permissions, and expected output clear before you install it. Review the source and test it on harmless inputs. Start with the setup and approval guides in this library if those boundaries are not yet written down.
Do I need to write code to build an agent skill?
No. The main instructions are plain text with a short settings block. You can describe the inputs, steps, stopping points and expected result without writing code. Have a technical reviewer check any scripts you add.
Is an agent skill the same thing as an MCP server?
No. An MCP server connects tools or services to the agent. A skill explains when and how to use available capabilities for a particular task.
How long should a SKILL.md file be?
Keep the main procedure short enough to follow. Put detailed reference material in separate files, and check the current authoring limits for the agent software you use.
Put the skill structure to work
Bring a recurring task and the instructions your team already uses. We can help turn those into a bounded workflow with clear inputs, a review checklist, and a result your team can check.