Continuing from last time, in the previous article, we introduced what Skills are, why they are important, and how Agents load Skills through progressive disclosure.

However, just knowing these concepts is not enough. To truly understand Skills, the most direct way is to create one yourself.

In this article, we will start from a specific requirement and create a Skill that can actually run, step by step. It will organize messy, unstructured meeting notes into a clear, easy-to-share meeting summary.

After completion, you will have a genuinely usable Skill, not just a SKILL.md example that looks correct.

So, grab a coffee, and let's begin. ☕

First, Define the Use Case

The first step in creating a Skill is not to create a new directory and immediately start writing the description, but to first clarify one question:

What requirement do you actually want this Skill to solve?

If you haven't thought this through clearly, even if the directory structure and instructions are written completely later, it's easy to end up with a set of prompts without a clear purpose.

Before starting, you can ask yourself a few questions:

• What task do I want to automate?
• Does this task include multiple fixed steps?
• Are tools needed during execution? If so, are they built-in tools or tools provided by MCP?
• Do I need to put specific domain knowledge, team conventions, or best practices into the Skill?

At the same time, you can also determine which category of Skill it belongs to, as mentioned in the previous article.

Let's take an example. Suppose our requirement is:

Organize raw meeting notes into a clearly structured summary, extract action items, so that anyone on the team can follow up. It belongs to the first category of Skill—Document & Asset Creation, because the ultimate goal is to generate a document.

These questions seem simple, but they can help us define the boundaries of the workflow before actually writing the files.

How to Determine if This Skill is Successful

After defining the use case, the next step is to define success criteria.

Of course, you also need to confirm that the Skill's goal itself is achievable. You probably can't write a Skill and expect it to solve Goldbach's conjecture—that's not realistic. Of course, I'm wording this carefully: I said "probably not," because who knows, maybe it will be possible in the future?

This is a very important step in the whole process. Because without criteria, we can only judge by feeling whether a Skill "seems usable," without knowing if it can work stably.

Success criteria can generally be divided into two categories.

Quantitative Metrics

Quantitative metrics describe results with measurable numbers, for example:

• Out of 10 relevant requests, at least 9 can be triggered correctly;
• Able to complete all steps in the workflow without missing any one step.

Qualitative Metrics

Qualitative metrics focus on the actual behavior exhibited by the Skill, for example:

• Generates structured results every time;
• Does not fabricate information that does not exist in the original notes.

For this meeting notes Skill, we can write the success criteria more specifically:

Quantitative Metrics:
Given a fixed host, model version, and set of available Skills, out of at least 10 messages containing raw meeting notes or expressions like "organize these notes," "clean up my notes," "write meeting minutes," or "summarize the meeting," at least 9 should automatically trigger the Skill without the user needing to actively say the Skill's name.

Qualitative Metrics:
A first-time user only needs to paste a chunk of messy meeting notes to get a summary that can be sent directly to the team without further modification; it must not contain fabricated information, and every action item must indicate the person responsible; if uncertain, it must be clearly marked as "Unassigned."

These metrics won't be immediately useful right now. In the third article, we will use them to test the Skill and confirm whether it truly works as expected.

Once the use case and success criteria are defined, you can start creating the Skill. However, before writing the specific content, let's first look at its directory structure.

Skill Directory Structure

The final directory roughly looks like this:

meeting-notes-formatter/
├── SKILL.md
├── references/
│   └── formatting-rules.md
└── assets/
    └── meeting-template.md

Among these, only SKILL.md is a required file. references/, scripts/, and assets/ are optional directories added as needed.

SKILL.md: The Core of the Skill

Most Skills only need a SKILL.md to work. Other files and directories are mainly used to hold more detailed materials, scripts, and templates.

Therefore, whether SKILL.md is written correctly is very important. The Agent relies on it to determine:

• When this Skill should be used;
• What tasks this Skill can complete;
• What steps should be followed after it is triggered.

A SKILL.md usually consists of two parts:

• Frontmatter: A short piece of YAML metadata at the top of the file, wrapped with ---;
• Instruction Body: The Markdown content below the Frontmatter, defining the actual workflow.

---
name: your-skill-name
description: Explains what this Skill can do and under what circumstances it should be used.
---

# Skill Name

From here on, the content below is the specific instructions...

The Agent typically first sees the Skill's name and description, using them to determine if the current task matches. Only after confirming that this Skill is needed will it continue to read the full instruction body.

This is also why the Frontmatter, although short, directly affects whether the Skill can be correctly discovered and triggered.

Let's start with it below.

Frontmatter: The First Part the Agent Sees

Frontmatter is the YAML metadata at the top of SKILL.md. For a minimal Skill, it needs to include at least name and description:

---
name: your-skill-name
description: Explains what it can do and for which user requests it should be used.
---

The field requirements are as follows:

description: Increasing the Probability of Correct Triggering

What exactly is the role of description?

It is a piece of metadata for discovering and routing Skills. The Agent does not need to load all the complete instructions first; just by looking at this short description, it can determine whether the current request should use this Skill.

A relatively complete description usually contains three parts:

[What it can do] + [When to use it] + [What key capabilities it includes]

All three parts should be as clear as possible. Compare the following writing styles:

# ✅ Better: Explains what it can do, when to use it, and what capabilities it includes
description: Organizes rough requirements into Agile User Stories ready for a Sprint. Use when users need to write, refine, split, or validate User Stories before Sprint Planning. Includes acceptance criteria, INVEST checks, edge cases, dependencies, subtasks, and output ready to be written directly into Jira.

# ❌ Too vague
description: Helps with Agile.

# ❌ Only says what it can do, doesn't explain when to use it
description: Creates User Stories with acceptance criteria and subtasks.

# ❌ Includes unnecessary XML tags in the description
description: <skill>Creates User Stories and acceptance criteria</skill>

Here is a very practical judgment method:

If you can't imagine what input a user would type to trigger this Skill, then the Agent will usually also have difficulty judging accurately.

The description should remain concise while using expressions that real users might say. Don't pile up technical jargon that only the Skill author would use.

If you wish to be compatible with the Agent Skills open specification, you also need to pay attention to constraints like field length. For example, description should not exceed 1024 characters; name should use 1 to 64 lowercase letters, numbers, and hyphens, cannot start or end with a hyphen, cannot use two consecutive hyphens, and must match the parent directory name. Different hosts may have additional restrictions; in practice, refer to the target Agent's documentation.

For our meeting notes Skill, the Frontmatter can be written like this:

---
name: meeting-notes-formatter
description: Organizes raw meeting notes into a clearly structured summary, including attendees, key decisions, action items, and next steps. Use when users paste messy meeting notes or request "organize meeting notes," "clean up these notes," "write meeting minutes," "summarize the meeting."
---

After defining the description, the next step is to write the actual execution instructions.

Instruction Body: What to Do After the Skill is Triggered

The content after the Frontmatter is all regular Markdown. Here, we need to tell the Agent: after the Skill is triggered, exactly how should it complete the task.

It can be organized according to the following structure:

---
name: your-skill
description: [...]
---

# Skill Name

## Steps

### Step 1: [First main step]

## Examples

## Common Issues

When writing instructions, the most important principle is: Specific and executable.

# ❌ Too vague
Validate the data before proceeding.

# ✅ Specific and executable
Run `python scripts/validate.py --input {filename}` to check the data.
If validation fails, common issues include:

- Missing required fields: Add the corresponding fields in the CSV;
- Invalid date format: Uniformly use YYYY-MM-DD.

Vague requirements easily lead to inconsistent results; clear, executable steps are more likely to be repeated stably.

Another point that is easily overlooked: The most important instructions should be placed at the front, not hidden at the bottom of the file.

If a certain validation step or necessary check is critical, the Agent should see it as early as possible.

Now, apply these principles to the meeting notes Skill. The complete instruction body is as follows:

# Meeting Notes Formatter

Organizes rough, unstructured meeting notes into a clear, easy-to-share meeting summary.

## Steps

### Step 1: Read the Raw Notes

Identify the meeting purpose, attendees, and the approximate date mentioned in the notes.

### Step 2: Extract Four Types of Core Information

Extract the following content:

- **Decisions Made:** What was finalized in the meeting;
- **Action Items:** Who is responsible for what task, and when it needs to be completed;
- **Open Questions:** What issues still have no conclusion;
- **Key Discussion Points:** What context is worth preserving.

If a certain type of information is not in the raw notes, keep the corresponding section but do not fabricate content.

### Step 3: Apply Formatting Rules

Before generating the result, read `references/formatting-rules.md` to confirm:

- Section order;
- How to handle missing information;
- Format for action items;
- How to handle edge cases.

### Step 4: Fill in the Template

Generate the result strictly according to the structure in `assets/meeting-template.md`, replacing the placeholders in square brackets with content extracted from the meeting notes.

### Step 5: Check Before Submitting

Confirm:

- Every action item has an owner; if it cannot be determined, mark it as "Unassigned";
- No content is fabricated;
- Do not add content unrelated to the meeting, while preserving the decisions made, action items, and necessary context.

## Examples

**User Input:**

> "Discussed product launch with Sarah and Tom. We decided to postpone to March 15th. Sarah will finish the press release by next Friday. Tom needs to talk to legal, but doesn't know when it will be done. We are still discussing whether to include the mobile features in v1."

**Output:**

# Product Launch Planning Meeting

**Attendees:** Sarah, Tom
**Date:** Not specified

## Decisions Made

- Launch date adjusted to March 15th.

## Action Items

- [ ] Sarah—Draft press release (Deadline: next Friday)
- [ ] Tom—Communicate with legal (Deadline: TBD)

## Open Questions

- Should the mobile features be released in v1?

## Common Issues

**Meeting notes are too vague to extract action items.**

Do not guess. Add a note: "No clear action items identified, suggest confirming with attendees."

**Multiple meetings in the same text.**

Ask the user to confirm before splitting, or organize each meeting into separate sections.

Now, the main body of SKILL.md is complete. However, as you can see from the content above, it also references two external files: references/formatting-rules.md and assets/meeting-template.md.

This involves the third layer of Skill content: resource files provided along with the Skill.

Supporting Files

Remember the three-layer structure mentioned in the previous article?

• Frontmatter is the first layer;
• The instruction body of SKILL.md is the second layer;
• Supporting files are the third layer, only read or executed when the workflow truly requires them.

These contents are placed in the Skill's optional directories respectively:

• references/: Stores documents, specifications, guides, and examples. The Agent can read them when the workflow reaches the corresponding step;
• scripts/: Stores executable scripts like Python, Bash, suitable for steps requiring deterministic computation or file processing;
• assets/: Stores templates, fonts, icons, and other resources that need to be used or copied in the output.

There is a very important rule here: Don't just put files into the directory; you must also explicitly tell the Agent in SKILL.md when to use them.

Suppose the directory contains references/style-guide.md, but the instructions never mention this file. You cannot expect the Agent to actively discover and read it.

# ✅ Correct: Explicitly reference in the instructions
Before starting to write, read `references/style-guide.md` to confirm the tone and format specifications.

# ❌ Unreliable: The file exists, but no instruction references it
(The Agent has no explicit reason to read the file in the workflow)

Precisely because these files are not all stuffed into the context at the beginning, even if a Skill contains many supporting materials, it can remain relatively lightweight. The Agent will follow the instructions and look for the corresponding content when needed.

At this point, everything needed to create a Skill is ready.

The Complete Skill Created

We first defined the requirement and success criteria, then established the directory, wrote the Frontmatter, and finally added specific, executable instructions and supporting files.

The complete example can be found in the repository below:

meeting-notes-formatter full source code

Next, there is a practical question: Where should the Skill be placed so the Agent can find it?

The directories used by different Agents may vary. For example:

• Claude Code: Typically uses .claude/skills/;
• OpenAI Codex: Can use .codex/skills/, also compatible with .agents/skills/; for example, placing a general Skill in ~/.agents/skills/ makes it recognizable by the current Codex environment. The specific discovery scope and priority may still vary with Codex versions and runtime environments, so refer to the current official documentation;
• Trae: Currently can use .trae/skills/ and ~/.trae-cn/skills/.

Additionally, some Agent tools may also be compatible with Skill directories from other conventions; but this is not a universal guarantee, and you cannot assume all tools will scan and load other Agents' directories.

If you want the same Skill to be used by multiple Agents, ~/.agents/skills/ is a practical shared location, currently recognizable by Codex. For other Agents, you should still check their respective documentation to confirm whether configuration or linking to that directory is needed.

Of course, even so, there is no installation directory here that unconditionally applies to all Agents. Even if the Skill's file format follows the same open specification, how each host discovers and loads Skills may still differ.

Therefore, the most reliable approach is to check the latest documentation of the target Agent and place the Skill in the location it actually scans.

Making the Skill Actually Run

After placing the Skill directory in a location the target Agent can scan, you can verify if it has been recognized.

For the meeting notes example, you can paste a chunk of messy meeting notes or type "organize these notes." If the description correctly matches the request, the Agent should load SKILL.md, execute according to the steps within, and generate a result similar in structure to the example.

If it doesn't trigger, you can check the following aspects:

• description is too vague: The Agent cannot determine when it should be used. Add more specific use cases and expressions users might input;
• Name or directory name does not meet requirements: To be compatible with the Agent Skills open specification, name should match the parent directory name, using 1 to 64 lowercase letters, numbers, and hyphens, cannot start or end with a hyphen, cannot use two consecutive hyphens; for example meeting-notes-formatter, not Meeting_Notes_Formatter;
• Incorrect file name: Must be written as SKILL.md, paying attention to case sensitivity;
• Skill placed in the wrong directory: Check the target Agent's documentation to confirm the location it actually scans;
• Agent hasn't recognized the change yet: Reload or restart the session according to the target Agent's documentation and try again.

Once this step is successful, the Skill truly transforms from a file into a workflow that the Agent can discover and use.

Next Article: Testing the Skill

Now, we have a Skill that can run.

But will it trigger when it should, and can it remain quiet on unrelated requests? Faced with different inputs, can it consistently generate structurally consistent and content-reliable results?

These questions are exactly what the next article will address.

Next, we will discuss:

• Testing: Measuring trigger accuracy, handling edge cases, checking output consistency, confirming the Skill doesn't just succeed occasionally but can consistently work as expected;
• Expansion: Sharing, version management, team deployment, and how to avoid common pitfalls.

The hardest part of creating a Skill is already done.

In the next article, let's confirm if it is reliable enough.