What Are Agent Skills? SKILL.md Guide for Claude, ChatGPT & More

Agent Skills are folders with a SKILL.md file — YAML frontmatter plus Markdown instructions — that teach coding agents a repeatable procedure. The same skill format works across Claude, ChatGPT / Codex, Cursor, Gemini, Kimi, GLM, and other agents that follow the open Agent Skills standard. For design work, skills encode taste, layout rules, and anti-slop constraints so first drafts stop looking generic.

What is an Agent Skill?

An Agent Skill is procedural knowledge packaged for an AI agent. Instead of pasting the same long prompt every session, you install a skill once. The agent reads the skill's description to decide when it applies, then follows the body when it activates.

A minimal skill looks like this:

---
name: tasteful-landing
description: Use when building marketing or landing page UI. Enforces layout, type, and anti-slop rules.
---

# Tasteful landing

1. Read DESIGN.md first if present.
2. Build one section per request.
3. Never use purple gradients, Inter-by-default, or three identical feature cards.

That package travels. Put it in the right skills folder and Claude Code, Cursor Agent, Codex, ChatGPT coding sessions, Kimi, GLM, or Gemini CLI can load the same instructions.

Agent Skills vs prompts vs rules vs MCP

Layer	What it is	Best for
Prompt	One-shot instruction in chat	A single task
Rules / AGENTS.md	Always-on project preferences	Repo-wide defaults
Agent Skill (SKILL.md)	On-demand procedure with trigger description	Repeatable workflows
MCP	Tools and data connections	Fetching APIs, browsers, DBs
DESIGN.md + templates	Visual system the skill can require	Taste and layout constraints

Skills explain how to work. MCP gives the agent tools. Templates and DESIGN.md from the Agent's Design gallery give the agent visual truth. Use all three when you care about shippable UI.

Why skills matter for UI and vibe coding

LLMs — whether Claude, ChatGPT, Kimi, GLM, or Gemini — default to the median UI on the internet. Freehand prompts rarely encode spacing rhythm, type scale, or banned patterns. A design skill forces the agent to load those constraints before writing JSX.

Typical failure without a skill:

• Purple-to-indigo heroes
• Inter everywhere
• Card grids with icon-in-circle rows
• Marketing fluff headlines

Typical gain with a design skill + template:

• Section-scoped builds
• Explicit anti-patterns
• Tokens and layout rules that survive model switches

Browse live before/after demos in the Skills directory — same prompt, with and without the skill.

SKILL.md anatomy (what agents actually read)

Required frontmatter

• name — kebab-case id; usually matches the folder name
• description — when to activate; this is the retrieval key

Write descriptions like search queries the agent would match: "Use when designing landing pages," "Use when auditing accessibility," "Use when rewriting typography."

Body

Markdown steps, checklists, examples, and links to references/ or scripts/. Keep the body scannable. Agents follow lists better than essays.

Optional extras

• scripts/ — runnable helpers the agent can execute
• references/ — deep docs loaded only when needed
• assets/ — templates, fixtures, images
• Platform fields such as disable-model-invocation (manual /skill-name only)

Where skills live by tool

Exact paths vary by product, but the pattern is consistent:

Agent / surface	Typical project path	Typical user path
Claude Code	.claude/skills/	~/.claude/skills/
Cursor	.cursor/skills/ (also loads Claude/Codex dirs)	—
ChatGPT / Codex	.agents/skills/ or .codex/skills/	~/.agents/skills/
Gemini CLI	.gemini/skills/	~/.gemini/skills/
Kimi / GLM / other CLIs	Tool-specific skills dir or shared Agent Skills path	Check vendor docs

If your stack mixes Claude for planning and Cursor Composer for edits, keep skills in a path Cursor already discovers — or symlink — so both surfaces see the same taste rules.

Progressive disclosure (why skills stay cheap)

Agents do not dump every skill body into context on every message. They typically:

1. Index skill names + descriptions at session start
2. Match your request to relevant descriptions
3. Load full SKILL.md bodies only for matches

That is why a sharp description matters more than a poetic title. Vague descriptions never fire; overbroad ones fire too often.

Design skills vs general coding skills

Not every skill is about UI. Categories that matter for product teams:

• Taste / craft — anti-slop, layout judgment, typography
• Systems — design tokens, component architecture
• Motion — animation rules and performance budgets
• Accessibility — WCAG checks and remediation
• Framework — Next.js, Vue, SwiftUI conventions
• Marketing / content — copy, SEO, launch workflows

Agent's Design focuses on the design-facing set. Pair a taste skill with a gallery template and a DESIGN.md so Claude, ChatGPT, Kimi, or GLM are not inventing a brand from scratch.

How to evaluate a design skill before you install it

1. Trigger clarity — Would you know when to use it from the description alone?
2. Concrete bans — Does it forbid specific slop patterns, or only say "be beautiful"?
3. Model-agnostic steps — Works on Claude and ChatGPT and Cursor, not one vendor API
4. Demo proof — Prefer skills with before/after UI (/skills shows this)
5. Complement, don't replace — Skills should call for DESIGN.md / templates, not invent tokens every run

Common mistakes

• Treating skills as magic model upgrades — Claude Opus and GPT-class ChatGPT models still need constraints
• Installing twenty overlapping taste skills — they fight; pick one primary craft skill
• Writing descriptions like feature marketing — agents need "when to use," not slogans
• Skipping DESIGN.md — skills without visual specs still regress to median UI
• Assuming Kimi or GLM will "just know design" — open models follow the same skill files; they do not invent taste

Start here

1. Read this hub, then the install guide
2. Browse design agent skills with live demos
3. Pick a gallery template and drop its DESIGN.md into the repo
4. Run the same landing prompt in Claude, Cursor, or ChatGPT — with the skill on

Agent Skills are the portable craft layer. Models change. Your SKILL.md should not.