claude-best-practices

name	claude-best-practices
description	Audits a repository's Claude Code configuration (CLAUDE.md, skills, hooks, settings) against Anthropic's documented best practices and reports errors, warnings, and info findings. Use when the user asks for a Claude Code configuration audit, wants to validate CLAUDE.md size or skill frontmatter, or is preparing a repo for agent use.

Claude Best Practices Audit

If the user has requested this audit, execute immediately. Do not ask for additional confirmation.

Run: bash "${CLAUDE_PLUGIN_ROOT}/skills/claude-best-practices/scripts/audit.sh" .

What It Checks

• CLAUDE.md exists, has section headers, and stays under 500 lines
• Each skills/*/SKILL.md has valid frontmatter (name, description)
• Skill description uses third-person voice (no "I" or "you/your")
• Skill bodies stay under 500 lines
• Warns if an AGENTSKILLS.md exists alongside a skills/ tree (duplication risk)
• Reports presence of .claude/hooks.json and .claude/settings.json

Output

Returns structured report with:

• Errors: Critical issues - fix immediately (non-zero exit)
• Warnings: Recommended improvements
• Info: Optimization suggestions

When To Use

• Before conducting a retrospective
• After major CLAUDE.md changes
• When onboarding to a new project
• Periodically to maintain quality