Write a SKILL.md
How to Write a SKILL.md That an Agent Can Actually Use
A good SKILL.md is not a long README. It is a triggerable workflow contract. The agent should know when to use it, what steps matter, what sources to trust, and where the boundaries are without re-deriving the process every time.
The fastest way to get there is to study a few strong authoring-oriented skills, then write the smallest version that captures one repeatable job cleanly. If the file tries to solve everything, it becomes documentation instead of a working skill.
Install
See how Claude Code skills are installed
Start here if you need the packaging and install context before you decide how your own skill should be structured.
Claude
See the strongest Claude Code skill examples
Use these as models when you want examples of concise triggers, workflow steps, and supporting references.
Codex
See the strongest Codex skill examples
Useful when your SKILL.md needs to fit terminal-driven engineering workflows and composable tool usage.
What a strong SKILL.md needs
The file should make the trigger conditions obvious, define the workflow steps in the order that matters, and point to the references or tools the agent should use instead of relying on vague “best practices” language.
What to avoid
Do not turn SKILL.md into a generic essay. If the file does not help the agent choose the skill and execute a concrete workflow faster, it is probably just background documentation wearing the wrong label.
Curated Listings
Pages worth studying before you author a SKILL.md
These pages are good references for skill creation, migration, and packaging across the current agent ecosystems.
Claude
Skill Creator
A direct guide for creating, refining, and measuring skills when the goal is to formalize a repeated workflow cleanly.
Codex
Skill Creator
The Codex-focused version of skill authoring guidance when your target environment is terminal-first and instruction-heavy.
Packaging
Plugin Creator
Useful when your reusable capability needs plugin packaging or a broader local bundle around the skill itself.
Migration
Migrate to Codex
Helpful when you are translating existing instruction files, skills, or agent workflows into Codex-friendly local structure.
Discovery
Find Skills
Worth reviewing so you can benchmark whether your idea should become a new skill or whether a close match already exists.
Related Hubs
Keep drilling down by ecosystem or use case
These related hubs connect the broad search term to the next page that usually narrows the decision cleanly.
Install Claude Code Skills
How to Install Claude Code Skills Without Turning the Setup Into a Mess
Learn how to install Claude Code skills and choose a sensible first set of discovery, testing, frontend, and MCP-oriented skill pages.
Best Claude Code Skills
Best Claude Code Skills for Real Workflows
Browse the best Claude Code skills to start with for testing, MCP servers, frontend work, documentation, and skill authoring.
Best Codex Skills
Best Codex Skills for Builders Who Want Fast Leverage
Browse the best Codex skills for CLI creation, Playwright, PR handling, official docs, deployment, and skill authoring.