Agent Skills Architecture Guide

📄 Get the Full Guide

Download the Agent Skills Architecture Guide v2 PDF

The guide covers agent folder structure, AGENTS.md, SKILL.md anatomy, frontmatter reference, orchestration folders, command-folder equivalents, self-hosted model notes, troubleshooting, and reusable skill patterns.

Copy the included AGENTS.md and skill file set into your canonical global agent folders, then replace the placeholder Git identity fields with your own name, email, and GitHub username.

AGENTS.md solves the following issues with your coding agent:

• Git branch chaos and generated branch pollution
• Agents treating Git branches like disposable sandboxes
• Context mangling and drift between passes
• Speed running without step by step updates or explaining architecture and the why behind it
• Yes-man loops and reflex apology responses; No more “You’re absolutely right!”
• Pausing after every section of a long prompt instead of finishing the full task
• Weak self-review and missed requirements from long or detailed prompts
• Overbuilding, bloated abstractions, and undocumented codebases

This repo now focuses on a simplified layout:

• AGENTS.md: public template for agent behavior, Git hygiene, contextual editing, implementation review, and handoff discipline.
• skills/agent-copy/: reusable skill for copying your canonical global instructions into any project repo and appending repo-specific guidance.
• skills/new-skill-builder/: reusable skill for creating, installing, validating, and auditing agent skills.
• skills/new-mcp-builder/: reusable skill for planning and building MCP server integrations.
• Agent-Skills-Architecture-Guide.md: Markdown source for the guide.
• Agent-Skills-Architecture-Guide-v2.pdf: PDF version of the guide.

For quick, optimized subagent execution after your base instructions are installed, also check out Subagent-Driven Development. It adds scoped workers, branch/worktree discipline, progress tracking, and review gates for multi-agent implementation work.

Install

The easiest install path is to give this repo to your coding agent and let it copy the instruction file and skills into the right local folders.

Copy this prompt into Codex, Claude Code, or another local coding agent:

Install the Agent Skills Architecture Guide into my local agent setup.

Repo: https://github.com/shane9coy/Agent-Skill-Architecture-Guide

Tasks:
1. Clone or download the repo.
2. Copy the repo's AGENTS.md into my canonical global agent instruction file.
   - Default Codex target: ~/.codex/AGENTS.md
   - If I use Claude Code or another agent, ask me to confirm the correct global instruction path before writing.
3. Copy these skills into my agent skills folder:
   - skills/agent-copy
   - skills/new-skill-builder