How to Write the Perfect SKILL.md for AI Context [2026]
Stop letting AI agents guess your architecture. Learn how to write the perfect `SKILL.md` file to instantly make your GitHub repository "Agent-Ready."
Quick Answer
A perfect SKILL.md relies on the XML-based "opencode" standard. It must include three exact sections: <context> (what the app is), <architecture> (where files go), and <rules> (what the AI is forbidden strictly from doing). Place this file in your root directory, and agents like Claude Code will automatically ingest it before writing code.
README.md vs SKILL.md
Historically, we threw all instructions into the README.md or CONTRIBUTING.md. But LLMs process information differently than humans.
- Humans need narrative, setup commands, and screenshots (README).
- AI Agents need strict logical boundaries, negative constraints, and XML-structured data (SKILL.md).
The Anatomy of a Perfect SKILL.md
In 2026, the community coalesced around the opencode standard for making repositories agent-ready. Here is the exact template you should copy into the root of your project:
--- name: Core Project Directives description: The absolute source of truth for AI agents modifying this codebase. --- <context> This is a B2B SaaS application built for the Model Context Protocol ecosystem. The backend handles heavy WebSockets, while the frontend is a static Next.js export. </context> <architecture> - Frontend: `src/app/` (Next.js 14, standard App Router) - Components: `src/components/ui/` (shadcn/ui exclusively) - State: `src/store/` (Zustand, NO Redux) </architecture> <rules> 1. STRICT: You MUST use 'lucide-react' for all icons. Do not import SVG files directly. 2. STRICT: Never use standard 'fetch'. Always use our custom wrapper in 'src/lib/api.ts'. 3. WARNING: Do not modify the database schema without notifying the user first. </rules>
Best Practices for AI Consumption
Use XML Tags
LLMs (especially Claude 3.5+ generation models) are heavily trained on XML tags during RLHF. Using <rules> instead of markdown headers (## Rules) provides a stronger boundary for the AI's attention mechanism.
Negative Constraints
AI models are eager to please and will often hallucinate dependencies just to fulfill your request. Writing "NEVER use X" is often more effective than writing "ALWAYS use Y".
Frequently Asked Questions
Is SKILL.md supported by GitHub?
Yes, as the agentic coding movement exploded, GitHub Copilot, Claude Code, and standalone tools like Antigravity all adopted SKILL.md as the primary target for repository-level system prompts.
Can I have multiple skill files?
Yes. While SKILL.md acts as the global root directive, larger monorepos will have local .mdc files (Markdown Components) nested inside specific directories (like /frontend/.cursor/rules/) that only activate when those specific files are edited.
Start Writing Your SKILL.md
Don't have time to write one from scratch? Browse our directory of verified Agent Skills to find the perfect template for your stack.