Agent Markdown Files: The Complete Guide to SKILL.md, AGENT.md, CLAUDE.md, and More
Master the growing ecosystem of specialized markdown files that control AI agent behavior. Learn about SKILL.md, AGENT.md, MEMORY.md, CLAUDE.md, DESIGN.md, and 10+ other formats used to configure modern AI agents.
In the early days of AI coding assistants (2023-2024), developers provided context to AI through chat messages. Every conversation started from scratch. You'd explain your project structure, coding standards, and architectural decisions over and over again.
By 2026, a new paradigm has emerged: configuration-as-markdown. Specialized .md files now serve as persistent instruction sets, skill definitions, and memory banks for AI agents. These files provide:
Persistent context that survives across sessions
Portable skills that can be shared across teams
Standardized formats that work across multiple AI platforms
Version-controlled instructions that evolve with your project
This guide covers 15+ types of markdown files used in modern AI agent development, their structure, use cases, and best practices.
The Core Standards: SKILL.md and AGENT.md
SKILL.md: The Agent Skills Standard
SKILL.md is the cornerstone of the agentskills.io open standard—a specification for defining reusable AI agent capabilities.
---
name: "api-documentation-generator"
version: "1.0.0"
description: "Generate comprehensive API documentation from OpenAPI specs"
tags: ["documentation", "api", "openapi"]
author: Yash Thakker
license: "MIT"
---# API Documentation Generator
This skill generates human-readable API documentation from OpenAPI/Swagger specifications.
## When to Use This Skill- You have an OpenAPI 3.0+ specification file
You need user-friendly documentation for your API
You want to generate markdown or HTML docs
OpenAPI spec file (JSON or YAML)
Node.js environment (for HTML generation)
Load the OpenAPI spec and validate it against the OpenAPI 3.0 schema.
Extract all endpoints, methods, parameters, request bodies, and responses.
Create structured markdown documentation with:
API overview and base URLs
Authentication methods
Endpoint details with examples
Schema definitions
Error codes
Use the templates in to generate formatted output.
See for the markdown template and
for the HTML version.
OpenAPI 3.0 Specification: []()
Examples: See
Run to validate against sample OpenAPI specs in .
Does not support OpenAPI 2.0 (Swagger)
Webhooks are not documented
Custom vendor extensions are ignored
---
name: "dotnet-msbuild"
description: "Diagnose MSBuild failures and optimize build performance"
---# MSBuild Diagnosis and Optimization## When to Use- Build fails with cryptic errors
- Builds are slow (>30s for small projects)
- Silent failures (builds succeed but produce wrong output)
## Instructions1. Locate the binary log file (.binlog)
2. Use AITools.BinlogMcp to parse the log
3. Identify:
- Failed targets and their dependency chain
- Performance bottlenecks (targets >5s)
- Warning-as-errors that cause failures
4. Suggest fixes based on common patterns
Why SKILL.md Matters
Portability: Works in Claude Code, Cursor, GitHub Copilot, and custom agents
Shareability: Publish skills to npm, GitHub, or internal registries
Composability: Combine multiple skills in one agent
Version control: Track skill evolution alongside code
AGENT.md: Defining Agent Personalities
AGENT.md defines an entire agent's behavior, personality, knowledge, and capabilities.
Structure
markdown
---
name: "senior-backend-engineer"
version: "2.0.0"
model: "claude-sonnet-4.5"
temperature: 0.2
---# Senior Backend Engineer Agent## Identity
You are a senior backend engineer with 10+ years of experience in:
- Distributed systems (microservices, event-driven architecture)
- Python (FastAPI, Django), Go, and Node.js
- PostgreSQL, Redis, Kafka, and Elasticsearch
- AWS (ECS, Lambda, RDS, S3)
## Communication Style- Be concise but thorough
- Use technical terminology appropriately
- Provide code examples for complex concepts
- Ask clarifying questions about requirements
- Point out potential issues proactively
## Core Competencies### 1. Architecture Design- Design for scalability (10x current load)
- Consider failure modes and fallbacks
- Document trade-offs and decisions
### 2. Code Quality- Follow PEP 8 (Python) and Go conventions
- Write comprehensive tests (unit, integration, E2E)
- Implement proper error handling and logging
- Use type hints (Python) or strong typing (Go)
### 3. Security- Always validate and sanitize inputs
- Use parameterized queries (never string concatenation)
- Implement proper authentication and authorization
- Follow OWASP Top 10 guidelines
## Workflow### When starting a task:1. Understand requirements thoroughly (ask questions!)
2. Propose architectural approach
3. Identify dependencies and risks
4. Estimate complexity
### When writing code:1. Start with interfaces/types
2. Implement core logic
3. Add error handling
4. Write tests
5. Add logging and observability
### When reviewing code:1. Check for security vulnerabilities
2. Verify error handling
3. Assess performance implications
4. Ensure test coverage
5. Verify documentation
## Prohibited Actions- Never commit secrets or credentials
- Never disable security features "temporarily"
- Never skip error handling for convenience
- Never merge untested code
## Skills Available- api-design
- database-optimization
- docker-compose-setup
- kubernetes-deployment
Project-Level Configuration Files
CLAUDE.md: Claude Code Project Context
CLAUDE.md (also called .clauderc) provides persistent instructions to Claude Code and Claude Desktop.
Structure
markdown
---
project: "ecommerce-platform"
updated: "2026-05-22"
---# E-Commerce Platform - Claude Context## Project Overview
A Next.js 15 e-commerce platform using:
- Frontend: React 19, TypeScript, Tailwind CSS, shadcn/ui
- Backend: Next.js API routes, Prisma ORM
- Database: PostgreSQL (Supabase)
- Auth: NextAuth.js v5
- Payments: Stripe
- Deployment: Vercel
## Architecture Decisions### 1. Server Components First
Use React Server Components by default. Only use "use client" when:
- You need interactivity (onClick, onChange, etc.)
- You use hooks (useState, useEffect, etc.)
- You use browser-only APIs
### 2. Database Access- Always use Prisma Client (imported from `@/lib/db`)
- Never expose database queries in client components
- Use Server Actions for mutations
- Cache queries with `unstable_cache` when appropriate
### 3. Error Handling```typescript
// Always use this pattern
import { handleApiError } from '@/lib/errors';
try {
// operation
} catch (error) {
return handleApiError(error);
}
See .env.example for required variables. Never commit .env.local.
Deployment Notes
Preview deployments on every PR
Production deploys on merge to main
Database migrations run automatically via Prisma
snippet
#### When Claude Reads CLAUDE.md
Every time you interact with Claude Code in this project:
1. Claude loads `CLAUDE.md` first
2. Applies all rules and patterns automatically
3. Maintains consistency across conversations
4. Remembers architectural decisions
---
### MEMORY.md: Persistent Agent Memory
**MEMORY.md** stores information the agent should remember across sessions.
#### Use Cases
- Decisions made during development
- User preferences
- Debugging history
- Performance benchmarks
- Lessons learned
#### Structure
```markdown
# Project Memory
Last updated: 2026-05-22
## User Preferences
- Prefers TypeScript over JavaScript
- Likes functional programming style
- Uses Prettier with 2-space indents
- Prefers named exports over default exports
## Recent Decisions
### 2026-05-20: Switch from REST to tRPC
**Reason**: Type safety across client-server boundary
**Impact**: All new API routes use tRPC
**Location**: `src/server/api/`
### 2026-05-15: Add Redis caching layer
**Reason**: Database queries were slow (>500ms)
**Impact**: 10x speedup on product listing pages
**Configuration**: See `lib/redis.ts`
## Known Issues
### Issue: Prisma migrations fail in CI
**Status**: Investigating
**Workaround**: Run migrations manually before deployment
**Tracking**: Issue #234
### Issue: Image uploads timeout on large files
**Status**: Fixed (2026-05-18)
**Solution**: Implemented chunked uploads
**PR**: #245
## Performance Baselines
- Homepage load: ~1.2s (target: <1s)
- Product search: ~200ms (good)
- Checkout flow: ~3s (target: <2s)
## Debugging Notes
### Stripe webhook issues
- Must use raw body for signature verification
- Use `bodyParser: false` in Next.js config
- Test with Stripe CLI: `stripe listen --forward-to localhost:3000/api/webhooks/stripe`
### Database connection pool exhaustion
- Prisma default is 10 connections
- Increased to 20 in `schema.prisma`
- Monitor with `prisma.$metrics`
DESIGN.md: Design System Documentation
DESIGN.md defines UI/UX standards, component usage, and design principles.
All text must meet WCAG AA standards (4.5:1 ratio)
Interactive elements: 3:1 ratio minimum
Keyboard Navigation
All interactive elements must be keyboard accessible
Use semantic HTML (button, link, etc.)
Provide visible focus indicators
Screen Readers
Use proper ARIA labels
Provide alt text for images
Use semantic heading hierarchy (h1 → h2 → h3)
Animation
Duration
Fast: 150ms (micro-interactions)
Normal: 300ms (standard transitions)
Slow: 500ms (page transitions)
Easing
Enter: ease-out
Exit: ease-in
Move: ease-in-out
snippet
---
## Tool and Workflow Files
### TOOLS.md: Tool Definitions
**TOOLS.md** documents available tools, CLI commands, and scripts.
```markdown
# Available Tools
## Development
### Start Dev Server
```bash
npm run dev
# Starts Next.js on http://localhost:3000
Run Tests
bash
npm test# Run all tests
npm test:unit # Unit tests only
npm test:e2e # E2E tests only
npm test:watch # Watch mode
Database
bash
npx prisma studio # Open Prisma Studio
npx prisma db push # Push schema changes
npx prisma migrate dev # Create migration
npx prisma generate # Regenerate client
Code Quality
Linting
bash
npm run lint # ESLint
npm run lint:fix # Auto-fix issues
npm run type-check # TypeScript check
Formatting
bash
npm run format # Format with Prettier
Deployment
Build
bash
npm run build # Production build
npm run start # Start production server
Symptom:
Expected:
Actual:
Steps to reproduce:
Error logs:
Provide:
Root cause analysis
Proposed fix
Tests to prevent regression
snippet
## Architecture Proposal
Design a system for:
Consider:
Scalability: Support users
Performance: p95 latency
Cost: Budget of
Timeline:
Provide:
High-level architecture diagram
Technology choices with rationale
Data flow
Key trade-offs
Risks and mitigations
snippet
WORKFLOW.md: Automated Workflows
WORKFLOW.md defines multi-step processes.
markdown
# Workflows## Feature Development Workflow### Phase 1: Planning1. Create GitHub issue
2. Define acceptance criteria
3. Break down into subtasks
4. Estimate complexity
### Phase 2: Development1. Create feature branch: `git checkout -b feature/description`2. Write failing tests
3. Implement feature
4. Make tests pass
5. Refactor
### Phase 3: Review1. Self-review checklist:
- [ ] Tests pass locally
- [ ] No console errors/warnings
- [ ] TypeScript has no errors
- [ ] Code follows style guide
2. Create pull request
3. Address review comments
### Phase 4: Deployment1. Merge to main
2. Verify preview deployment
3. Monitor error tracking
4. Check performance metrics
## Bug Fix Workflow### 1. Reproduce- Get exact steps to reproduce
- Verify in local environment
- Capture error logs
### 2. Isolate- Write a failing test that reproduces the bug
- Use debugger to step through
- Identify root cause
### 3. Fix- Implement minimal fix
- Ensure test passes
- Check for similar issues elsewhere
### 4. Verify- Run full test suite
- Manual testing
- Update documentation if needed
### 5. Deploy- Create PR with "Fixes #<issue-number>"
- Get review
- Merge and deploy
- Notify affected users
IDE-Specific Configuration Files
.cursorrules: Cursor AI Rules
Cursor IDE uses .cursorrules for project-specific instructions.
markdown
# Cursor Rules## Project: Next.js E-Commerce
You are an expert Next.js developer working on an e-commerce platform.
### Tech Stack- Next.js 15 (App Router)
- React 19
- TypeScript
- Tailwind CSS
- Prisma
- PostgreSQL
### Code Style- Use functional components
- Prefer Server Components
- Use TypeScript strict mode
- Follow ESLint config
### File Structure- Components: `components/`- Utils: `lib/`- API Routes: `app/api/`- Types: `types/`### When creating components:1. Start with TypeScript interface for props
2. Use Tailwind for styling
3. Add proper TypeScript types
4. Include JSDoc comments for complex logic
### When writing API routes:1. Validate inputs with Zod
2. Use proper error handling
3. Return typed responses
4. Add rate limiting where appropriate
.clinerules: Cline Agent Rules
Similar to .cursorrules but for Cline (VS Code extension).
markdown
You are a senior full-stack developer.
Project: Task Management SaaS
Stack: React, Node.js, MongoDB
Rules:
- Always use TypeScript
- Prefer functional components with hooks
- Use Tailwind CSS for styling
- Follow REST API conventions
- Write tests for all new features
When editing files:
1. Read the entire file first
2. Understand the context
3. Make minimal, focused changes
4. Update related tests
When debugging:
1. Check console for errors
2. Review recent changes
3. Add logging strategically
4. Test hypotheses systematically
.windsurfrules: Windsurf IDE Rules
Windsurf (by Codeium) uses .windsurfrules.
markdown
# Windsurf Rules## Project Context
Python FastAPI backend with PostgreSQL
## Standards- Follow PEP 8
- Use type hints everywhere
- Async/await for I/O operations
- Pydantic models for validation
## Database- Use SQLAlchemy 2.0 async
- Alembic for migrations
- Connection pooling
## Testing- pytest for unit tests
- pytest-asyncio for async tests
- >80% code coverage required
## Security- Always validate inputs
- Use parameterized queries
- Hash passwords with bcrypt
- Implement rate limiting
INSTRUCTIONS.md: GitHub Copilot Instructions
GitHub Copilot Workspace reads INSTRUCTIONS.md or .github/copilot-instructions.md.
markdown
# GitHub Copilot Instructions## Project Overview
Enterprise CRM built with Django and React
## Coding Standards### Python- Use Django 5.0 best practices
- Class-based views for CRUD
- Function-based views for custom logic
- Always use Django ORM (no raw SQL)
### JavaScript- Modern ES6+ syntax
- React functional components
- Redux Toolkit for state management
- React Query for server state
### Testing- pytest for backend
- Jest + React Testing Library for frontend
- Minimum 80% coverage
### Documentation- Docstrings for all functions
- README for each app
- API documentation with drf-spectacular
## Common Patterns### Django View Pattern```python
from rest_framework import generics
from rest_framework.permissions import IsAuthenticated
class ContactListCreateView(generics.ListCreateAPIView):
permission_classes = [IsAuthenticated]
serializer_class = ContactSerializer
def get_queryset(self):
return Contact.objects.filter(user=self.request.user)
### Writing Effective Agent Instructions
#### 1. Be Specific
❌ "Write good code"
✅ "Use TypeScript strict mode, Prettier with 2-space indents, and named exports"
#### 2. Provide Examples
❌ "Follow our coding style"
✅ Include code examples in your markdown files
#### 3. Explain Why
❌ "Never use `any` type"
✅ "Never use `any` type because it defeats TypeScript's type safety and makes refactoring dangerous"
#### 4. Update Regularly
- Review markdown files monthly
- Update after major architectural changes
- Remove outdated instructions
- Keep examples current
#### 5. Test Your Instructions
- Ask your AI agent to perform tasks
- Verify it follows your guidelines
- Refine instructions based on results
---
## Cross-Platform Compatibility
### Universal Instructions (CLAUDE.md style)
Most agents can read markdown files. To support multiple IDEs:
```markdown
<!-- This file works in Claude Code, Cursor, Copilot, and Cline -->
# Universal Project Instructions
## Tech Stack
TypeScript, React, Next.js 15
## Rules
1. Use Server Components by default
2. TypeScript strict mode
3. Tailwind CSS for styling
4. Zod for validation
## Patterns
[Include your standard patterns here]
This guide reflects the state of agent configuration files as of May 2026. Standards and formats continue to evolve rapidly across the AI agent ecosystem.
