# agent-copy

Adopt this skill: https://proskills.md/skills/other/shane9coy-agent-skill-architecture-guide-skills-agent-copy

Page: https://proskills.md/skills/other/shane9coy-agent-skill-architecture-guide-skills-agent-copy
This document is the public skill bundle for that page. It contains SKILL.md and every helper file the catalog carries. No login is required.

## File: skills/agent-copy/SKILL.md
size: 5013
sha: 3d7fd70563811162f9826bb5ddf2e22786f09333
upstream: https://github.com/shane9coy/agent-skill-architecture-guide/blob/main/skills/agent-copy/SKILL.md

````text
---
name: agent-copy
description: Use when the user asks to copy, install, refresh, or update a repo-root AGENTS.md file from their canonical global instruction source. Also use when the user says "agent copy" or wants a repo-local AGENTS.md with global operating rules plus project-specific guidance.
metadata:
  short-description: Copy canonical instructions into a repo and append repo-specific guidance
---

# Agent Copy

This skill creates or refreshes a repo-root `AGENTS.md` file by copying the user's canonical global agent instructions, then appending a repo-specific guide for the current project.

Architecture:

```text
canonical global instructions -> repo-local AGENTS.md -> repo-specific tail
```

Use one `agent-copy` skill for this workflow. Do not create separate runtime-specific variants such as `agent-copy-codex`, `agent-copy-claude`, or `agent-copy-cursor`; change the source path instead.

Default source:

- `$HOME/.codex/AGENTS.md`

Default target:

- `./AGENTS.md`

Codex is the default because this repo demonstrates a Codex-first setup. If the user's canonical instructions live somewhere else, use that source path instead. Examples include a Claude project instruction file, an OpenCode context file, or another agent-compatible global instruction file.

Only `AGENTS.md` files should be created, copied, or updated unless the user explicitly asks for another instruction file.

## Core Rule

The repo-root `./AGENTS.md` file must:

1. Start with an exact copy of the selected canonical global instruction source.
2. Append a repo-specific tail section titled `## Repo-Specific Guide`.
3. Include only repo facts from filesystem inspection or the user's answers.
4. Mark unknowns as `TBD - ask the user before implementing this area.`

Do not paraphrase, summarize, or partially copy the canonical source file.

## Workflow

### 1. Confirm The Canonical Source File

Check for the default source:

```bash
test -f "$HOME/.codex/AGENTS.md" && echo "$HOME/.codex/AGENTS.md"
```

If the file does not exist and the user wants Codex as the canonical source, tell the user to install the repo's root `AGENTS.md` template into their Codex root first:

```bash
mkdir -p "$HOME/.codex"
cp AGENTS.md "$HOME/.codex/AGENTS.md"
```

If the user is not using Codex, ask for the exact path to their equivalent canonical instruction file before copying anything.

### 2. Ground In The Repo

Run before editing:

```bash
pwd
git status --short --branch
git branch --show-current
git remote -v
find . -maxdepth 2 -type f \( -name 'package.json' -o -name 'pnpm-lock.yaml' -o -name 'package-lock.json' -o -name 'yarn.lock' -o -name 'pyproject.toml' -o -name 'requirements.txt' -o -name 'go.mod' -o -name 'Cargo.toml' -o -name '.env.example' -o -name 'README.md' -o -name 'DESIGN.md' \) -print
find . -maxdepth 3 \( -name AGENTS.md -o -name CLAUDE.md \) -print
```

Scan and read existing repo docs/manifests before writing repo-specific details.

### 3. Preserve Existing Repo-Specific Content

If `./AGENTS.md` already exists:

- Read it first.
- Preserve useful repo-specific guidance unless the user asked to replace it.
- Refresh the global preamble from the selected canonical source.
- Keep the repo-specific tail after the global preamble.

If existing repo instructions conflict with the selected canonical source, keep the canonical source rules unless the user explicitly says the repo is an exception.

### 4. Write The Repo-Specific Tail

Append this section after the global preamble. Populate known fields from the user's project description, `README.md`, `DESIGN.md`, package manifests, lockfiles, env examples, app directory structure, existing scripts, and tests.

Never invent production credentials, live deployment state, database schema, auth policy, or external integrations.

```md
## Repo-Specific Guide

### Project Overview

### Product Goal

### Audience / Users

### Key Directories / Docs / Scripts

### Stack / Architecture

### Local Dev Commands

### Build / Test / Verification

### Branch / Git Workflow

### Boundaries / Do Not Touch

### Implementation Notes
```

## Verification

After writing:

```bash
SOURCE_AGENTS="${SOURCE_AGENTS:-$HOME/.codex/AGENTS.md}"
head -n "$(wc -l < "$SOURCE_AGENTS")" ./AGENTS.md | cmp "$SOURCE_AGENTS" -
rg -n "Repo-Specific Guide|Project Overview|Product Goal|Stack / Architecture|Build / Test / Verification|Boundaries / Do Not Touch|Implementation Notes" ./AGENTS.md
git status --short --branch
```

If a non-default source was used, set `SOURCE_AGENTS` to that path before verification.

Report whether the global preamble verification passed.

## Handoff

Final response should include:

- files created or updated
- which canonical source file was used
- whether the global preamble matches the source
- which repo-specific sections were populated
- which sections remain blank or need user confirmation
- current git status

Commit only when the user explicitly asked for commit/push or the current task includes publishing.
````

## File: README.md
upstream: https://github.com/shane9coy/agent-skill-architecture-guide/blob/main/README.md

````text
# Agent Skills Architecture Guide

![Agent Skills Architecture Guide cover](assets/title-cover.png)

📄 Get the Full Guide

[Download the Agent Skills Architecture Guide v2 PDF](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](https://github.com/shane9coy/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:

```text
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
   - skills/new-mcp-builder
4. Default Codex skills target: ~/.codex/skills/
5. Claude Code skills example: ~/.claude/skills/
6. Do not overwrite an existing AGENTS.md or skill folder without showing me what will change first.
7. Verify the installed files exist and report the final paths.
```

### Manual Install

Codex is the default example in this repo. The manual install copies:

```text
AGENTS.md -> ~/.codex/AGENTS.md
skills/*  -> ~/.codex/skills/
```

Run from the directory where you want to download the repo:

```bash
git clone https://github.com/shane9coy/Agent-Skill-Architecture-Guide.git
cd Agent-Skill-Architecture-Guide

mkdir -p "$HOME/.codex" "$HOME/.codex/skills"

cp AGENTS.md "$HOME/.codex/AGENTS.md"
cp -R skills/agent-copy "$HOME/.codex/skills/"
cp -R skills/new-skill-builder "$HOME/.codex/skills/"
cp -R skills/new-mcp-builder "$HOME/.codex/skills/"
```

Then open `~/.codex/AGENTS.md` and replace:

- `<YOUR_GIT_AUTHOR_NAME>`
- `<YOUR_GIT_AUTHOR_EMAIL>`
- `<YOUR_GITHUB_USERNAME>`

Claude Code users can use the same repo files, but the destination folders are different. Common examples:

```text
Claude skills folder: ~/.claude/skills/
Claude project instructions: CLAUDE.md or the project instruction file your Claude setup uses
```

Keep the same model no matter which agent you use:

```text
canonical global instructions -> repo-local AGENTS.md -> repo-specific tail
```

## Recommended Workflow

1. Install `AGENTS.md` globally so every agent session starts with the same operating rules.
2. Install `agent-copy` so your agent can create repo-local `AGENTS.md` files without manual copy/paste.
3. Run `agent-copy` inside each important repo so local sessions have a reliable fallback.
4. Add repo-specific guidance underneath the global rules: stack, commands, branch rules, build/test flow, project boundaries, and known risks.
5. Install `new-skill-builder` when you want your agent to create or validate skills.
6. Install `new-mcp-builder` when you want your agent to plan or build MCP integrations.

After installing `agent-copy`, open a target project and ask your agent:

```text
Use agent-copy to create or refresh this repo's AGENTS.md from my canonical global instructions, then add repo-specific guidance based on the files in this project.
```

If your canonical source is not `~/.codex/AGENTS.md`, provide the exact source path:

```text
Use agent-copy with SOURCE_AGENTS=/path/to/my/global/instructions.md to create or refresh this repo's AGENTS.md, then add repo-specific guidance based on the files in this project.
```

## What's Inside

```text
Agent-Skill-Architecture-Guide/
├── AGENTS.md
├── Agent-Skills-Architecture-Guide.md
├── Agent-Skills-Architecture-Guide-v2.pdf
├── README.md
├── LICENSE
└── skills/
    ├── agent-copy/
    │   └── SKILL.md
    ├── new-mcp-builder/
    │   ├── SKILL.md
    │   └── references/
    └── new-skill-builder/
        ├── SKILL.md
        └── references/
```

## What The Skills Do

### `agent-copy`

Use this skill when you want an agent to:

- Copy your canonical global instructions into the current repo's `AGENTS.md`.
- Preserve the canonical rules exactly.
- Add repo-specific guidance based on the current codebase.
- Keep future repo-local `AGENTS.md` files aligned with your global operating rules.
- Use Codex's `~/.codex/AGENTS.md` by default, while allowing another canonical source path when needed.

### `new-skill-builder`

Use this skill when you want an agent to:

- Create a new skill from scratch.
- Install a skill from GitHub, ZIP, or Markdown.
- Validate a skill's structure and frontmatter.
- Audit an agent skill folder.
- Move long reference material out of `SKILL.md` and into `references/`.

### `new-mcp-builder`

Use this skill when you want an agent to:

- Plan a new MCP server.
- Define tool surfaces and schemas.
- Document setup, auth, environment variables, and safety boundaries.
- Create implementation notes for MCP integrations.
- Review an MCP server for usability and agent compatibility.

## Compatibility

This repo uses the shared AgentSkills pattern:

| Tool | Suggested instruction file | Suggested skill folder |
|------|----------------------------|------------------------|
| OpenAI Codex | `AGENTS.md` | `.codex/skills/`, `.agents/skills/`, or repo `skills/` |
| Hermes Agent | `AGENTS.md` or context files | Hermes skills path or repo `skills/` |
| KiloCode | `AGENTS.md` | `.kilocode/skills/` |
| Claude Code | `CLAUDE.md` / project instructions | `.claude/skills/` |
| OpenCode | tool-specific context | `.opencode/skills/` |
| Cursor / Windsurf / Cline | tool-specific context | compatible imported skills folder |
| Any AgentSkills agent | tool-specific context | repo `skills/` |

## Key Concepts

- **`AGENTS.md`**: Durable agent instructions for behavior, Git hygiene, contextual editing, stack conventions, verification, and handoff expectations.
- **`SKILL.md`**: Skill entrypoint with YAML frontmatter for discovery and Markdown body for instructions.
- **`ref
````
