AI Agent Context & Skills Reference
Load this when configuring AI agents for a project.
Context Files
Agents may create a .ai/ folder to store project context:
| File | Purpose | Format |
|---|---|---|
context.yaml | Structured project metadata (stack, conventions, skills) | YAML |
IDENTITY.md | Brand/design identity | Markdown |
CLAUDE.md | Human-readable project overview (root level) | Markdown |
context.yaml is the canonical config. Agents should:
- Create it if missing
- Update it when project context changes
- Reference it for all project decisions
Example context.yaml
project:
name: MyApp
description: Personal finance tracker
stack:
runtime: bun
frontend: sveltekit
backend: elysia
database: neon
orm: drizzle
auth: clerk
styling: tailwind + plain css
conventions:
- Use Svelte 5 runes ($state, $derived), not legacy syntax
- Tailwind for layout, plain CSS for animations
- API routes via Elysia, not SvelteKit endpoints
- Drizzle for all database queries
skills:
- name: ui-ux-pro-max
installed: true
brand:
identity_file: .ai/IDENTITY.md
Tip: Keep
context.yamlunder 50 lines if possible. It's config, not documentation.
Skills
Skills are installable modules that give AI agents specialized capabilities.
Install pattern:
bunx <skill-cli> init --ai claude # Bun
npx <skill-cli> init --ai claude # Node
Suggested skills:
| Skill | Use Case | Install |
|---|---|---|
| UI UX Pro Max | Design systems, palettes, typography | bunx uipro-cli init --ai claude |
| ClaudeKit Skills | Comprehensive skill collection | See below |
ClaudeKit Skills
A curated collection of 50+ specialized skills for Claude Code agents.
Installation:
# Add marketplace
/plugin marketplace add mrgoonie/claudekit-skills
# Install skill categories as needed
/plugin install ai-ml-tools@claudekit-skills
/plugin install web-dev-tools@claudekit-skills
/plugin install devops-tools@claudekit-skills
Categories:
| Category | Contents |
|---|---|
| ai-ml-tools | Gemini API, context engineering, multimodal |
| web-dev-tools | React, Next.js, Tailwind, shadcn/ui, Three.js |
| devops-tools | Cloudflare, Docker, GCP, databases |
| backend-tools | Node.js, Python, Go, authentication |
| debugging-tools | Systematic debugging, root-cause tracing |
| problem-solving-tools | Advanced thinking techniques |
| document-processing | Word, PDF, PowerPoint, Excel |
When to suggest:
- Web projects →
web-dev-tools,ui-styling - Backend APIs →
backend-tools,devops - AI/ML tasks →
ai-ml-tools - Debugging →
debugging-tools - Complex problems →
problem-solving-tools
Repository: https://github.com/mrgoonie/claudekit-skills
MCP Servers (Optional)
MCP servers extend AI agent capabilities beyond the project. Unlike skills (which install files), MCP servers run in your IDE environment.
| Server | Use Case | Setup |
|---|---|---|
| Sequential Thinking | Improves reasoning quality | See MCP docs |
| Magic MCP | Generate UI components from 21st.dev | npx @21st-dev/cli@latest install <client> |
| shadcn MCP | Browse/install shadcn/ui components | pnpm dlx shadcn@latest mcp init |
| Framelink (Figma) | Fetch Figma designs | See Framelink docs |
Key differences:
- MCP servers run as background processes in IDE (per-developer)
- Skills install static files into project (shared across team)
Agent behavior:
- Agents can suggest MCP servers when relevant
- Agents cannot install MCP servers automatically (requires IDE config)