Coding Agents

Claude skill generator and SKILL.md validator

Q: Are skills the same as slash commands in Claude Code?

Custom commands have been merged into skills. A file at .claude/commands/deploy.md and a skill at .claude/skills/deploy/SKILL.md both create /deploy. Skills add a folder for supporting files; for a single prompt with no files, the slash command builder writes the command file. Set disable-model-invocation: true for a command only you should run, such as a deploy.

Create a Claude skill in a few minutes: fill in a form or start from a template, then download the SKILL.md and its folder as a ZIP. Or paste a SKILL.md, or choose a skill folder, to check it against Anthropic’s rules. It’s free and runs in your browser.

Start from a template

Conventions Claude applies whenever they’re relevant. Switching template replaces the form.

Where it will runClaude CodeEvery Claude Code field: invocation control, arguments, subagents, hooks.Portable (claude.ai, API, other agents)Only the six Agent Skills fields, which claude.ai uploads and the Skills API accept.

Name

Lower-case letters, numbers and hyphens, up to 64 characters. It becomes the folder name and the /command.

Description

151 / 1,024

What the skill does, then when to use it: Claude decides from this text whether to load the skill.

When to use (optional)

Extra trigger phrases or example requests. Claude Code appends this to the description.

Who can run itYou and ClaudeType /name, or Claude loads it when a request matches the description.Only youdisable-model-invocation: true. For actions with side effects, such as deploys.Only Claudeuser-invocable: false. Background knowledge, hidden from the / menu.

Argument hint

Shown in the / menu, e.g. [issue-number].

Model

Effort

Only for paths (optional)

Globs, comma-separated, e.g. src/**/*.ts.

Run in a subagentcontext: fork. The skill becomes the subagent’s task; it doesn’t see your conversation.

Pre-approved tools (optional)

Space-separated, e.g. Bash(git add *) Read. Approved for the turn that runs the skill; nothing is blocked.

Licence (optional)

Compatibility (optional)

Up to 500 characters, e.g. Requires git.

Foldersreferences/Long docs Claude reads only when neededscripts/Code Claude runs; only its output uses contextassets/Templates and static files

Instructions

Markdown. $ARGUMENTS, $0, $1 take what follows /name.

Install location

Loads in sessions in this repository. Commit it so your team gets it too. Unzip into .claude/skills/.

api-conventions/
└── SKILL.md

SKILL.md

---
name: api-conventions
description: "API design conventions for this codebase: REST naming, error format and request validation. Use when writing, reviewing or changing HTTP API endpoints."
---

# API conventions

When writing or changing an endpoint:

- Name resources with plural nouns: `/orders`, `/orders/{id}`.
- Return errors as `{ "error": { "code": "…", "message": "…" } }` with a matching HTTP status.
- Validate the request body before any database call and return 422 with the failing field.
- Add or update the endpoint’s test in the same change.

Checks

No problems found: the frontmatter, name and description follow the rules for this target.

Run it with /api-conventions, or Claude loads it when a request matches the description.

Everything stays in your browser. Your draft is saved on this device.

Steps

How to use the claude skill generator and SKILL.md validator

Choose where the skill will run: Claude Code, or portable for claude.ai, the API and other agents.
Pick a template, then edit the name, the description (what it does and when to use it) and the instructions.
Add references/, scripts/ or assets/ if the skill needs them, and fix anything the checks flag.
Download the ZIP and unzip it into .claude/skills/ or ~/.claude/skills/, or upload it to claude.ai.
To check an existing skill, open the Validate tab and choose its folder, a ZIP, or paste the SKILL.md.

Method

How it works

A skill is a folder with a SKILL.md file: YAML frontmatter that tells Claude what the skill is for, then Markdown instructions. Skills follow the open Agent Skills format, so the same folder works in Claude Code, claude.ai, the Claude API and other agents that adopt the standard, as long as you stay within the shared fields.

How skills load

Skills use progressive disclosure. At startup only each skill’s name and description are in context, roughly a hundred tokens each by the spec’s estimate. When a request matches a description, Claude reads the whole SKILL.md. Files in the folder load only when the instructions send Claude to them, and scripts run without their code entering the context; only their output does. That is why a skill can carry long reference material at almost no cost until it’s needed, and why the description matters most: it is the only part Claude sees when deciding.

Writing a description that triggers

Say what and when. “Extracts text and tables from PDF files. Use when the user mentions PDFs or forms” works; “Helps with documents” doesn’t.
Use the words users say. File types, tool names and typical requests.
Write in the third person. The description goes into the system prompt, so “Processes Excel files”, not “I can help you…”.
Put the main use case first. Claude Code trims long descriptions in its skill listing.

Claude Code versus claude.ai and the API

Claude Code accepts every field in the table below and ignores ones it doesn’t recognise, without an error. In Claude Code the name is optional, the folder name becomes the command, and a skill can run in a subagent, take arguments, pre-approve tools or run shell commands with !`command` before Claude reads it. claude.ai uploads and the Skills API accept only the six Agent Skills fields and reject the upload otherwise. On the API, skills run in a sandbox with no network access and no package installs. Skills uploaded to claude.ai and to the API don’t appear on each other; Claude Code downloads your claude.ai skills only when you sign in with that account.

Where Claude Code finds skills

Project skills live in .claude/skills/<name>/SKILL.md and load for everyone working in the repository. Personal skills live in ~/.claude/skills/ and load in all your projects on one machine. Plugins carry skills too, namespaced as /plugin:skill. When names clash, an enterprise skill beats a personal one, and a personal one beats a project one; a skill also wins over a legacy command file with the same name.

What the validator checks

It reads the frontmatter the way Claude Code does (the opening --- must be the first line), parses the YAML (for Claude Code, retrying as it does with unquoted values such as one containing “: ”), and applies the name, description and field rules for the target you choose. Errors are what makes an upload fail or a skill not load; warnings are what Claude Code accepts but other tools don’t, or what is likely a mistake, such as a misspelt field. With a folder or ZIP it also checks that every file SKILL.md links to exists, with matching case. We set Claude Code’s severities by running its own validator, claude plugin validate in version 2.1.296, on test skills. The description hints are heuristics, not rules.

Everything happens in your browser. Nothing you paste or upload is sent anywhere.

Examples

Worked examples

.claude/skills/deploy/SKILL.md (manual-task template)

---
name: deploy
description: "Deploys the application: runs the tests, builds and pushes to the chosen environment. Use when the user asks to deploy or ship a release."
argument-hint: "[environment]"
disable-model-invocation: true
allowed-tools: Bash(npm test *) Bash(npm run build *)
---

Deploy to $ARGUMENTS (default: staging).

1. Run `npm test`. Stop and report if anything fails.
2. Run `npm run build`.
3. Push to the deployment target for that environment.
4. Check the deployment responded, then report the URL and the commit deployed.

Typing /deploy production replaces $ARGUMENTS with “production”. disable-model-invocation: true stops Claude from deploying on its own and keeps the description out of context. The description is quoted because it contains a colon followed by a space, which YAML would otherwise misread.

Frontmatter fields by surface (checked 2026-10-13)
Field	Claude Code	claude.ai upload and Skills API
name	Optional; defaults to the folder name	Required: lower-case letters, numbers, hyphens, up to 64 characters
description	Recommended; listing cut at 1,536 characters with when_to_use	Required, up to 1,024 characters, no XML tags
license, compatibility, metadata	Accepted, not acted on	Accepted; compatibility up to 500 characters
allowed-tools	Pre-approves tools for the turn that runs the skill	Accepted; experimental in the spec
when_to_use, argument-hint, arguments	Supported	Upload fails
disable-model-invocation, user-invocable	Supported	Upload fails
context: fork, agent, background	Runs the skill in a subagent	Upload fails
model, effort, paths, hooks, shell, disallowed-tools	Supported	Upload fails

FAQ

Frequently asked questions

How do I create a Claude skill?

Make a folder named after the skill and put a SKILL.md file in it. The file starts with YAML frontmatter between --- lines, holding at least a name and a description, followed by Markdown instructions. For Claude Code, put the folder in .claude/skills/ in your project or ~/.claude/skills/ for every project. For claude.ai, zip the folder and upload it.

What are the rules for a skill name?

For claude.ai, the Claude API and the open Agent Skills spec, the name is required: at most 64 characters, only lower-case letters, numbers and hyphens, no leading, trailing or double hyphen, and not containing “anthropic” or “claude”. The spec also says it must match the folder name. Claude Code is looser: the name is optional and defaults to the folder name.

How long can a skill description be?

The spec and the platform docs allow 1,024 characters. Claude Code lists the description plus when_to_use up to 1,536 characters and drops the rest, so put the key use case first. The Claude Help Center’s upload guide gives a lower figure of 200 characters for claude.ai, so staying under that is the safe choice for uploads.

How does Claude decide when to use a skill?

At the start of a session Claude sees only each skill’s name and description. When a request matches a description, Claude loads the full SKILL.md, and reads other files in the folder only if the instructions point to them. That is why the description needs both what the skill does and when to use it, with words users would actually say.

Are skills the same as slash commands in Claude Code?

Custom commands have been merged into skills. A file at .claude/commands/deploy.md and a skill at .claude/skills/deploy/SKILL.md both create /deploy. Skills add a folder for supporting files; for a single prompt with no files, the slash command builder writes the command file. Set disable-model-invocation: true for a command only you should run, such as a deploy.

Can I use the same skill in Claude Code, claude.ai and the API?

Yes, if the frontmatter uses only the six Agent Skills fields: name, description, license, compatibility, metadata and allowed-tools. claude.ai uploads and the Skills API reject any other field with an “Unexpected key(s)” error. claude.ai and the API don’t share skills, so upload to each one separately. Claude Code can download the skills enabled on your claude.ai account when you sign in with it (v2.1.273 and later), but it never uploads its own. Choose “Portable” in this tool to check the fields.

How long should SKILL.md be?

Anthropic recommends keeping SKILL.md under 500 lines. Its full text loads when the skill runs and stays in context, so every line costs tokens on later turns. Move long reference material into files under references/ and link them from SKILL.md, one level deep, so Claude reads them only when a task needs them.

Read