← Writing

A CLAUDE.md file worked until it didn't. Agent Skills are modular folders that tell your agent what to do, what it can touch, and who can trigger it. One format, 30+ tools, three months.

You gave your AI agent a markdown file with rules. CLAUDE.md. GEMINI.md. AGENTS.md.

It worked. Until it didn’t.

One file can’t hold project conventions, deployment workflows, review checklists, and security policies without becoming a wall of text nobody maintains. You needed something modular.

Enter: Agent Skills.

What Are Agent Skills? — cover slide

The Problem

The problem with monolithic instruction files

A single markdown file with all your agent instructions has a natural ceiling. It gets long. It becomes inconsistent. Different workflows conflict. You stop updating it because touching it breaks something else.

The pattern that emerged: separate the instructions by task. Each task gets its own file, its own scope, its own rules.

The Folder

Agent Skills folder structure

A skill is a folder with a SKILL.md file inside:

deploy-staging/
  SKILL.md
  scripts/
  references/

Drop it in .claude/skills/, .github/skills/, or .agents/skills/. Your agent discovers it automatically at startup.

No build step. No registration. No config file to update. A folder.

The Frontmatter

SKILL.md frontmatter anatomy

SKILL.md has two parts: frontmatter and body.

---
name: deploy-staging
description: Deploy current branch to staging
---

## Instructions

Run `npm run build` first, then deploy to the staging environment...

The agent reads name and description at startup to understand what the skill does. When a task matches the description, it loads the full body — markdown instructions, code blocks, rules, anything you need.

The Evolution: From Instructions to Governance

Skills evolve from instructions to governance

Simple skills are just instructions. Complex skills are governance documents.

---
name: deploy-staging
description: Deploy to staging environment
allowed-tools: Bash(git *) Bash(kubectl *)
disable-model-invocation: true
model: sonnet
context: fork
---

What each governance field does

What each field does:

  • allowed-tools — restrict which tools the agent can use when running this skill. This skill can run git and kubectl commands, nothing else.
  • disable-model-invocation — only a human can trigger this skill. The agent can’t auto-invoke it.
  • model — override which model runs this skill. Use a fast model for simple tasks, a more capable one for complex reviews.
  • context: fork — run in an isolated subagent that can’t affect the parent session.

A skill went from “here are some instructions” to a full access control document.

The Standard

One format, 30+ tools, three months

Anthropic published the Agent Skills spec in December 2025. By March 2026, Claude Code, GitHub Copilot, Gemini CLI, and OpenAI Codex all support SKILL.md.

Write a skill once. It works across tools.

Three months from spec to cross-industry adoption is fast. The format converged because the problem was identical across all four ecosystems — everyone needed a way to give agents scoped, modular instructions that scale past a single markdown file.

What’s Next in This Series

The format converged. What diverged is everything else: governance depth, orchestration power, marketplace ecosystems, and what “supported” actually means in practice for each tool.

The next posts in this series cover:

  • #2 — Skills Won. Now What? — where the four tools diverge after adopting the same format
  • #3 — What Are Plugins? — the layer on top of skills: skills + MCP servers + hooks as a distributable unit
  • #4 — State of Plugins — capability and governance comparison across all four tools
  • #5 — MCP Deep Dive — the open protocol, the four different config formats, and the governance gap

The AI Basics #1. LinkedIn post