Black Friday sale: 30% off Flywrite

Claude Code skills are folders of reusable instructions, each with a SKILL.md file, that Claude Code loads when a task calls for them or when you type the skill's name as a slash command.

What it looks like

A skill is a folder with a SKILL.md file in it. A project skill lives in the project's .claude/skills/ folder:

my-newsletter/
├── .claude/
│   └── skills/
│       └── newsletter-edit/
│           └── SKILL.md
├── CLAUDE.md
└── issues/
    └── issue-42.md

SKILL.md is Markdown with front matter on top. The name matches the folder, and the description says what the skill does and when to use it:

---
name: newsletter-edit
description: Edit a newsletter issue before it goes out.
---

# Pre-send edit

Edit the issue file you're given, in place:

1. Keep the subject line under 50 characters.
2. Cut filler words and points made twice.
3. Keep the issue under 1,200 words.
4. Flag any number or claim that needs a source.
5. List what you changed at the end.

To run it, type the folder's name as a command, with the file after it:

/newsletter-edit issue-42.md

Or ask in plain words, such as "do the pre-send edit on issue 42". Claude Code can load a skill on its own when your request matches its description.

Skills in a writer's work

Make a skill when you keep pasting the same checklist into the chat, or when a section of your CLAUDE.md has turned into a procedure rather than a fact.

CLAUDE.md A skill
When it loads At the start of every session Only when it's used
What goes in it Short standing facts: your voice, which folders to leave alone Procedures and longer reference: an edit pass, a launch checklist

What trips people up:

  • The description decides when Claude picks the skill. Use the words you'd use to ask for the task.
  • Where it lives decides where it works. A personal skill in ~/.claude/skills/ works in every project on your Mac. A project skill in .claude/skills/ works in that project and travels with the folder.
  • Some skills should only run when you ask. Add disable-model-invocation: true to the front matter, and Claude won't start the skill on its own.
  • Edits apply right away. Change a SKILL.md and the running session picks up the new version.
  • Old commands still work. Custom commands were merged into skills, and files in .claude/commands/ keep working.

Agent Skills and other agents

Claude Code skills follow Agent Skills, an open format originally developed by Anthropic. Codex reads skills in the same format, from different folders:

Agent Project skills Personal skills Run one with
Claude Code .claude/skills/ ~/.claude/skills/ /name
Codex .agents/skills/ ~/.agents/skills/ $name, or pick from /skills

Both agents follow a skill folder that's a symlink, so one folder can serve both: keep it in one place and link it into the other. For a skill you share across agents, use only the standard's fields (name, description and a few optional ones), because the extras, such as disable-model-invocation, are Claude Code's own.

In Flywrite

Flywrite has no skills feature of its own. A skill is plain files, so .claude/skills/ and .agents/skills/ show in the file tree with the rest of the project. SKILL.md opens like any draft, and its front matter shows as a card where you edit the name and description in place. Claude Code started in Flywrite's terminal loads your skills as it does anywhere, so you write the skill and run it in the same window. More in Writing with Claude Code.

Questions

What's the difference between a skill and CLAUDE.md?

CLAUDE.md loads at the start of every session, so it holds short standing facts, such as your style rules. A skill's body loads only when it's used, so it holds procedures and longer reference, such as a pre-send checklist.

Do Claude Code skills work in Codex?

Codex reads skills in the same open format, but from .agents/skills folders, not .claude/skills. Keep a shared skill to the standard's fields, and link or copy the folder to where each agent looks.

Sources
  1. Claude Code: Extend Claude with skills. Checked .
  2. Agent Skills: Specification. Checked .
  3. OpenAI: Build skills. Checked .
  4. Claude Code: How Claude remembers your project. Checked .
  5. Flywrite docs: Writing with Claude Code. Checked .

Write with your agent in a writing app.

Buy now