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)

Load resources/agents-md-guide.md → create AGENTS.md at repo root using the template
Add project overview, build commands, test instructions, code conventions
Configure .vscode/mcp.json with at minimum the Bifrost server (see mcp-codebase-tools.md)
If the project has complex, repeatable workflows → package them as skills (see agent-skills-architecture.md)
Commit all AI configuration files to version control alongside the codebase

Workflow 2: AGENTS.md for an Existing Repo

Load resources/agents-md-guide.md
Audit the existing README.md for technical content that belongs in AGENTS.md
Extract: build commands, test scripts, folder structure map, conventions → move to AGENTS.md
For monorepos: create root AGENTS.md + sub-directory AGENTS.md files for each package
Add a "pointer" to CLAUDE.md or copilot-instructions.md referencing AGENTS.md

Workflow 3: Preventing Agent Mistakes from Recurring

Identify the pattern: did the agent use a wrong pattern/file/command?
Load resources/self-improvement-patterns.md
Update the relevant AGENTS.md section with an explicit correction
If the mistake is workflow-specific → update or create a skill (agent-skills-architecture.md)
Test: ask the agent to perform the same task; verify it now follows the corrected instruction

Workflow 4: Giving Agents Deep Code Navigation

Load resources/mcp-codebase-tools.md
Install Bifrost VS Code extension (provides call hierarchy, find usages, go-to-definition)
Add server config to .vscode/mcp.json
For semantic search → configure a vector-store MCP server (Qdrant or Azure AI Search)
Document MCP tool names in AGENTS.md so the agent knows when to use them

Workflow 5: Self-Improving Agent Configuration

After each significant debugging session, ask the agent: "What should we add to AGENTS.md to prevent this?"
Review proposed update → approve and commit
Monthly: use a "review" prompt against self-improvement-patterns.md to audit all config files
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.

ai-coding-agent-setup