# Clean Up Agent Config > >- - **Type:** Skill - **Install:** `agentstack add skill-cboone-agent-harness-plugins-clean-up-agent-config` - **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior - **Seller:** [cboone](https://agentstack.voostack.com/s/cboone) - **Installs:** 0 - **Category:** [Agent Skills](https://agentstack.voostack.com/c/agent-skills) - **Latest version:** 0.1.0 - **License:** MIT - **Upstream author:** [cboone](https://github.com/cboone) - **Source:** https://github.com/cboone/agent-harness-plugins/tree/main/dist/codex/plugins/clean-up-agent-config/skills/clean-up-agent-config - **Website:** https://github.com/cboone/agent-harness-plugins ## Install ```sh agentstack add skill-cboone-agent-harness-plugins-clean-up-agent-config ``` Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent. ## About # Agent Config Cleanup Review, consolidate, and organize AI coding agent configuration and instruction files across four tools: Claude Code, OpenAI Codex, GitHub Copilot (CLI agent and code review), and OpenCode. ## Reference Documents Consult the reference files in this skill's `references/` directory for detailed information about each tool's file formats, precedence rules, and unique capabilities: - `references/agent-instruction-files.md` -- CLAUDE.md, AGENTS.md, copilot-instructions.md, SKILL.md comparison - `references/agent-config-files.md` -- settings.json, config.toml, opencode.json, VS Code settings comparison Read these references before starting work. They contain tool-specific details about file precedence, loading behavior, and cross-tool compatibility that inform every decision in this workflow. --- ## Target Structure The goal is a hub-and-spoke model: shared instructions in one canonical file, tool-specific configuration in each tool's hidden directory. ### Instruction files (the hub) Pick **one** scoped-instructions layout per repo. The two layouts below are mutually exclusive alternatives, not files that should coexist. **Flat layout** (convenient for one or two scoped files): ```text repo/ +-- AGENTS.md # Single source of truth (all tools) +-- CLAUDE.md -> AGENTS.md # Symlink for Claude Code +-- .claude/ | +-- rules/ | +-- *.md # Claude-specific rules (auto-loaded) +-- .github/ +-- copilot-instructions.md # Copilot repo-wide review rules +-- *.instructions.md # Copilot path-scoped rules ``` **Nested layout** (scales better when there are many scoped files, or to keep `.github/` uncluttered): ```text repo/ +-- AGENTS.md # Single source of truth (all tools) +-- CLAUDE.md -> AGENTS.md # Symlink for Claude Code +-- .claude/ | +-- rules/ | +-- *.md # Claude-specific rules (auto-loaded) +-- .github/ +-- copilot-instructions.md # Copilot repo-wide review rules +-- instructions/ +-- *.instructions.md # Copilot path-scoped rules ``` Both are read by Copilot and both honor `applyTo` frontmatter. Choose based on how many scoped files the repo needs and stick with that choice; do not mix the two. ### Config files (the spokes) ```text repo/ +-- .mcp.json # Shared MCP servers (Claude Code, OpenCode) +-- opencode.json # OpenCode project config (if used) +-- .claude/ | +-- settings.json # Team-shared: permissions, hooks, env vars | +-- settings.local.json # Personal: model, telemetry (gitignored) +-- .codex/ +-- config.toml # Codex project config (if used) ``` ### What goes where | Content type | Location | Reason | | ---------------------------------------------- | ---------------------------------------------------------------------------------------- | ------------------------------------------------------------------------- | | Project overview, tech stack, commands | `AGENTS.md` | Read by all four tools | | Directory-scoped conventions | Subdirectory `AGENTS.md` (Codex, Copilot) and `CLAUDE.md` or symlink per subdir (Claude) | Scoped by directory; Claude requires `CLAUDE.md` in each scoped directory | | Claude-specific (MCP hints, subagent patterns) | `.claude/rules/*.md` | Auto-loaded, Claude-only | | Copilot code review rules | `.github/copilot-instructions.md` | Copilot code review agent | | File-type-specific review rules | `.github/*.instructions.md` or `.github/instructions/*.instructions.md` | Copilot's `applyTo` glob scoping | | Team permissions and hooks | `.claude/settings.json` | Committed, shared with team | | Personal model/telemetry/privacy | `.claude/settings.local.json` | Gitignored, personal | | MCP servers (team) | `.mcp.json` at project root | Committed, shared | | MCP servers (personal) | `.claude/settings.local.json` | Gitignored | | Codex sandbox/approval policy | `.codex/config.toml` | Codex-specific | | OpenCode model/instruction paths | `opencode.json` | OpenCode-specific | --- ## Workflow ### Phase 1: Audit Scan the repository for all known agent-related files. #### Instruction files to check - `AGENTS.md` (root and subdirectories) - `AGENTS.override.md` (root and subdirectories) - `CLAUDE.md` (root and subdirectories) - `.claude/CLAUDE.md` - `.claude/rules/*.md` - `.github/copilot-instructions.md` - `.github/*.instructions.md` (flat path-scoped layout) - `.github/instructions/*.instructions.md` (nested path-scoped layout) - `.github/prompts/*.prompt.md` - `.github/chatmodes/*.chatmode.md` - `.github/agents/*.agent.md` #### Config files to check - `.claude/settings.json` - `.claude/settings.local.json` - `.mcp.json` - `.codex/config.toml` - `opencode.json` #### Also check - **Symlinks:** Run `ls -la CLAUDE.md AGENTS.md` to detect symlinks and their targets. - **Gitignore:** Verify `.claude/settings.local.json` is gitignored (Claude Code does this automatically, but confirm). - **Project characteristics:** Note the primary languages, directory structure, build tools, and monorepo indicators. These inform AGENTS.md content and Copilot path-scoped instructions. Report which files exist, which are missing, which are symlinks, and what each file contains at a high level. ### Phase 2: Analyze Read each found file and categorize its contents into: 1. **Shared instructions** -- project overview, tech stack, commands, coding conventions that all tools should know 1. **Claude-specific instructions** -- MCP server usage hints, subagent patterns, `@import` references, Claude-only tool restrictions 1. **Copilot-specific instructions** -- code review rules, PR description conventions, `excludeAgent` scoping 1. **Tool config** -- permissions, hooks, model settings, environment variables, sandbox policies 1. **Personal config** -- settings that belong in gitignored files, not shared config 1. **Duplicated content** -- instructions repeated across multiple files 1. **Misplaced content** -- team settings in personal files or personal settings in team files #### Settings split analysis (Claude Code) For `.claude/settings.json` and `.claude/settings.local.json`, specifically classify each setting: **Belongs in settings.json (team-shared, committed):** - `$schema` reference - `permissions.allow` rules for team-standard tool patterns - `permissions.deny` rules for protecting sensitive paths - `hooks` definitions (pre/post tool use enforcement) - `env` vars for team conventions (`attribution`, survey suppression, etc.) - `attribution` settings **Belongs in settings.local.json (personal, gitignored):** - Model override env vars (`ANTHROPIC_MODEL`, `CLAUDE_CODE_MAX_TURNS`) - Telemetry/privacy env vars (`DISABLE_TELEMETRY`, `DISABLE_ERROR_REPORTING`) - Personal MCP servers in `mcpServers` - Personal permission overrides - `spinnerTipsEnabled` and similar personal preferences - Experimental settings being tested before proposing to the team Note: Claude Code writes to `settings.local.json` by default when users change settings interactively. This means team-appropriate settings often end up in the local file and need to be moved to `settings.json`. #### Scoped Copilot instructions analysis For each `.github/*.instructions.md` and `.github/instructions/*.instructions.md` file, check: 1. **Frontmatter present.** Each scoped file MUST start with YAML frontmatter containing `applyTo: ""`. Flag files missing the frontmatter or the `applyTo` key. 1. **Top-level heading matches scope.** Each scoped file should have a top-level heading naming what it scopes to (e.g., `# Lean PR Review Instructions`, `# TypeScript Frontend Instructions`). Flag files with no top-level heading or one that does not reflect the scope. 1. **Glob is non-empty.** Run a glob match against the repo (e.g., via `git ls-files` or a Glob tool call) to confirm the `applyTo` pattern matches at least one tracked file. Flag scoped files whose glob matches nothing as **stale**: either the code they targeted has been removed, the glob was mistyped, or the file was copied from another repo without being updated. 1. **No silent overlap with sibling scoped files.** Compare each `applyTo` glob to every other scoped file's `applyTo`. If two scoped files match the same file (e.g., one has `**/*.ts` and another has `**/*.tsx`, but a `.ts` file matches the first only -- fine; but two files both globbing `**/*.lean` is a conflict). Flag overlaps where two files would both apply to the same source file without a clear separation of concerns. 1. **Cross-references with the general file.** The general `.github/copilot-instructions.md` should mention the scoped files (so a contributor reading the general file discovers them); each scoped file should reference the general file for repo-wide context. Flag missing cross-references. 1. **Layout consistency.** If the repo uses both `.github/*.instructions.md` (flat) and `.github/instructions/*.instructions.md` (nested), flag the inconsistency and propose consolidating on one layout. ### Phase 3: Propose Changes Present the user with a concrete plan before making any changes: 1. **New files** -- what will be created, with a summary of contents 1. **Content moves** -- what content is moving between files, with before/after locations 1. **Consolidations** -- duplicated content being merged into one location 1. **Symlinks** -- what symlinks will be created or updated 1. **Deletions** -- files being replaced by symlinks or removed 1. **Config split** -- settings moving between settings.json and settings.local.json Show the proposed final file tree and get explicit user approval before proceeding. #### Symlink strategy Recommend `CLAUDE.md -> AGENTS.md` (AGENTS.md is the real file) when: - AGENTS.md already exists, or - Starting fresh (AGENTS.md is the cross-tool standard), or - The team uses multiple AI tools Recommend keeping CLAUDE.md as the real file (no symlink) when: - The team exclusively uses Claude Code and the user prefers the CLAUDE.md name - CLAUDE.md has extensive Claude-specific `@import` references that other tools wouldn't understand Follow whichever recommendation applies. The Phase 3 plan approval gives the user a chance to override the choice. ### Phase 4: Implement Execute the approved plan in this order: #### 4a. AGENTS.md Create or update AGENTS.md with shared instructions consolidated from all sources. Structure with clear headings: ```markdown # Project Name ## Overview Brief project description and key architectural decisions. ## Development Environment - Package manager and runtime versions - Key commands: build, test, lint, dev server ## Code Conventions - Language-specific patterns and preferences - Error handling approach - Testing conventions and location ## Git Workflow - Branch naming and commit format - Pre-commit requirements ``` **Keep it under 200 lines.** If more detail is needed, keep it in `.claude/rules/` files (Claude) or reference supporting docs. **Do not include** code style rules that linters enforce (formatting, indentation). Those belong in `.editorconfig`, `.prettierrc`, etc. #### 4b. CLAUDE.md symlink ```bash # If AGENTS.md is the source of truth: ln -sfn AGENTS.md CLAUDE.md ``` If CLAUDE.md previously had Claude-specific content, extract those sections to `.claude/rules/` files before replacing with the symlink. #### 4c. .claude/rules/ (Claude-specific) Move Claude-specific instructions to focused rule files: ```text .claude/rules/ +-- mcp-servers.md # How to use project MCP servers +-- testing.md # Claude-specific test runner patterns +-- security.md # Paths to protect, secrets handling ``` Each file is auto-loaded alongside CLAUDE.md. Keep files focused on one topic. Only create these if there are genuine Claude-specific instructions. Do not create empty rule files. #### 4d. .claude/settings.json (team-shared) Create or update with team-appropriate settings: ```json { "$schema": "https://json.schemastore.org/claude-code-settings.json", "permissions": { "allow": [], "deny": [] } } ``` Move team settings here from settings.local.json. Remove personal settings to settings.local.json. #### 4e. .claude/settings.local.json (personal) Move personal settings here from settings.json. Verify it is gitignored. If settings.local.json does not exist and there are no personal settings to move, do not create an empty file. #### 4f. .github/copilot-instructions.md Create or update with Copilot-specific content. This file should NOT duplicate AGENTS.md. Instead, use the pointer pattern: a cross-reference to AGENTS.md plus Copilot-specific PR review rules. ```markdown # GitHub Copilot Instructions For full project conventions, see AGENTS.md in the repository root. ## Scoped Instructions Flat-layout example -- path-scoped Copilot instructions live alongside this file: - [`lean.instructions.md`](lean.instructions.md) -- Lean source files (`**/*.lean`). - [`ts.instructions.md`](ts.instructions.md) -- TypeScript files (`**/*.ts`, `**/*.tsx`). If the repo uses the nested layout under `.github/instructions/`, link to `instructions/lean.instructions.md` and `instructions/ts.instructions.md` instead. ## PR Review When reviewing pull requests, do not flag the following patterns as issues. Each is an intentional project convention: - **Convention name**: Brief explanation of why this is intentional. ``` **Cross-reference the scoped files.** When the repo has any `.github/*.instructions.md` (or `.github/instructions/*.instructions.md`) files, list them in a `## Scoped Instructions` section in the general file with their `applyTo` glob noted. This makes the scoped surface discoverable to humans reading the general file. Omit the section if there are no scoped files. **Keep concise.** GitHub recommends keeping instruction files short and putting the most important rules first. Start with a focused set of review rules and add more iteratively. **The "do not flag" pattern.** The PR Review section documents project conventions that Copilot commonly misidentifies as issues during PR reviews. Each item uses the bold-key format (`**Convention name**: explanation`). To populate this section for an existing project: 1. Check the project's PR history for recu … ## Source & license This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code. - **Author:** [cboone](https://github.com/cboone) - **Source:** [cboone/agent-harness-plugins](https://github.com/cboone/agent-harness-plugins) - **License:** MIT - **Homepage:** https://github.com/cboone/agent-harness-plugins Install and usage instructions live in the source repository linked above. ## Pricing - **Free** — Free ## Security capabilities Automated source analysis of v0.1.0 — what this tool can access: - **Network access:** no - **Filesystem access:** no - **Shell / process execution:** no - **Environment & secrets:** no - **Dynamic code execution:** no *"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.* ## Versions - **0.1.0** — security scan: passed — Imported from the upstream source. ## Links - Listing page: https://agentstack.voostack.com/l/skill-cboone-agent-harness-plugins-clean-up-agent-config - Seller: https://agentstack.voostack.com/s/cboone - Browse the marketplace: https://agentstack.voostack.com/browse --- Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.