| 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)
- 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.
External References
