skills.rest
davidsneighbour
davidsneighbourCOMMUNITY
Explore all skills by this author →
WebsiteGitHub

agent-instructions-audit

Audit and optimise repository agent instruction architecture and context cost.

1|Updated Aug 18, 2026
Search Tags:#audit#migration#claude.md#agents.md#repository maintenance#context cost#instruction architecture
One-click install
npx skills add https://github.com/davidsneighbour/clerkwork --skill agent-instructions-audit-davidsneighbour
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: agent-instructions-audit
Source: https://github.com/davidsneighbour/clerkwork/tree/main/skills/agent-instructions-audit
Command: npx skills add https://github.com/davidsneighbour/clerkwork --skill agent-instructions-audit-davidsneighbour

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve? Repository agent instructions often accumulate bloat: oversized AGENTS.md bootstrap files, legacy CLAUDE.md content, global applyTo scopes, and duplicated rules that inflate unconditional context cost and reduce reliability. This Skill audits that architecture and, when explicitly requested, restructures it. ## Core Features & Use Cases - Non-mutating audit mode: Classifies instruction material, estimates token costs, and reports findings with ERROR/WARN/INFO severity without changing files. - CLAUDE.md migration: Classifies legacy content as duplicate, bootstrap, scoped, reference, or skill material, migrates useful content, then removes the obsolete file. - Optimise mode: Moves rules between AGENTS.md, .agents/instructions/, and .agents/references/ with validated non-global applyTo scopes and discoverable task triggers. - Use Case: A repository has a 400-line CLAUDE.md and a bloated AGENTS.md. Run the audit to get a cost estimate and migration plan, then run optimise to cut bootstrap context while preserving all behaviour. ## Quick Start Use the agent-instructions-audit skill to audit this repository's agent instruction architecture and report context-cost savings.

Frequently Asked Questions about agent-instructions-audit

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I audit AGENTS.md and CLAUDE.md for context cost?▼

Run the audit mode, which reads AGENTS.md and any CLAUDE.md variants completely, classifies each instruction block, and reports byte counts with approximate token estimates. It also proposes a post-optimisation bootstrap size without modifying files.

How to migrate CLAUDE.md content to AGENTS.md?▼

The skill classifies every CLAUDE.md instruction as duplicate, bootstrap, scoped rule, reference, or skill material, then moves useful content into AGENTS.md, .agents/instructions/, or .agents/references/. CLAUDE.md is deleted only after all unique content is preserved elsewhere.

Does the audit modify repository files by default?▼

No, audit mode is strictly non-mutating and only reports findings with severity levels. Optimise mode edits instruction files only when the user explicitly asks to optimise, restructure, fix, migrate, or apply recommendations.

What applyTo scopes are invalid in agent instruction files?▼

Repository-wide scopes such as *, **, and **/* are prohibited and flagged as ERROR, along with effectively-global patterns covering most working files. Reference files must have no applyTo at all, and every scoped instruction needs a narrow pattern.

When should I use agent-align instead of this audit?▼

Use agent-align for structural alignment of AGENTS.md, .agents/instructions/, and .agents/references/ entry-point setup. This skill owns context-efficiency analysis, duplication removal, and CLAUDE.md migration, and delegates structural alignment work to agent-align.

Related Skills

Explore More Software Engineering Skills→
devantler-techdevantler-tech
2

agent-instructions

Architect a canonical AGENTS.md with tool-specific shims for Claude, Copilot, Cursor, Gemini, and Codex.

Official
Advanced
vltanskyvltansky
10

roast-my-agents-md

Audit AI instruction files for redundancy and ineffectiveness using static analysis and A/B testing.

Community
Advanced
fieldspherefieldsphere
37

update-readme

Generate repository READMEs with startup instructions and Mermaid architecture diagrams.

Official
Advanced
bmad-code-orgbmad-code-org
52.5k

bmad-project-context

Creates and maintains verified AGENTS.md instruction blocks for AI coding agents in a repository.

Official
Advanced