auditing-claude-instructions
Use this skill when evaluating, auditing, reviewing, or optimizing CLAUDE.md files (or agents.md files) for effectiveness. Triggers on "review my CLAUDE.md", "optimize my claude instructions", "is my CLAUDE.md effective", "audit my claude config", or when users share their CLAUDE.md content for feedback. Evaluates files against a research-backed rubric covering minimality, tooling, codebase overviews, novelty, and authorship.
Best use case
auditing-claude-instructions is best used when you need a repeatable AI agent workflow instead of a one-off prompt.
Use this skill when evaluating, auditing, reviewing, or optimizing CLAUDE.md files (or agents.md files) for effectiveness. Triggers on "review my CLAUDE.md", "optimize my claude instructions", "is my CLAUDE.md effective", "audit my claude config", or when users share their CLAUDE.md content for feedback. Evaluates files against a research-backed rubric covering minimality, tooling, codebase overviews, novelty, and authorship.
Teams using auditing-claude-instructions should expect a more consistent output, faster repeated execution, less prompt rewriting.
When to use this skill
- You want a reusable workflow that can be run more than once with consistent structure.
When not to use this skill
- You only need a quick one-off answer and do not need a reusable workflow.
- You cannot install or maintain the underlying files, dependencies, or repository context.
Installation
Claude Code / Cursor / Codex
Manual Installation
- Download SKILL.md from GitHub
- Place it in
.claude/skills/auditing-claude-instructions/SKILL.mdinside your project - Restart your AI agent — it will auto-discover the skill
How auditing-claude-instructions Compares
| Feature / Agent | auditing-claude-instructions | Standard Approach |
|---|---|---|
| Platform Support | Not specified | Limited / Varies |
| Context Awareness | High | Baseline |
| Installation Complexity | Unknown | N/A |
Frequently Asked Questions
What does this skill do?
Use this skill when evaluating, auditing, reviewing, or optimizing CLAUDE.md files (or agents.md files) for effectiveness. Triggers on "review my CLAUDE.md", "optimize my claude instructions", "is my CLAUDE.md effective", "audit my claude config", or when users share their CLAUDE.md content for feedback. Evaluates files against a research-backed rubric covering minimality, tooling, codebase overviews, novelty, and authorship.
Where can I find the source code?
You can find the source code on GitHub using the link provided at the top of the page.
Related Guides
Best AI Skills for Claude
Explore the best AI skills for Claude and Claude Code across coding, research, workflow automation, documentation, and agent operations.
ChatGPT vs Claude for Agent Skills
Compare ChatGPT and Claude for AI agent skills across coding, writing, research, and reusable workflow execution.
SKILL.md Source
# Auditing Claude Instructions
Evaluate CLAUDE.md and agents.md files against a research-backed rubric. Score each file on 5 criteria (4 points each, 20 max) and provide actionable recommendations.
## Evaluation Process
### 1. Locate the File
```bash
fd -H "CLAUDE.md" .
fd -H "agents.md" .
```
### 2. Gather Context
Before scoring, check what other documentation exists in the repo:
```bash
fd -H "README.md" .
fd -d 1 . docs/ 2>/dev/null
```
This informs the Novelty vs. Redundancy criterion—instructions that duplicate README content are actively harmful.
### 3. Score Against Rubric
Apply each criterion from `./scoring-rubric.md`. For every criterion, assign a score of 4 (Excellent), 3 (Satisfactory), or 1 (Needs Improvement).
**The 5 criteria:**
1. **Minimality of Requirements** — Only what's needed to interact with the repo. Extra instructions increase exploration time and raise inference costs by 20%+.
2. **Specification of Tooling and Environment** — Explicit tool names and commands. Agents strictly adhere to specified tools.
3. **Absence of Codebase Overviews** — No enumerated directories or file summaries. Research shows overviews don't help agents find files faster and can cause models to waste steps re-reading context.
4. **Novelty vs. Redundancy** — Unique operational context not found elsewhere in the repo. Redundancy with README/docs only helps if all other docs are deleted.
5. **Authorship and Curation** — Human-written or heavily human-edited. Purely LLM-generated files reduce task success rates by 3% on average.
### 4. Generate Report
## Output Format
```markdown
## CLAUDE.md Audit Report
### Scores
| Criterion | Score | Rating |
|-----------|-------|--------|
| Minimality of Requirements | X/4 | [Excellent/Satisfactory/Needs Improvement] |
| Tooling and Environment | X/4 | [Excellent/Satisfactory/Needs Improvement] |
| Absence of Codebase Overviews | X/4 | [Excellent/Satisfactory/Needs Improvement] |
| Novelty vs. Redundancy | X/4 | [Excellent/Satisfactory/Needs Improvement] |
| Authorship and Curation | X/4 | [Excellent/Satisfactory/Needs Improvement] |
| **Total** | **X/20** | |
### Findings
#### [Criterion Name] — [Score]/4
**Evidence**: [Quote or reference specific lines]
**Issue**: [What's wrong and why it matters, citing research]
**Fix**: [Concrete rewrite or removal]
### Recommended Rewrite
[If score < 16, provide a complete rewritten version of the file]
```
## Scoring Thresholds
- **17-20**: Well-optimized file. Minor tweaks only.
- **13-16**: Functional but has clear areas for improvement.
- **9-12**: Significant issues reducing agent effectiveness.
- **5-8**: File is likely hurting more than helping. Consider a full rewrite.
## Key Principles
- **Cut aggressively**: For every line, ask "Would removing this cause the agent to make mistakes?" If no, cut it.
- **Commands over prose**: Replace explanatory paragraphs with runnable commands.
- **Detect LLM generation**: Watch for telltale signs—exhaustive file trees, generic advice ("write clean code"), walls of boilerplate. These indicate an unedited LLM-generated file.
- **Check for README duplication**: If content appears in both CLAUDE.md and README.md, it should be removed from CLAUDE.md.
- **Verify tooling specificity**: Vague references like "run the tests" should be `pytest -x` or `npm test`.Related Skills
claude-settings-audit
Analyze a repository to generate recommended Claude Code settings.json permissions. Use when setting up a new project, auditing existing settings, or determining which read-only bash commands to allow. Detects tech stack, build tools, and monorepo structure.
stop-slop
Use this skill when writing or editing prose to eliminate predictable AI writing patterns. Helps make writing more direct, authentic, and human.
sonos-control
Control Sonos speakers on Tim's home network. Use when the user wants to (1) play, pause, or stop music on Sonos speakers, (2) change volume on speakers, (3) skip tracks, (4) check what's playing, (5) see speaker status, (6) group or ungroup speakers, (7) any Sonos or music/audio playback task involving home speakers. Triggers on "sonos", "speakers", "play music", "what's playing", "volume", "turn up", "turn down", "pause music", "stop music".
slack-message
Draft and send Slack messages in Tim's natural voice. Use when the user wants to (1) post an update to a channel, (2) draft a Slack message, (3) share something on Slack, (4) send a DM, (5) reply in a thread. Applies Tim's Slack writing style and prose principles automatically.
skill-creator
Create new skills, modify and improve existing skills, and measure skill performance. Use when users want to create a skill from scratch, edit, or optimize an existing skill, run evals to test a skill, benchmark skill performance with variance analysis, or optimize a skill's description for better triggering accuracy.
sending-to-codex
Delegate tasks or ask questions to OpenAI's Codex CLI from within Claude Code. Use this skill when the user says "ask codex", "send to codex", "delegate to codex", "have codex do this", "get codex's opinion", "run this in codex", or wants to offload a coding task or question to the Codex agent. Supports both fire-and-forget coding tasks (fix bugs, add features, refactor) and research questions (analyze code, explain behavior, get a second opinion).
reviewing-writing
Review and critique writing using Michael Nielsen's principles on craft. Analyzes text for purpose focus, brevity, danger words, opening strength, originality, reader psychology, truthfulness, and title impact. Use when the user says "review my writing", "nielsen review", "writing review", "review this writing", "critique my writing", or asks for feedback on prose quality.
reviewing-code
Review pull requests, branch changes, or code diffs. Triggers on "review this PR", "review my changes", "code review", "review branch", or GitHub PR URLs. Focuses on bugs, tests, complexity, and performance - not linting.
resend-email
Send emails via Resend.com API. Use when the user wants to (1) send an email, (2) email someone, (3) send a message to an email address, (4) send email with attachments, (5) schedule an email for later. Requires RESEND_API_KEY environment variable.
refresh-dotfiles
Full sync of personal (yadm) and work (yadm-work) dotfiles. Pulls remote changes, commits and pushes local changes, and audits for untracked files that should be tracked. Use when the user says 'refresh yadm', 'sync dotfiles', 'dotfiles sync', or 'update dotfiles'.
omnifocus
Interact with OmniFocus task manager via the command-line interface (@stephendolan/omnifocus-cli). Use when the user wants to: (1) Add tasks or projects to OmniFocus, (2) List, view, or search tasks/projects, (3) Update or complete tasks, (4) Manage inbox items, (5) Work with tags and analyze tag usage, (6) Process or organize their OmniFocus database from the command line.
omnifocus-triage
Interactively process OmniFocus inbox items using AskUserQuestion. Use when the user wants to (1) triage their inbox, (2) process inbox items, (3) organize their OmniFocus inbox, (4) clear out their inbox, (5) do a GTD-style inbox review. Triggers on "triage inbox", "process inbox", "organize inbox", "clear inbox", "inbox zero".