What Is a Skill File?
A skill file is a structured Markdown document that encodes a process or workflow so an AI assistant can follow it perfectly — every time, without being reminded. For writers, managers, customer success teams, engineers, and everyone in between.
The Simple Definition
Think of a skill file as a standing instruction card for your AI assistant. When you're writing a difficult email, preparing for a client meeting, reviewing a document, running a retrospective, or onboarding a new team member — the skill file tells the AI exactly how you and your team approach that situation.
Unlike a README or a wiki page, a skill file is machine-readable first. It is formatted so AI agents can parse it, activate it at the right moment, and execute it step-by-step.
In one sentence: A YAML-frontmatter Markdown file with a name, a trigger description, and a structured process body — designed to be invoked by an AI agent.
The Problem They Solve
Every team has processes. The problem is they live in three terrible places:
❌ People's heads
Leaves with them. Unavailable at 3am. Inconsistent across the team.
❌ Wiki pages
Instantly stale. Nobody reads them at the right moment. Not executable.
❌ Slack threads
Impossible to find. No version history. Contradicts older threads.
✅ Skill files
- Live in git — versioned, diffable, with full history
- Invoked automatically by AI agents at exactly the right moment
- Consistent — every agent, every engineer, follows the same process
- Updatable — improve once, every agent benefits immediately
A Real Example
Here's a complete skill file for reviewing pull requests. Notice the YAML frontmatter tells the agent when to use it, the context section explains why, and the process is a clear numbered list with anti-patterns at the end.
--- name: reviewing-pull-request description: Invoke when you are about to review a pull request to ensure nothing is missed. --- # Reviewing a Pull Request ## Context Pull request review is the primary quality gate for every change that enters the codebase. A rushed review misses bugs; an over-engineered review blocks progress. ## Process 1. **Read the PR description** — understand the *why* before reading code. 2. **Verify the branch is up to date** with the base branch. 3. **Review each changed file** looking for: - Missing error handling or uncaught exceptions - Untested edge cases or missing test coverage - Unclear variable / function names - Performance regressions (N+1 queries, unnecessary re-renders) 4. **Leave line comments** for specific issues. 5. **Leave a general comment** if the overall approach is wrong — explain why. 6. **Check CI passes** before approving. 7. **Approve only when all blocking issues are resolved.** ## Anti-Patterns - **Never approve with unresolved blocking comments** — a TODO is not a fix. - **Never leave vague feedback** — explain what to change and why.
How AI Assistants Use Them
Each AI assistant loads skill files differently, but the pattern is universal: read the description to know when to activate, then execute the body when the situation matches.
Ready to create your first skill file?
Use our free, private generator — upload a document, dictate, or paste text. No account, no API key, runs entirely in your browser.