What you need to write an agent skill
All you need is a text editor. An agent skill is just a folder with a SKILL.md file inside. No build tools, no dependencies, no special software. The SKILL.md file has two parts: a YAML frontmatter block (between --- markers) with metadata, and a Markdown body with the actual instructions for the agent.
Step 1 — Create the skill folder
Create a folder inside your project's .claude/skills/ directory (or the equivalent for your platform). Name it after your skill using lowercase-hyphenated naming: my-skill-name/. Inside that folder, create a SKILL.md file. That's it — the folder name becomes the skill's identifier.
Step 2 — Write the YAML frontmatter
Open SKILL.md and add the frontmatter block at the top. At minimum you need name and description. The description is the most important field — it's the only thing loaded at startup, so make it specific and actionable. Bad: 'Helps with React'. Good: 'Enforces functional components, custom hooks patterns, and memoization rules for React codebases.' Keep it under 150 characters.
Step 3 — Write the instruction body
After the closing --- of the frontmatter, write your instructions in plain Markdown. Be direct and imperative: 'Always use...', 'Never do...', 'When you see X, do Y'. Use headings to organize rules by topic. Include examples with code blocks where the rule might be ambiguous. The body is loaded only when the skill is activated, so you can be thorough — aim for 200-800 words.
Step 4 — Test in Claude Code
Open your project in Claude Code. Type /skills in the chat to see if your skill appears in the list. If it shows up, activate it by name and give Claude a task related to the skill. Check whether Claude follows the rules you defined. Iterate on the instructions until the behavior matches your expectations.
Step 5 — Publish to GitHub
Create a GitHub repository named agent-skill-[your-skill-name]. Copy your skill folder into the repo root. Add a README that explains what the skill does and which platforms it supports. Tag the repo with the topic agent-skills so it's discoverable. Then submit it to agentskills.my/submit for inclusion in the community directory.