Teach Claude your workflow: build an Agent Skill with SKILL.md

Originally published at AI Frontier Post. Every regular Claude user eventually hits the same wall: a workflow they repeat every week - the way they want release notes written, code reviewed, or research briefs formatted - that they have to re-explain in every single session. Paste the checklist again. Correct the format again. Watch the agent improvise the steps you already decided. The knowledge exists, but it lives nowhere the agent can reliably find it. Agent Skills are the industry's answer, and they are having a moment: Anthropic launched them as a Claude feature in October 2025, published the format as an open standard on December 18, 2025 at agentskills.io, and by mid-2026 roughly forty products read the same files - Claude Code, OpenAI's Codex, Cursor, GitHub Copilot, Google's Gemini CLI among them. The whole standard is almost absurdly small: a folder containing a single Markdown file, SKILL.md, with a few lines of YAML metadata on top and instructions below. This tutorial builds one from scratch, end to end. You will pick a workflow worth teaching, write the frontmatter and instructions, validate the result with a real script, and install it so it triggers automatically in your own sessions. No API keys, no servers, no cost - and the skill you build works in every agent that speaks the open standard, not just Claude. What you'll need - A coding agent that supports the open standard - Claude Code is the reference implementation, but the skill you build also loads in OpenAI Codex, Cursor, GitHub Copilot, Gemini CLI, and the rest. claude.ai supports skills too once enabled in settings. - A text editor and Python 3 (for the validation script; pip install pyyaml if you don't have it). - One repeatable workflow of your own - something you have done at least three times and will do again. We will build a changelog writer as the worked example; substitute your own at Step 1. - About 20-30 minutes. No accounts, no API keys, no cost. What a skill actually is Strip away the announcements and a skill is a directory with one required file: changelog-writer/ └── SKILL.md # YAML frontmatter + Markdown instructions The frontmatter - just name and description are required - tells the agent what the skill does and when to use it. The body tells it how: the workflow, the rules, the output contract, the edge cases. Optionally, the folder grows three sub-directories: scripts/ for executable code, references/ for docs loaded on demand, and assets/ for templates and static files. The clever part is progressive disclosure - how the agent loads the skill in three stages instead of all at once: AI-generated illustration: progressive disclosure - metadata always loaded, instructions on trigger, resources on demand. - Metadata (~100 tokens), always loaded. At startup the agent reads only every skill's name anddescription into context. You can have fifty skills installed and barely feel it. - Instructions ( 500: errors.append("SKILL.md exceeds 500 lines") allowed = {"name", "description", "license", "compatibility", "metadata", "allowed-tools"} if unknown := set(fm) - allowed: errors.append(f"unknown frontmatter fields: {unknown}") return errors print(validate_skill("~/.claude/skills/changelog-writer".replace("~", str(Path.home())))) Against our changelog-writer: [] - valid. Against a deliberately broken skill (missing name , 1,100-character description), it reported exactly the two violations: name is required; description length out of range (1-1024) . Validation is not a substitute for testing the behavior - ask the agent to use the skill on a real task and read what comes out - but it catches the structural mistakes that silently prevent loading. One safety note before you go further: a skill is instructions plus, optionally, code that runs with your agent's permissions. Install skills only from sources you trust, and read SKILL.md before installing - the same review you'd give any script before running it. Community marketplaces now list thousands of skills; treat an unknown skill the way you'd treat an unknown npm package. Which approach should you use? Skills overlap with half a dozen other mechanisms. Here's the map, in plain terms: - System prompts / custom instructions: one-off guidance for a conversation. Use a skill when the knowledge should survive the session and follow you across projects. - Projects (static background knowledge): always-loaded context about a repo or domain. Skills are procedural and load dynamically - how to do the thing, not facts about the thing. - MCP servers: they give the agent access - databases, APIs, external services. Skills give it method - how to use those tools well. They compose: a Sentry skill wraps workflow around Sentry's MCP server. - Slash commands: in Claude Code, commands have effectively merged into skills - a skill at .claude/skills/deploy/SKILL.md creates/deploy , and adds auto-triggering on top. - Subagents: runtime isolation - a forked context for a task. The skill says what to do; the subagent provides the room to do it in. Use them together for long, messy jobs. Mental model: MCP is the nervous system, skills are the handbook, projects are the memory, subagents are the work crew. The takeaway A skill is the smallest unit of reusable agent expertise: a folder, a SKILL.md, a name and description that cost ~100 tokens per session. Pick one repeated workflow, write the frontmatter as the trigger contract it is, keep the body to decisions and failure modes, split detail into references, validate the structure, and install it where the team can inherit it. Do that three or four times and your agent stops being a brilliant stranger every morning - it starts being the colleague who already knows how you work. Top comments (0)