Agent Skills Creation Guide: From Directory Structure to SKILL.md

If you have used Claude Code or similar AI coding tools, But not many people have actually created one. Most assume it is an "advanced feature" that is far removed from everyday use.

The essence of a Skill is extremely simple: it is a folder containing a file called SKILL.md. The AI reads this file and knows what scenario it applies to, what steps to follow, and what resources to use.

This article starts from scratch and walks you through the creation methods, directory structure, and the meaning of every file. By the end, you will be able to write your own.

What Problem Do Skills Solve

why do you need Skills?

Every time you use AI for the same type of task — code review, weekly report generation, data cleaning — you repeat the same background information, rules, and output format requirements. Doing it once is fine. Doing it ten times is annoying. And you probably say it differently each time, leading to inconsistent AI output.

Skills fix this by solidifying the repetitive information. Write it once, and the AI loads it automatically whenever the skill is triggered. No need to repeat yourself.

More importantly, Skills can carry scripts, reference documents, and templates. The AI does not just read your instructions — it can actually run your scripts and consult your reference materials. This is far more powerful than relying on prompts alone.

Two Creation Methods

Depending on the complexity of the skill, there are two approaches.

The minimal version covers 90% of use cases. Two steps: first, create a skill folder with a name using only lowercase letters, numbers, and hyphens, like "code-review" or "weekly-report." Second, create a SKILL.md file inside it with the metadata and instructions. Done.

The standard version is for complex skills that need scripts, templates, or reference docs. Six steps: define the scenario and create the root folder, write the SKILL.md core file, create optional directories like scripts, references, and assets as needed, link those resources in SKILL.md, place the skill folder in the .claude/skills directory, then test and iterate.

Note that regardless of which approach you use, SKILL.md is the only required file. Other directories are optional and added as needed.

Standard Directory Structure

The minimal structure is just one file: a my-skill folder containing SKILL.md.

The standard structure looks like this. "my-skill" is the root folder. It contains SKILL.md (required) and three optional directories: scripts for executable scripts (Python, Shell, etc.), references for detailed reference documents (business rules, API documentation), and assets for static resources (templates, images, data files).

All structures follow the Anthropic open-source standard and are supported by tools like Claude Code and Cursor.

SKILL.md Field-by-Field Breakdown

SKILL.md has two parts: YAML front matter (between two sets of three dashes) and Markdown body instructions.

The YAML header is loaded when the AI starts up and determines whether the skill should be triggered. It uses about 100 tokens and does not consume much context.

The first field is "name" — required, the unique skill identifier, matching the root folder name, within 64 characters, using only lowercase letters, numbers, and hyphens.

The second field is "description" — required, describing what the skill does and its trigger conditions, within 1024 characters. This is how the AI decides whether to activate the skill, so make it clear what user requests should trigger it.

The third field is "license" — optional, the open-source license for the skill.

The fourth field is "compatibility" — optional, runtime environment requirements like "Python 3.10 and above."

The fifth field is "metadata" — optional, extended information like author and version number.

The Markdown body is loaded only when the skill is triggered, so keep it under 5000 tokens. There is no mandatory format, but several modules are recommended.

The first module, "When to use," is the most critical. It defines the trigger scenarios and prevents the AI from misjudging. For example: "Use this skill when the user asks to review code, check code quality, or review a PR."

The second module, "Steps," is a step-by-step guide, presented as a numbered list. Write it as simply as possible because the AI will not fill in steps you skip.

The third module, "Output format," standardizes how the AI presents results. For example, use bullet points, symbols for pass/fail items, or a specific template.

The fourth module, "Available resources," links to content in scripts, references, and assets. For example: "Run script: python scripts/check.py."

The fifth module, "Notes," covers edge cases and common mistakes. For example: "Empty catch blocks are not allowed."

What the Three Optional Directories Do

The "scripts" directory holds executable scripts. The AI can run them directly in a virtual environment instead of writing code on the fly, which improves both efficiency and accuracy. Scripts should declare their dependencies, have clear parameter descriptions, and include error handling. For example, a data cleaning script should list its required packages at the top.

The "references" directory holds detailed reference documents. The AI loads them on demand — only when the skill is triggered — saving context. This is ideal for long texts like company code standards or API documentation. Each file should focus on one topic, and files over 100 lines should include a table of contents.

The "assets" directory holds static resources the AI can use directly: document templates, images, data files, and so on. Examples include weekly report templates, brand logos, and CSV lookup tables.

Three-Level Progressive Loading

This is the clever part of the skill system design.

Level one: when the AI starts, it only loads the YAML metadata (name and description) from all skills to determine which ones should trigger.

Level two: only when a skill is triggered does the AI load the SKILL.md body instructions. Untriggered skills are not loaded, consuming no context.

Level three: during execution, the AI reads specific files from scripts, references, and assets on demand. It reads only what it needs and skips the rest.

This means you can install dozens of skills without slowing down the AI. Only the skills actually being used consume resources.

Advanced Tips for Effective Skills

Writing a functional Skill is easy. Writing a great one takes a bit more thought.

Be specific in your trigger conditions. A vague description like "helps with code" will either never trigger or trigger at the wrong times. Write descriptions that match the actual phrases users type. If users say "review my PR" or "check this code for bugs," include those exact phrases in your description.

Keep the body focused. The body instructions should contain only what the AI does not already know. Python syntax, common patterns, general best practices — skip those. Focus on your specific conventions, your project's unique requirements, your personal preferences.

Use the assets directory for examples. When you want consistent output quality, place example outputs in the assets folder and reference them in your instructions. The AI can consult the example before generating its own output, producing more consistent results.

Version your skills. When you share skills with a team, use versioning to track changes. This lets users know when updates are available and whether to adopt them.

Test against edge cases. Before deploying a skill, give it ambiguous inputs and see how it responds. A good skill should handle edge cases gracefully rather than producing nonsense or hallucinated content.

One Core Principle

When writing SKILL.md, remember this: only tell the AI what it does not already know.

You do not need to explain Python syntax, common library usage, or general programming conventions. The AI knows these better than you do.

What you do need to write is your company's internal code conventions, your project's specific directory structure, your personal writing style preferences, your team's business rules — things the AI cannot possibly figure out on its own.

Once you internalize this principle, your Skills become smaller in size but dramatically more effective.

Wrapping Up

Skills are not some advanced concept. They are a structured "instruction manual." But it is exactly this structure that transforms the AI from guessing to following documented procedures.

My own experience: spending 10 minutes creating a Skill saves dozens of rounds of repetitive explanation later. Especially for highly repetitive tasks like code review and weekly report generation, the return on investment is extremely high.

The incremental approach — starting with one skill and building over time — produces better results than trying to create a comprehensive skill library in one session.