resources/agent-skills-architecture.md
# Agent Skills Architecture for Project-Specific Workflows
Agent skills package specialized, reusable workflows as `SKILL.md`-based modules. While AGENTS.md defines *what the project is*, skills define *what the agent can do* within it. This resource covers how to design skills for your project's repeatable tasks.
---
## Overview: Identity vs. Capability
| Layer | Artifact | Purpose | Example |
|-------|----------|---------|---------|
| Identity | `AGENTS.md` | Static project rules, conventions, build steps | "Use TypeScript strict mode" |
| Capability | `SKILL.md` + resources | Dynamic, executable workflows loaded on demand | "Scaffold a new API endpoint" |
| Connectivity | `mcp.json` | Live tool access (databases, IDE, APIs) | "Query the database schema" |
Skills are loaded via **progressive disclosure**:
- Level 1 (always in context): metadata only (~100 tokens per skill)
- Level 2 (loaded when triggered): full SKILL.md instructions
- Level 3 (loaded as needed): scripts, reference files, assets
---
## When to Create a Skill for Your Project
Create a project-specific skill when:
- The same multi-step workflow is repeated frequently (e.g., "add a new feature module")
- Architectural rules are complex enough to warrant dedicated instructions
- The workflow involves tool coordination (MCP + file edits + test runs)
- Agent mistakes follow a pattern that hints at missing procedural knowledge
**Do not** create a skill for:
- One-off tasks unlikely to recur
- Simple conventions already in AGENTS.md
- Straightforward single-step operations
---
## Skill Structure for Project Workflows
```
.claude/skills/
├── add-feature/
│ ├── SKILL.md # Trigger phrases + step-by-step workflow
│ └── resources/
│ ├── feature-template.md # Template showing expected file layout
│ └── conventions.md # Architecture-specific rules
│
├── database-migration/
│ ├── SKILL.md
│ └── scripts/
│ └── generate-migration.py # Deterministic migration generation
│
└── deploy-staging/
├── SKILL.md
└── resources/
└── checklist.md # Pre-deploy validation steps
```
Skills can live in:
- `.claude/skills/` — project-level (committed to repo)
- `~/.claude/skills/` — personal/global (available across all projects)
---
## Writing Effective Trigger Phrases in SKILL.md
The `description` field in SKILL.md frontmatter determines when the skill loads. Per the AAIF spec, it is pre-loaded as lightweight metadata (~100 tokens) so the agent can decide relevance.
### Effective Description Pattern
```
[What it does] + [When to use it] + [Exact trigger phrases]
```
**Example — good:**
```yaml
description: Scaffolds a new REST API endpoint in this project following our
layered architecture (router → service → repository). Use when asked to
"add an endpoint", "create a route", or "add an API for [feature]".
Generates controller, service, repository, and test files in the correct
directories with the project's naming conventions pre-applied.
```
**Example — too vague:**
```yaml
description: Helps with API development.
```
### Preventing Over-Triggering
Add explicit exclusions to prevent the skill loading for unrelated tasks:
```yaml
description: ... Do NOT use for frontend component creation (use the
add-component skill instead) or for database migrations (use
database-migration skill).
```
---
## Structuring SKILL.md for a Project Workflow
Follow this template for project-specific skills:
```markdown
---
name: [project-name]-[workflow]
description: [What + When + Triggers + Exclusions]
metadata:
project: [project-name]
version: 1.0.0
---
# [Workflow Name]
Brief description of what this workflow produces.
## Critical
[Any must-follow rules — put them first, use this section for non-negotiables]
## Steps
1. [Step 1 — specific, actionable]
2. [Step 2]
3. [Step 3 — including: run `[test command]` to validate]
## File Locations
- New files go in: `[path]/`
- Naming pattern: `[pattern]`
- Import from: `[path]` using `[alias]`
## Conventions for This Workflow
- [Specific rule 1]
- [Specific rule 2]
## Validation Checklist
Before marking complete:
- [ ] Tests pass: `[command]`
- [ ] Types check: `[command]`
- [ ] No lint errors: `[command]`
```
---
## Example: "Add Feature Module" Skill
For a project using a feature-based folder structure:
```yaml
---
name: add-feature-module
description: Creates a new feature module in the project following the
feature-slice architecture. Use when asked to "add a feature",
"create a new module", or "scaffold [feature-name]". Creates the
full directory structure, index barrel, component, hook, and test files.
Do NOT use for standalone utility functions or API-only changes.
---
# Add Feature Module
Creates a complete feature slice: component, hook, types, tests, and barrel.
## Critical
All new feature modules MUST be placed in `src/features/[feature-name]/`.
Never place feature logic directly in `src/components/` or `src/pages/`.
## Steps
1. Create directory: `src/features/[name]/`
2. Create `src/features/[name]/index.ts` (barrel file, re-exports public API only)
3. Create `src/features/[name]/[Name].tsx` (main component — named export)
4. Create `src/features/[name]/use[Name].ts` (hook for business logic)
5. Create `src/features/[name]/[name].types.ts` (TypeScript types)
6. Create `src/features/[name]/[name].test.tsx` (Vitest + Testing Library)
7. Run `pnpm typecheck && pnpm test` to validate
## Naming Conventions
- Directory: lowercase kebab-case (`user-profile`)
- Component file: PascalCase (`UserProfile.tsx`)
- Hook file: camelCase with `use` prefix (`useUserProfile.ts`)
- Types file: lowercase with `.types.ts` suffix
## What NOT to do
- Do not create `default` exports (use named exports everywhere)
- Do not import directly from sub-files — always go through the barrel (`index.ts`)
- Do not add styling inline — use the `[Name].module.css` file pattern
```
---
## Skills for Architecture Migration
When the team is migrating from one pattern to another, a skill ensures consistency:
```yaml
---
name: migrate-to-react-query
description: Migrates a component from local useState/useEffect data fetching
to TanStack Query (React Query). Use when asked to "migrate data fetching",
"convert to React Query", or "refactor [component] to use TanStack".
---
# Migrate Component to TanStack Query
## Steps
1. Install check: verify `@tanstack/react-query` in package.json
2. Identify the fetch pattern to replace (useEffect + useState)
3. Create a query key constant in `lib/query-keys.ts`
4. Replace the useState/useEffect with `useQuery(queryKey, fetchFn)`
5. Map loading/error/data states to the component's existing UI
6. Add the query to `QueryClient` prefetching if it's a page-level fetch
7. Run `pnpm test [component]` to confirm behaviour unchanged
## Key Patterns in This Codebase
- Query keys defined in `lib/query-keys.ts` (centralized)
- Query functions defined in `lib/api/` (not inline in components)
- Error boundaries in `app/error.tsx` handle React Query errors globally
```
---
## Meta-Skills: Skills that Create Skills
A meta-skill instructs the agent to observe a successful session and write a new skill to automate it:
```yaml
---
name: capture-workflow
description: After successfully completing a complex, repeatable task, use
this skill to capture the workflow as a new SKILL.md. Use when asked to
"save this workflow", "create a skill for this", or "automate what we just did".
---
# Capture Workflow as Skill
## Steps
1. Review the current session for the repeatable steps just performed
2. Identify: trigger phrases, step order, file locations, validation commands
3. Run: `python scripts/init_skill.py [name] --path .claude/skills/`
4. Write SKILL.md with:
- Precise description with trigger phrases from this session
- Step-by-step instructions (imperative, not suggestions)
- Exact commands used
- Validation checklist
5. Test by asking: "Would you use [skill-name] to do [task]?" — verify it
loads correctly
6. Commit to version control
```
---
## Deployment: Making Skills Available to the Team
| Method | Use Case | Commands |
|--------|----------|---------|
| Commit to `.claude/skills/` in repo | Project-level, shared with all contributors | `git add .claude/skills/ && git commit -m "add [skill] skill"` |
| User global `~/.claude/skills/` | Personal workflows across projects | `cp -r .claude/skills/[name] ~/.claude/skills/` |
| Claude Console (admin deploy) | Organization-wide deployment (Jan 2026+) | Via Claude Console → Capabilities → Skills |
| ZIP for Claude Desktop | Desktop/API distribution | `python scripts/package_skill.py .claude/skills/[name]` |
resources/agents-md-guide.md
# AGENTS.md Guide
AGENTS.md is an open-standard file (governed by the Agentic AI Foundation / Linux Foundation) that serves as a "README for agents." While README.md is written for human contributors, AGENTS.md provides the precise technical context AI coding agents need to operate autonomously: build steps, testing protocols, architectural constraints, and conventions.
---
## Recommended Sections
### 1. Project Overview
A concise technical summary — not marketing copy. Include:
- Primary tech stack (languages, frameworks, runtimes)
- Core architectural pattern (monolith, microservices, monorepo, etc.)
- Key directories and their purpose
- Any unusual or non-standard choices
**Example:**
```markdown
## Project Overview
Full-stack web application built with Next.js 15 (App Router), TypeScript strict mode,
and a PostgreSQL database accessed via Drizzle ORM. REST API routes in `app/api/`.
Frontend components use shadcn/ui. Authentication via NextAuth.js.
Key directories:
- `app/` — Next.js App Router pages and API routes
- `lib/` — Shared utilities, database client, auth helpers
- `components/` — Reusable UI components (shadcn/ui based)
- `db/` — Drizzle schema, migrations
- `tests/` — Vitest unit + integration tests
```
### 2. Setup & Build Commands
Exact, copy-pasteable commands. Agents run these literally.
```markdown
## Setup & Build
Install dependencies:
pnpm install
Start development server:
pnpm dev # runs on http://localhost:3000
Run database migrations:
pnpm db:migrate
Build for production:
pnpm build
```
### 3. Testing Instructions
Include linting, type-checking, and unit/integration test commands. Specify what agents must run before committing.
```markdown
## Testing
Run all tests:
pnpm test
Run tests in watch mode:
pnpm test:watch
Type-check without building:
pnpm typecheck
Lint:
pnpm lint
IMPORTANT: Always run `pnpm typecheck && pnpm test` before marking a task complete.
```
### 4. Code Style & Conventions
The most valuable section for eliminating repeated mistakes. Be specific.
```markdown
## Code Style & Conventions
- TypeScript strict mode is enabled — never use `any`
- Use `type` not `interface` for object shapes
- Functional components only — no class components
- All imports use path aliases (`@/lib/...` not relative `../../lib/...`)
- Single quotes, no semicolons (enforced by ESLint/Prettier)
- Use named exports, not default exports (except page components)
- Database queries go in `lib/db/` — never inline SQL in components
- Environment variables accessed only through `lib/env.ts` (validated at startup)
```
### 5. Architecture & Constraints
Document non-obvious decisions and hard constraints.
```markdown
## Architecture Constraints
- This is a multi-tenant SaaS — always filter queries by `organizationId`
- Never expose user PII in API responses; strip before returning
- All external API calls go through `lib/api-client.ts` (centralizes auth headers)
- Background jobs use BullMQ — do not use `setTimeout` for deferred work
- Feature flags checked via `lib/flags.ts` — do not hardcode feature availability
```
### 6. Security Considerations
Make implicit security rules explicit.
```markdown
## Security
- Never log request bodies or database query results (may contain PII)
- API routes validate JWT via `lib/auth/validate.ts` — do not skip this
- All user-controlled strings are escaped before DB insertion (Drizzle handles this)
- `NEXT_PUBLIC_*` env vars are exposed to the browser — never put secrets there
- Dependency updates: run `pnpm audit` before merging security-related PRs
```
### 7. Operational Context
Commit message format, PR conventions, branch naming, etc.
```markdown
## Operational Context
Commit format: `type(scope): description` (Conventional Commits)
- feat(auth): add OAuth2 provider
- fix(api): handle null user response
- chore(deps): update Next.js to 15.2
Branch naming: `feature/short-description`, `fix/issue-number`, `chore/task-name`
Do not commit directly to `main` — use PRs with at least one reviewer.
```
---
## Hierarchical Discovery in Monorepos
AGENTS.md supports nested files to avoid bloating a single root file and to provide scoped instructions per package.
### Resolution Rules
1. Agents discover instructions by searching from the current file's directory **upward** to the repo root
2. The closest AGENTS.md takes precedence (most-specific wins)
3. Agents typically load all AGENTS.md files along the path and merge them, with closer files overriding global rules
### Recommended Structure
```
repo/
├── AGENTS.md # Global: team conventions, CI, git rules
├── packages/
│ ├── frontend/
│ │ └── AGENTS.md # Overrides: React/Next.js specifics
│ ├── backend/
│ │ └── AGENTS.md # Overrides: Go/API specifics
│ └── shared/
│ └── AGENTS.md # Overrides: shared library rules
└── infra/
└── AGENTS.md # Overrides: Terraform/Pulumi specifics
```
The root AGENTS.md defines baseline rules. Subdirectory files add or override for their scope. Example root entry:
```markdown
## Root Conventions
Use spaces for indentation (2 spaces). All packages must have tests.
```
And the frontend override:
```markdown
## Frontend-Specific Build
Install all packages from repo root: `pnpm install`
Start only frontend: `pnpm --filter @repo/frontend dev`
Run frontend tests: `pnpm --filter @repo/frontend test`
```
---
## Comparison: AGENTS.md vs. CLAUDE.md vs. copilot-instructions.md
| Feature | AGENTS.md | CLAUDE.md | copilot-instructions.md |
|---------|-----------|-----------|------------------------|
| Governance | Open standard (AAIF/Linux Foundation) | Proprietary (Anthropic) | Proprietary (GitHub/Microsoft) |
| Scope | Cross-platform (Codex, Cursor, Gemini CLI, Claude Code) | Claude Code CLI only | GitHub Copilot only |
| File location | Repo root and nested directories | Repo root or `.claude/` | `.github/` directory |
| Discovery | Hierarchical (closest file wins) | Flat (root file) | Flat (single file) |
| Interoperability | High — referenced by other config files | Low | Low |
### Convergence Trend (2026)
The industry is converging on AGENTS.md as the unified baseline. As of early 2026, it is supported by Cursor, Codex, Gemini CLI, and Claude Code.
**The recommended pattern** for multi-tool repos:
1. Write all project context into `AGENTS.md` (the single source of truth)
2. Create `CLAUDE.md` containing only: `Read @AGENTS.md`
3. Create `.github/copilot-instructions.md` containing only: `See AGENTS.md for project context`
This avoids duplicating project knowledge across tool-specific files.
---
## AGENTS.md Template
Copy and customize this template for any project:
```markdown
# AGENTS.md — [Project Name]
## Project Overview
[One paragraph: tech stack, architecture, purpose]
Key directories:
- `src/` — [purpose]
- `tests/` — [purpose]
## Setup & Build
Install dependencies:
[command]
Start development:
[command]
## Testing
Run all tests:
[command]
IMPORTANT: Always run [test command] before marking work complete.
## Code Style & Conventions
- [Convention 1]
- [Convention 2]
- [Convention 3]
## Architecture Constraints
- [Constraint 1]
- [Constraint 2]
## Security
- [Security rule 1]
- [Security rule 2]
## Operational Context
Commit format: [format]
Branch naming: [pattern]
```
---
## Common AGENTS.md Mistakes to Avoid
| Mistake | Why It's a Problem | Fix |
|---------|-------------------|-----|
| Copying README.md content verbatim | README is for humans; agents need precise commands | Extract only technical, actionable content |
| Vague conventions ("write clean code") | Unenforceable by agents | Give specific, checkable rules |
| No test/build commands | Agents guess or skip validation | Add exact commands, including flags |
| Not updating after refactors | Agents follow stale instructions ("context rot") | Schedule AGENTS.md reviews on major changes |
| Putting workflow logic in AGENTS.md | Should live in agent skills (SKILL.md) | Keep AGENTS.md for identity; skills for capability |
| No security section | Agents may repeat unsafe patterns | Add explicit security rules for your threat model |
resources/mcp-codebase-tools.md
# MCP Servers for Codebase Navigation
Model Context Protocol (MCP) gives AI agents live, dynamic access to your IDE, codebase, and infrastructure — beyond what static files can provide. This resource covers the key MCP servers for code navigation, semantic search, and developer tooling.
---
## Overview: Why MCP for Codebase Understanding
Static files (AGENTS.md, skills) give agents context about *how the project works*. MCP gives agents tools to *explore the living codebase* — finding usages, navigating call hierarchies, checking diagnostics, and querying databases.
| Without MCP | With MCP |
|-------------|---------|
| Agent reads a file's source to understand it | Agent calls `find_usages("UserService")` |
| Agent guesses at function signatures | Agent calls `get_type_definition` on any symbol |
| Agent misses a compilation error | Agent calls `get_diagnostics` and sees errors directly |
| Agent re-discovers schema from migration files | Agent queries live DB schema via MCP |
---
## Primary MCP Servers
### 1. Bifrost — IDE Language Server for Agents
The highest-value MCP server for codebase navigation. Bifrost is a VS Code extension that exposes the IDE's Language Server Protocol (LSP) capabilities to LLMs via MCP.
**Install:** Search "Bifrost" in VS Code Extensions, or `ext install bifrost.bifrost-mcp`
**Configuration** (`.vscode/mcp.json`):
```json
{
"servers": {
"bifrost": {
"type": "stdio",
"command": "node",
"args": ["${userHome}/.vscode/extensions/bifrost.bifrost-mcp-*/dist/server.js"]
}
}
}
```
**Available Tools:**
| Tool | Purpose | Example Use |
|------|---------|-------------|
| `find_usages` | Find all references to a symbol | "Where is `UserService` used?" |
| `get_call_hierarchy` | Incoming and outgoing call graph | "What calls `processPayment()`?" |
| `go_to_definition` | Navigate to symbol definition | "Where is `AuthToken` defined?" |
| `find_implementations` | Find all implementations of an interface | "What implements `IRepository`?" |
| `get_type_definition` | Type info for a symbol | "What type does `result` have?" |
| `get_workspace_symbols` | Search symbols across the project | "Find all classes named `*Service`" |
| `get_document_symbols` | Outline symbols in a file | "List all functions in `auth.ts`" |
| `get_diagnostics` | Compilation errors and warnings | "Are there any type errors?" |
| `get_hover_info` | Documentation on hover | "What does `encryptPII` do?" |
**Add to AGENTS.md:**
```markdown
## MCP Tools Available
Code navigation (via Bifrost MCP):
- `find_usages` — find all references to a symbol
- `get_call_hierarchy` — trace calls to/from a function
- `go_to_definition` — navigate to a definition
- `get_diagnostics` — check for compilation errors
Use these tools instead of grepping source files for symbol references.
```
---
### 2. vscode-mcp-server — VS Code Control and File Analysis
Open-source server that turns a local VS Code instance into an MCP server. Complements Bifrost with additional file editing, terminal, and symbol tools.
**Install:** `npx @vscode/mcp-server`
**Configuration** (`.vscode/mcp.json`):
```json
{
"servers": {
"vscode": {
"type": "stdio",
"command": "npx",
"args": ["@vscode/mcp-server"]
}
}
}
```
**Key Tools:**
| Tool | Purpose |
|------|---------|
| `get_diagnostics_code` | File or workspace errors/warnings |
| `get_symbol_definition_code` | Type info and docs for a symbol at a line |
| `get_document_symbols_code` | Hierarchical outline of functions/classes |
| `search_symbols_code` | Find symbols by name across workspace |
| `open_file` | Open a file in the editor |
| `run_terminal_command` | Execute a terminal command |
---
### 3. GitHub MCP Server — Remote Repository Context
For exploring code that isn't locally checked out, or for cross-repository searches.
**Install:** `npx @github/mcp-server`
**Configuration** (`.vscode/mcp.json`):
```json
{
"servers": {
"github": {
"type": "stdio",
"command": "npx",
"args": ["@github/mcp-server"],
"env": {
"GITHUB_TOKEN": "${env:GITHUB_TOKEN}"
}
}
}
}
```
**Key Tools:**
| Tool | Purpose |
|------|---------|
| `search_code` | Full-text code search across repositories |
| `get_file_contents` | Read a file from a remote repo |
| `list_commits` | View commit history for a branch/file |
| `get_pull_request` | Read PR details and review comments |
| `list_issues` | Browse open issues |
| `create_issue` | Create an issue from within the agent session |
---
### 4. Semantic Search via Vector Store MCP
For natural-language queries over large codebases or documentation, connect a vector store.
#### Option A: Qdrant (self-hosted)
```json
{
"servers": {
"qdrant": {
"type": "stdio",
"command": "npx",
"args": ["qdrant-mcp-server"],
"env": {
"QDRANT_URL": "http://localhost:6333",
"COLLECTION_NAME": "codebase"
}
}
}
}
```
**Workflow:**
1. Index codebase: `python scripts/index-codebase.py --collection codebase`
2. Query: agent calls `search("How does auth work?")` → returns relevant code chunks
#### Option B: Azure AI Search (cloud)
```json
{
"servers": {
"azure-search": {
"type": "stdio",
"command": "npx",
"args": ["azure-ai-search-mcp"],
"env": {
"AZURE_SEARCH_ENDPOINT": "${env:AZURE_SEARCH_ENDPOINT}",
"AZURE_SEARCH_API_KEY": "${env:AZURE_SEARCH_API_KEY}",
"INDEX_NAME": "codebase-index"
}
}
}
}
```
---
### 5. Database MCP Server — Live Schema Access
Prevent agents from guessing at database schemas by giving them direct query access.
**Configuration example (PostgreSQL):**
```json
{
"servers": {
"postgres": {
"type": "stdio",
"command": "npx",
"args": ["@modelcontextprotocol/server-postgres"],
"env": {
"DATABASE_URL": "${env:DATABASE_URL}"
}
}
}
}
```
Agents can call:
- `list_tables` — enumerate all tables
- `describe_table` — columns, types, constraints for a table
- `query` — run a SELECT query (read-only by default)
**Security note:** Use a read-only database user for the MCP server connection. Never point MCP at a production database with write credentials.
---
## Full mcp.json Template
Place this at `.vscode/mcp.json` in your project root:
```json
{
"servers": {
"bifrost": {
"type": "stdio",
"command": "node",
"args": ["${userHome}/.vscode/extensions/bifrost.bifrost-mcp-*/dist/server.js"],
"description": "LSP-powered code navigation (find usages, call hierarchy, diagnostics)"
},
"github": {
"type": "stdio",
"command": "npx",
"args": ["@github/mcp-server"],
"env": {
"GITHUB_TOKEN": "${env:GITHUB_TOKEN}"
},
"description": "GitHub code search and repository access"
}
}
}
```
Add other servers (vscode, postgres, qdrant) as needed.
---
## Tool Selection Guide
When should agents use which tool?
| Question | Preferred Tool |
|----------|---------------|
| "Where is X defined?" | Bifrost `go_to_definition` |
| "What calls function X?" | Bifrost `get_call_hierarchy` |
| "What implements interface X?" | Bifrost `find_implementations` |
| "Are there compilation errors?" | Bifrost `get_diagnostics` or vscode `get_diagnostics_code` |
| "Find all files using a pattern" | Bifrost `find_usages` or vscode `search_symbols_code` |
| "What's the DB schema for table X?" | DB MCP `describe_table` |
| "How does the auth flow work?" (concept) | Semantic search MCP `search` |
| "Find code in another repo" | GitHub MCP `search_code` |
Document this guide in AGENTS.md so agents know which tool to reach for.
---
## Troubleshooting MCP Configuration
| Problem | Likely Cause | Fix |
|---------|-------------|-----|
| Server not found in agent session | mcp.json path wrong or extension not installed | Verify `.vscode/mcp.json` exists; reload VS Code window |
| Tool call returns "not connected" | MCP server process not running | Check MCP extension status in VS Code Output panel |
| Bifrost tools not available | Extension not activated | Open any source file to trigger language server activation |
| GitHub auth failure | `GITHUB_TOKEN` env var missing | Add to shell profile or `.env` (git-ignored) |
| DB query fails with permission denied | DB user insufficient permissions | Use a dedicated read-only DB user for MCP |
resources/self-improvement-patterns.md
# Self-Improvement Patterns for AI Agents
Agent configurations become stale over time — a phenomenon called "context rot." This resource covers strategies for keeping AI context accurate, establishing feedback loops, preventing context window poisoning, and building living documentation that improves with the project.
---
## The Problem: Context Rot
Context rot occurs when:
- AGENTS.md instructions describe outdated conventions or deleted files
- Skills contain stale commands that no longer match the codebase
- The agent follows superseded patterns because no one updated the docs
- Context windows fill with conflicting instructions, reducing signal quality
Left unaddressed, context rot causes agents to regress — making mistakes that were previously corrected.
---
## Strategy 1: Treat Agent Mistakes as Documentation Bugs
Every repeated agent error signals a gap or inaccuracy in AGENTS.md or a skill.
### Feedback Loop Protocol
When an agent makes a mistake:
1. **Identify** — Was it a wrong command, wrong pattern, or wrong file path?
2. **Locate** — Which file (AGENTS.md or a skill) should have prevented it?
3. **Update** — Add an explicit instruction that corrects the behaviour
4. **Test** — Repeat the original task; verify the agent now follows the correction
5. **Commit** — Treat the doc update as a code fix; add it to the PR or commit
**Example:**
```
Agent made mistake: Used `npm install` instead of `pnpm install`
Fix: Added to AGENTS.md under ## Setup:
"Package manager: pnpm (NOT npm or yarn). Always use `pnpm install`.
Running `npm install` will corrupt the lockfile."
```
---
## Strategy 2: End-of-Session Improvement Prompts
After completing a complex task, explicitly ask the agent to propose documentation improvements.
### Prompt Templates
**After debugging:**
```
Based on the debugging session we just completed, what should we add to
AGENTS.md to prevent this class of error in future sessions?
```
**After implementing a new pattern:**
```
We just added [feature/pattern]. Update AGENTS.md to document this new
convention so future agents (and teammates) understand it.
```
**After a failed refactor attempt:**
```
The approach we first tried didn't work because [reason]. Add a note to
AGENTS.md or the relevant skill so agents don't repeat this mistake.
```
**Weekly/monthly review:**
```
Review AGENTS.md and all skills in .claude/skills/. Identify any instructions
that are outdated, incorrect, or missing based on what you know about the
current codebase. List proposed changes.
```
---
## Strategy 3: Progressive Disclosure to Prevent Context Overload
Loading everything into context simultaneously causes "context collapse" — the agent loses coherence as the window fills.
### Tiered Loading Architecture
| Level | Content | Tokens | When Loaded |
|-------|---------|--------|-------------|
| 1 — Always present | AGENTS.md + skill metadata (name/description only) | ~500 | Session start |
| 2 — On demand | Full SKILL.md when a skill is triggered | ~2,000 per skill | Matching task |
| 3 — Reference pull | Resource files within a skill | ~5,000 per file | When referenced |
**Design for this in AGENTS.md:**
- Keep AGENTS.md under 500 lines — move detailed docs to skills and references
- Use skills instead of long AGENTS.md appendices for workflow procedures
- Write skill descriptions that are specific enough to trigger only when relevant
### Context Compression Checkpoints
For long sessions, periodically compact context:
```
Provide a concise summary of what we've accomplished, the key decisions made,
and importantly, any updated understanding of the codebase architecture.
I'll use this as a checkpoint if the context window fills.
```
---
## Strategy 4: Memory Architecture for Long-Lived Projects
For projects maintained over months/years, structure persistent memory across layers:
### Memory Tiers
```
Short-term memory: Active conversation context (message buffer)
↓ fades at session end
Core memory: AGENTS.md — stable conventions and project identity
↓ persists across sessions
Skill memory: .claude/skills/ — executable workflows and patterns
↓ persists across sessions
Archival memory: Vector store (via MCP) — searchable history of decisions
↓ persists; retrieved on demand
```
### Practical Implementation
1. **Core memory** → Maintain in `AGENTS.md` (version-controlled, human-readable)
2. **Skill memory** → Commit skills to `.claude/skills/` in the repo
3. **Archival memory** → For decision rationale, use an Architecture Decision Record (ADR) folder:
```
docs/
└── decisions/
├── 001-chose-drizzle-over-prisma.md
├── 002-feature-slice-architecture.md
└── 003-tanstack-query-for-server-state.md
```
Reference ADRs in AGENTS.md:
```markdown
## Architecture Decisions
Key architectural decisions are documented in `docs/decisions/`.
Consult these before proposing changes to core patterns.
Notable decisions:
- #002 — Feature-slice structure (do not flatten to component-based layout)
- #003 — TanStack Query for all server state (do not use useEffect + fetch)
```
---
## Strategy 5: Skills as Living Workflows
Skills degrade when the project changes but the skill is not updated.
### Skill Maintenance Checklist
Run this when making significant changes to the project:
- [ ] Do any skill commands reference renamed/moved files? Update paths.
- [ ] Do any skill commands reference deprecated tools or packages? Update.
- [ ] Have new conventions been adopted that conflict with existing skills?
- [ ] Are any skills never triggered? Consider merging into AGENTS.md or deleting.
- [ ] Are any AGENTS.md sections complex enough to deserve their own skill?
### Skill Version Pinning
When a skill is created at a specific project checkpoint, note it:
```yaml
---
name: add-api-endpoint
metadata:
version: 2.0.0
updated: 2026-02-18
note: Updated for v2 route structure after API refactor
---
```
---
## Strategy 6: Meta-Skills for Automated Improvement
### The Skill-Creator Pattern
A "meta-skill" is a skill that writes other skills. After successfully completing a complex workflow, invoke the `skill-creator` meta-skill (or prompt the agent directly) to codify the workflow.
**Trigger:**
```
We just successfully [completed task]. This workflow is repeatable.
Create a new skill in .claude/skills/[name]/ that captures this workflow
so it can be triggered automatically next time.
```
The agent should:
1. Identify the steps performed
2. Extract the trigger phrases (what prompted the original task)
3. Write a `SKILL.md` with imperative instructions
4. Include exact commands, file paths, and validation steps
5. Run `python scripts/package_skill.py .claude/skills/[name]` to validate
### Reflexion Loops
For complex tasks, build in a self-critique step:
```
Before finalizing this implementation:
1. Review what you just produced against the constraints in AGENTS.md
2. Identify any violations of the project conventions
3. Fix them, then confirm the implementation is compliant
```
This prevents the agent from bypassing AGENTS.md rules during long edits.
---
## Strategy 7: Observability — Detecting When Agents Go Off-Track
Signs that agent configuration needs attention:
| Signal | Likely Cause | Action |
|--------|-------------|--------|
| Agent uses wrong package manager | Missing/wrong command in AGENTS.md | Update Setup section |
| Agent creates files in wrong location | Missing directory map in AGENTS.md | Add Key Directories section |
| Agent suggests deprecated patterns | Stale skill or AGENTS.md | Version-check and update |
| Agent ignores existing conventions | Convention not documented | Add to AGENTS.md Conventions |
| Skill never triggers automatically | Description too vague | Add specific trigger phrases |
| Skill triggers for wrong tasks | Description too broad | Add "Do NOT use for X" exclusions |
| Same mistake recurs across sessions | Not documented after previous fix | Re-run error → AGENTS.md fix → commit |
### Minimal Observability Setup
Track agent errors in a lightweight log alongside ADRs:
```
docs/
└── agent-learnings/
├── 2026-01-15-wrong-import-paths.md
├── 2026-01-22-missing-migration-step.md
└── TEMPLATE.md
```
Template:
```markdown
# Agent Learning: [Date]
## Mistake Observed
[What the agent did wrong]
## Root Cause
[Which instruction was missing or incorrect]
## Fix Applied
[What was updated in AGENTS.md / skill]
## Verification
[How we confirmed the fix works]
```
---
## Emerging Approaches (Experimental)
### SAGE (Skill Augmented GRPO for Self-Evolution)
A reinforcement-learning framework where agents generate and refine skills across sequential tasks. Skills produced in earlier tasks are preserved in a library and reused in later tasks. Achieves ~8.9% improvement in goal completion with 59% fewer tokens. Not yet production-ready for typical codebases — relevant for teams building fine-tuned agents.
### SEAgent (Self-Evolving Agent)
Enables autonomous skill discovery for unseen software via a World State Model and Curriculum Generator. Trains a specialist-to-generalist approach from software documentation. Significantly outperforms static-prompt baselines on OSWorld benchmarks.
### Agentic Context Engineering
Agents acting as "context engineers" — rewriting and pruning their own context files to mitigate brevity bias and context collapse. Uses `start_focus` / `complete_focus` checkpoints where intermediate reasoning is compressed into a persistent "knowledge block," reducing token usage by 20%+ without accuracy loss.
For practical projects today, the human-curated approaches in Strategies 1–6 above remain more reliable and easier to audit.
SKILL.md
---
name: ai-coding-agent-setup
description: Configures AI agents (GitHub Copilot, Claude Code, Cursor, Codex) to understand a codebase and self-improve as the project evolves. Use when setting up a new project for AI-assisted development, onboarding AI agents to an existing repo, creating AGENTS.md, configuring MCP servers for code navigation, packaging project workflows as agent skills, or establishing self-improvement feedback loops. Covers AGENTS.md authoring, skill packaging, MCP configuration, context management, and living-documentation strategies.
metadata:
version: 1.0.0
tags: [agents, ai, codebase, mcp, agents-md, self-improvement]
---
# AI Coding Agent Setup
Configure AI agents to deeply understand a codebase and continuously improve as the project grows. This skill covers the three-layer architecture: **AGENTS.md** for project identity, **agent skills** for packaged workflows, and **MCP servers** for live tool access — plus self-improvement strategies to prevent context rot.
## Quick Reference Table
| Goal | Load Resource | Key Concepts |
|------|---------------|--------------|
| Create or improve AGENTS.md | `resources/agents-md-guide.md` | project identity, hierarchical discovery, conventions |
| Package project workflows as skills | `resources/agent-skills-architecture.md` | progressive disclosure, SKILL.md, trigger phrases |
| Add IDE/codebase tools via MCP | `resources/mcp-codebase-tools.md` | Bifrost, vscode-mcp-server, semantic search |
| Reduce context rot, build feedback loops | `resources/self-improvement-patterns.md` | living docs, meta-skills, context compression |
---
## Orchestration Protocol
### Phase 1 — Classify the Request
Determine which layer the user needs help with:
- **"Set up AI for my project"** → start with `agents-md-guide.md`, then assess if skills and MCP are needed
- **"AI keeps making the same mistake"** → `self-improvement-patterns.md` (feedback loops section)
- **"AI can't navigate my code / doesn't understand the structure"** → `mcp-codebase-tools.md`
- **"How do I package this workflow for AI reuse?"** → `agent-skills-architecture.md`
- **"Agent ignores my conventions"** → `agents-md-guide.md` (conventions and enforcement section)
### Phase 2 — Select Resource
Load the relevant resource file from the table above. Most setups require `agents-md-guide.md` as the foundation, with other resources added on top.
### Phase 3 — Execute
Follow the specific guidance in the loaded resource. Output actionable file content (AGENTS.md, SKILL.md, mcp.json) — not just advice.
---
## Common Task Workflows
### Workflow 1: New Project AI Setup (15 minutes)
1. Load `resources/agents-md-guide.md` → create `AGENTS.md` at repo root using the template
2. Add project overview, build commands, test instructions, code conventions
3. Configure `.vscode/mcp.json` with at minimum the Bifrost server (see `mcp-codebase-tools.md`)
4. If the project has complex, repeatable workflows → package them as skills (see `agent-skills-architecture.md`)
5. Commit all AI configuration files to version control alongside the codebase
### Workflow 2: AGENTS.md for an Existing Repo
1. Load `resources/agents-md-guide.md`
2. Audit the existing `README.md` for technical content that belongs in AGENTS.md
3. Extract: build commands, test scripts, folder structure map, conventions → move to AGENTS.md
4. For monorepos: create root AGENTS.md + sub-directory AGENTS.md files for each package
5. Add a "pointer" to `CLAUDE.md` or `copilot-instructions.md` referencing AGENTS.md
### Workflow 3: Preventing Agent Mistakes from Recurring
1. Identify the pattern: did the agent use a wrong pattern/file/command?
2. Load `resources/self-improvement-patterns.md`
3. Update the relevant `AGENTS.md` section with an explicit correction
4. If the mistake is workflow-specific → update or create a skill (`agent-skills-architecture.md`)
5. Test: ask the agent to perform the same task; verify it now follows the corrected instruction
### Workflow 4: Giving Agents Deep Code Navigation
1. Load `resources/mcp-codebase-tools.md`
2. Install Bifrost VS Code extension (provides call hierarchy, find usages, go-to-definition)
3. Add server config to `.vscode/mcp.json`
4. For semantic search → configure a vector-store MCP server (Qdrant or Azure AI Search)
5. Document MCP tool names in AGENTS.md so the agent knows when to use them
### Workflow 5: Self-Improving Agent Configuration
1. After each significant debugging session, ask the agent: "What should we add to AGENTS.md to prevent this?"
2. Review proposed update → approve and commit
3. Monthly: use a "review" prompt against `self-improvement-patterns.md` to audit all config files
4. Over time: stale instructions become "context rot" — prune or update them proactively
---
## Resource Summaries
| Resource | Purpose | Line Count |
|----------|---------|-----------|
| `resources/agents-md-guide.md` | AGENTS.md template, recommended sections, hierarchical discovery, comparison with CLAUDE.md/copilot-instructions.md | ~350 |
| `resources/agent-skills-architecture.md` | How to package project workflows as reusable SKILL.md-based skills with progressive disclosure | ~300 |
| `resources/mcp-codebase-tools.md` | MCP servers for live code navigation: Bifrost, vscode-mcp-server, semantic search, GitHub MCP | ~280 |
| `resources/self-improvement-patterns.md` | Context rot prevention, feedback loops, living documentation, meta-skills, memory architecture | ~300 |
---
## Best Practices
- **Identity vs. Capability**: Use AGENTS.md for static project rules (identity); use skills for dynamic, executable workflows (capability). Do not put workflow logic in AGENTS.md.
- **Commit AI config to version control**: AGENTS.md, skills, and mcp.json are first-class project files — track them in git alongside code.
- **Hierarchical AGENTS.md for monorepos**: Root file holds global rules; sub-directory files override for local packages. Closest file wins.
- **Treat agent mistakes as documentation bugs**: Every repeated agent error is a missing or incorrect instruction in AGENTS.md or a skill. Fix the docs, not just the output.
- **Pointer pattern**: In `CLAUDE.md` write `Read @AGENTS.md` — avoids duplication across tool-specific instruction files.
- **Progressive disclosure in skills**: Keep SKILL.md under 5,000 words; move heavy reference content to `resources/` files loaded only when needed.
- **Name MCP tool names explicitly**: Include exact MCP tool names in AGENTS.md so agents know which tools to invoke for code navigation tasks.
---
## External References
- [AGENTS.md Open Standard — AAIF](https://agentprotocol.ai/agents-md)
- [Anthropic Skills Documentation](https://docs.anthropic.com/en/docs/agents-and-tools/agent-skills)
- [Model Context Protocol Specification](https://modelcontextprotocol.io)
- [Bifrost VS Code MCP Extension](https://marketplace.visualstudio.com/items?itemName=bifrost.bifrost-mcp)
- [GitHub MCP Server](https://github.com/github/github-mcp-server)