In the first post of this series, we looked at what a skill is. Now we create one.
It’s a Markdown file. No code, no configuration. Just text.
The structure of a SKILL.md
A SKILL.md has two parts: a YAML header and a Markdown body.
my-skill/
└── SKILL.md
The header contains the metadata. Two fields are required: name and description. The rest are optional.
---
name: my-skill-name
description: What the skill does and when to use it.
license: MIT
compatibility: Requires git
metadata:
author: gabriel
version: "1.0"
allowed-tools: Bash(git:*)
---
name must be lowercase with hyphens, maximum 64 characters, and match the folder name.
description is the most important field. It’s what the agent reads to decide whether your skill is relevant.
compatibility specifies environment dependencies, for example Requires Python 3.14+ and uv or Requires git, docker. Most skills don’t need it.
allowed-tools pre-approves tools the skill can use without asking for confirmation each time. Use with caution, especially for shell and bash.
The file body, after the frontmatter, contains your instructions in Markdown. The agent follows them when the skill is activated.
The description is the key
If your skill doesn’t trigger, it’s almost always the description.
The agent doesn’t read your skill content constantly. It only reads the description at startup, then decides whether the skill is relevant based on your request. If the description is too vague, the skill stays inactive.
A good description says what the skill does, and when to use it. It includes the keywords you’ll naturally use in your requests.
Too vague:
description: Helps with plans and ideas.
Effective:
description: Interview the user relentlessly about a plan or design until
reaching shared understanding. Use when asked to stress-test a plan,
review a design, or when user says "grill me".
The second version tells the agent explicitly when to load the skill.
grill-me: the simple example
The SKILL.md for grill-me fits in fifteen lines:
---
name: grill-me
description: Interview the user relentlessly about a plan or design until
reaching shared understanding, resolving each branch of the decision tree.
Use when user wants to stress-test a plan, get grilled on their design,
or mentions "grill me".
---
Interview me relentlessly about every aspect of this plan until we reach
a shared understanding. Walk down each branch of the design tree,
resolving dependencies between decisions one-by-one. For each question,
provide your recommended answer.
Ask the questions one at a time.
If a question can be answered by exploring the codebase, explore the
codebase instead.
Precise description, direct instructions.
github-actions-failure-debugging: the technical example
This skill comes directly from the official GitHub documentation. It relies on external tools, specifically the GitHub MCP Server.
---
name: github-actions-failure-debugging
description: Debug failing GitHub Actions workflows. Use when a workflow
is failing, a build is broken, or when asked to investigate a CI failure.
---
To debug failing GitHub Actions workflows in a pull request, follow this
process, using tools provided from the GitHub MCP Server:
1. Use the `list_workflow_runs` tool to look up recent workflow runs for
the pull request and their status.
2. Use the `summarize_job_log_failures` tool to get an AI summary of the
logs for failed jobs, to understand what went wrong without filling your
context window with thousands of lines of logs.
3. If you still need more information, use the `get_job_logs` or
`get_workflow_run_logs` tool to get the full, detailed failure logs.
4. Try to reproduce the failure yourself in your own environment.
5. Fix the failing build. If you were able to reproduce the failure
yourself, make sure it is fixed before committing your changes.
The skill contains no code. It gives the agent instructions on which tools to use and in what order. The agent does the rest.
For more complex skills, you can add scripts, reference files, or templates in subfolders:
github-actions-failure-debugging/
├── SKILL.md
├── scripts/
│ └── parse-logs.sh
└── references/
└── common-errors.md
The SKILL.md references these files by relative path, and the agent loads them as needed.
Where to put your skills
There are two scopes: per project and personal.
Per project: the skill lives in your repository and follows your code. It’s available to everyone working on the project. Put it in .github/skills/, .claude/skills/, or .agents/skills/ at the root of your repository.
Personal: the skill is available across all your projects. Put it in ~/.copilot/skills/, ~/.claude/skills/, or ~/.agents/skills/ depending on the agent.
grill-me is a good candidate for a personal skill. github-actions-failure-debugging makes more sense at the project level, especially if you want to include references specific to your pipeline.
Platform-specific differences
The standard is shared, but each platform has its quirks.
GitHub Copilot adds two frontmatter fields: user-invocable to control whether the skill appears in the chat / menu, and disable-model-invocation to prevent the agent from loading it automatically. Useful when you want a skill that only triggers if you ask for it explicitly.
OpenAI Codex CLI reads skills from ~/.codex/skills and supports a config.toml file to enable or disable individual skills without deleting them.
ChatGPT supports skills, but they don’t sync yet across OpenAI products. A skill in ChatGPT isn’t automatically available in Codex CLI, and vice versa.
Claude exposes skills via the /v1/skills API with the skills-2025-10-02 header, which lets you manage them programmatically in your own applications.
Where to start
To create your first skill, ask your agent to do it for you. Describe what you want, and it generates the SKILL.md. Just review and adjust the description.
For inspiration, anthropics/skills and github/awesome-copilot contain dozens of concrete examples. The full spec is at agentskills.io.
Happy creating, and if your skill doesn’t trigger, check the description first.
This post was written with AI assistance and edited by me.