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

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

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
• Anthropic Skills Documentation
• Model Context Protocol Specification
• Bifrost VS Code MCP Extension
• GitHub MCP Server