Claude Code Skill Generator: Build and Check SKILL.md

Target Portable skills work in any tool that follows the Agent Skills spec. Outside Claude Code, extra fields cause an error. NameLowercase letters, numbers and hyphens, up to 64 characters. Must match the folder name. DescriptionWhat it does and when to use it. Claude reads this to decide when to load the skill.

When to use (optional)Extra trigger phrases. Counts toward the 1,536-character listing limit with the description.

Argument hint (optional) Effort (optional) Shell for ! commands

Only activate for these files (optional)Glob patterns, comma separated. Only run when I type /nameSets disable-model-invocation: true, so Claude never loads it on its own. Good for deploys and other actions with side effects. Hide from the / menuSets user-invocable: false. Claude can still use it as background knowledge. Run in a separate subagentSets context: fork, so the skill's work does not fill your main conversation.

Allowed tools (optional)Tools pre-approved while the skill runs, space separated. License (optional) Instructions (the body)Leave it empty to get a template with steps, examples and edge cases. Keep it under 500 lines. Use $ARGUMENTS for whatever is typed after /name.

SKILL.md

Runs in your browser. Nothing you type or upload is sent to our server.

A skill is a folder with a SKILL.md file inside it. The file starts with YAML frontmatter between --- lines, followed by Markdown instructions. Claude Code puts the name and description of each skill in a short listing up front and loads the full body only when the skill is needed. This tool builds that file for you and checks files you already have.

How do I use this tool?

Pick a target: portable (Agent Skills spec fields only, safe for claude.ai uploads and the Skills API) or Claude Code (all Claude Code fields).
Enter a name, such as pdf-processing. It must match the folder name.
Write a description that says what the skill does and when to use it.
Set optional fields, then write the instructions in the body. Leave the body empty to start from a template with steps, examples and edge cases.
Copy or download the file and save it as .claude/skills/<name>/SKILL.md in your project, or ~/.claude/skills/<name>/SKILL.md for all projects.

To validate, switch to the validator tab and paste a full SKILL.md. It checks that the frontmatter starts on the first line, parses as YAML, uses known fields with the right types and stays within length limits.

What are the frontmatter rules?

The Agent Skills specification defines six fields. Claude Code accepts these and adds its own, listed in the Claude Code skills docs.

Field	Required (spec)	Rule
`name`	Yes	1 to 64 characters. Lowercase letters, numbers and hyphens only. No hyphen at the start or end, no `--`. Must match the parent folder name.
`description`	Yes	1 to 1024 characters. Say what the skill does and when to use it.
`license`	No	A license name or a bundled license file.
`compatibility`	No	1 to 500 characters. Environment needs, such as required packages.
`metadata`	No	A map of string keys to string values.
`allowed-tools`	No	Space-separated list of pre-approved tools. Marked experimental.

In Claude Code, every field is optional: name defaults to the folder name and description defaults to the first line of the body. Claude Code adds fields such as when_to_use, disable-model-invocation, user-invocable, argument-hint, arguments, model, effort, context, agent, paths, hooks and shell. Unknown field names are ignored in Claude Code, but outside it (claude.ai uploads, the Skills API) only the six spec fields are allowed and any other key causes a hard error. The validator flags this.

How long can the description be?

The spec caps description at 1024 characters. Claude Code also truncates the combined description and when_to_use text at 1,536 characters in the skill listing by default (the skillListingMaxDescChars setting changes this). If you have many skills, Claude Code can drop some descriptions to fit the listing budget, so put the most important trigger words first.

Worked example

---
name: changelog-writer
description: Writes a changelog entry from the staged git diff. Use when the user asks for release notes, a changelog line or a summary of changes.
license: MIT
metadata:
  author: example-team
  version: "1.0"
---

## Steps
1. Read the staged diff.
2. Group changes into Added, Changed and Fixed.
3. Write one line per change in plain English.

## Edge cases
- If nothing is staged, say so and stop.

This file passes both the portable and Claude Code checks. Save it in a folder named changelog-writer.

What are the common mistakes?

Name does not match the folder. The spec requires them to match.
Capital letters or underscores in the name. PDF_Tools fails; pdf-tools passes.
A vague description. “Helps with PDFs” gives Claude nothing to match on. Name the tasks and the words users say.
Frontmatter not on line one. The opening --- must be the first line of the file.
Unquoted version numbers in metadata. Write version: "1.0" so it stays a string.
Claude Code fields in a portable skill. Fields like context or paths break uploads to claude.ai.

Tips

Keep SKILL.md under 500 lines and move long reference material into files under references/, linked with relative paths one level deep.
Use disable-model-invocation: true for actions with side effects, such as deploys, so only you can start them.
Use $ARGUMENTS in the body to receive text typed after /skill-name.
Check the result with the official skills-ref validate ./my-skill command before you share it.

For a longer walkthrough, read our guide to Claude Code skills and the basics in what is Claude Code. If you need custom skills built for your team, see our AI automation service.

Last updated: October 19, 2026

Questions, answered

Questions about the SKILL.md Generator & Validator.

Still unsure? Ask the developer directly on a free 30-minute call.

Book a free consultation

What is a SKILL.md file?

It is the main file of an agent skill. It has YAML frontmatter with at least a name and description, followed by Markdown instructions that Claude loads when the skill is needed.

What are the rules for a skill name?

Under the Agent Skills spec the name must be 1 to 64 characters of lowercase letters, numbers and hyphens. It cannot start or end with a hyphen, cannot contain two hyphens in a row and must match the folder name.

How long can a skill description be?

The spec allows 1 to 1024 characters. By default Claude Code also cuts the combined description and when_to_use text at 1,536 characters in the skill listing.

Where do I save a Claude Code skill?

Save it as .claude/skills/skill-name/SKILL.md in your project, or ~/.claude/skills/skill-name/SKILL.md to use it in every project.

Which frontmatter fields work outside Claude Code?

Only name, description, license, compatibility, metadata and allowed-tools. Any other key causes an error on claude.ai uploads and the Skills API.

How long should a SKILL.md file be?

Both the spec and the Claude Code docs say to keep it under 500 lines. Move detailed reference material into separate files in the skill folder.

How do I stop Claude from running a skill on its own?

Add disable-model-invocation: true to the frontmatter. The skill then runs only when you type its slash command.

Is name required in Claude Code?

No. Claude Code uses the folder name when name is missing. The Agent Skills spec does require it, so include it if you plan to share the skill.

See all free tools

Your developer Jamshaid Ali Founder, Handicraft Marketing

Need a tool like this built for your business?

We build fast WordPress sites, custom calculators and software that run your daily work. Tell us what you need and get a clear plan within 24 hours.

Book Free Consultation Chat on WhatsApp (+92 306 9626307)

Reply within 24 hours
Free plan, no obligation
Talk directly to the developer

Claude Code skill generator and SKILL.md validator