{"id":48495449,"url":"https://github.com/ordinary9843/claude-code-auditor","last_synced_at":"2026-04-07T12:02:20.654Z","repository":{"id":340284701,"uuid":"1165318376","full_name":"ordinary9843/claude-code-auditor","owner":"ordinary9843","description":"Quality auditor for Claude Code artifacts — scores SKILL.md, CLAUDE.md, agents, rules \u0026 commands with A–F grades and actionable fixes.","archived":false,"fork":false,"pushed_at":"2026-03-11T12:06:04.000Z","size":34,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"master","last_synced_at":"2026-03-11T15:28:54.242Z","etag":null,"topics":["anthropic","auditor","claude","claude-cli","claude-code","claude-md-linter","prompt-engineering","skill-md"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ordinary9843.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-02-24T03:30:11.000Z","updated_at":"2026-03-11T12:06:07.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/ordinary9843/claude-code-auditor","commit_stats":null,"previous_names":["ordinary9843/claude-prompt-evaluator-plugin","ordinary9843/claude-prompt-evaluator"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/ordinary9843/claude-code-auditor","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ordinary9843%2Fclaude-code-auditor","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ordinary9843%2Fclaude-code-auditor/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ordinary9843%2Fclaude-code-auditor/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ordinary9843%2Fclaude-code-auditor/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ordinary9843","download_url":"https://codeload.github.com/ordinary9843/claude-code-auditor/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ordinary9843%2Fclaude-code-auditor/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31511785,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-07T03:10:19.677Z","status":"ssl_error","status_checked_at":"2026-04-07T03:10:13.982Z","response_time":105,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["anthropic","auditor","claude","claude-cli","claude-code","claude-md-linter","prompt-engineering","skill-md"],"created_at":"2026-04-07T12:02:10.235Z","updated_at":"2026-04-07T12:02:20.608Z","avatar_url":"https://github.com/ordinary9843.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Claude Code Auditor\n\n[![Claude Code Auditor](https://img.shields.io/badge/Claude_Code_Auditor-Grade_A-success?style=flat-square\u0026logo=anthropic\u0026logoColor=white)](https://github.com/ordinary9843/claude-code-auditor)\n\nTells you why your Claude Code setup isn't working as well as it should. Scores any Claude Code markdown file — `CLAUDE.md`, `.claude/rules/*.md`, `SKILL.md`, `agents/*.md`, `.claude/commands/*.md`, `MEMORY.md`, `.claude/output-styles/*.md`, and context files — against Anthropic best practices. Gives you an A–F grade, exact fixes, and a standard `shields.io` Score Badge for your README.\n\nMost plugin quality improvements are based on intuition (\"I feel this is better\"). This plugin makes quality measurable with a consistent 100-point scoring rubric derived from Anthropic's official documentation and established community standards.\n\n## Installation\n\nYou can install this plugin either directly within Claude Code or via your standard terminal.\n\n### 1. Inside Claude Code (Recommended)\n```shell\n/plugin marketplace add https://github.com/ordinary9843/claude-code-auditor.git\n/plugin install code-auditor@claude-code-auditor\n```\n\n### 2. Via Standard Terminal\n```shell\nclaude plugin marketplace add https://github.com/ordinary9843/claude-code-auditor.git\nclaude plugin install code-auditor@claude-code-auditor\n```\n\n*Note: Please restart Claude Code after installation to ensure the plugin loads correctly.*\n\n## How It Works\n\nThe plugin provides two primary commands that auto-detect the target file type. There is no need to manually specify what kind of file you are evaluating:\n\n```text\n/code-auditor:review [path]   →  score a file or directory (read-only)\n/code-auditor:fix    [path]   →  review + apply improvements (confirms before writing)\n```\n\nIf no path argument is provided, it defaults to the current working directory.\n\n**Two precision tiers are available:**\n- **Fast Review** (default): Scores using the criteria files in `skills/review/references/`. Best for quick feedback on a single file.\n- **Deep Audit**: Activated automatically for directory-level audits, or when you ask for a \"deep audit\" or \"detailed review\". Handled by the `auditor` agent for full reference criteria with cross-file consistency checks.\n\n### Supported File Types \u0026 Components\n\n| Target | Description |\n|--------|-------------|\n| Directory | Performs a full weighted audit |\n| `CLAUDE.md` | Assesses context file quality (actionability, commands, architecture layout, size limit). |\n| `.claude/rules/*.md` | Evaluates rule actionability, scope focus, path targeting, and cross-rule consistency. |\n| `.claude/commands/*.md` | Evaluates custom slash command quality (frontmatter, `$ARGUMENTS` usage, prompt clarity). |\n| `SKILL.md` | Evaluates skill rubrics (frontmatter, content, progressive disclosure, structure). |\n| `agents/*.md` | Evaluates agent rubrics (frontmatter, role definition, behavioral guidelines). |\n| `MEMORY.md` \u0026 topic files | Evaluates auto-memory quality (200-line limit, actionability, topic file structure). |\n| Output styles (`.claude/output-styles/*.md`) | Evaluates custom output style quality (frontmatter, persona, behavioral rules). |\n| Context files (`template.md`, `examples/*.md`) | Evaluates supporting prompt files (formatting, placeholders, input/output clarity). |\n\n\u003e Commands, rules, skills, and output styles must be under `.claude/` (project-level) or `~/.claude/` (global). CLAUDE.md can be placed at the project root or any subdirectory.\n\n### Background Hooks\n\nThe plugin also includes background hooks that fire automatically to assist your development flow:\n\n*   **PostToolUse:** When you write or edit any Claude Code artifact, this hook suggests running the relevant review/fix command.\n*   **SessionStart:** When a Claude Code session begins in a plugin project, it displays available commands.\n\n*Both hooks are advisory only (exit 0) and will never block your operations.*\n\n## Usage Examples\n\n### 1. Run a Full Plugin Audit\n\n```shell\n/code-auditor:review .\n```\n\n**Example Output:**\n```text\n## Plugin Audit: Project   Overall: 64/100 — Grade D\n\nBadge: `[![Claude Code Auditor](https://img.shields.io/badge/Claude_Code_Auditor-Grade_D-orange?style=flat-square\u0026logo=anthropic\u0026logoColor=white)](https://github.com/ordinary9843/claude-code-auditor)`\n\n| Component         | Score      | Grade | Top issue                                                                                         |\n|-------------------|------------|-------|---------------------------------------------------------------------------------------------------|\n| Skills (6)        | 49/100     | F     | Missing frontmatter entirely; No XML bounding for input parsing (-15 security penalty)            |\n| Agents (1)        | 68/100     | D     | reviewer.md has no frontmatter; Claude cannot register or route to the agent                      |\n| Commands (0)      | —          | —     | No custom commands found                                                                          |\n| Rules (2)         | 75/100     | C     | security.md has overlapping globs and vague principles                                            |\n| Memory (0)        | —          | —     | No MEMORY.md found                                                                                |\n| Output Styles (0) | —          | —     | No custom output styles found                                                                     |\n| CLAUDE.md         | 86/100     | B     | No dedicated \"Development Commands\" section; commands scattered; 1–2 vague principle patterns     |\n| **OVERALL**       | **64/100** | **D** |                                                                                                   |\n\n### Top 5 actions (highest point impact across the directory)\n1. [+19.6 pts overall] All 6 SKILL.md files — Add YAML frontmatter with name, description, argument-hint. Example for review/SKILL.md:\n---\nname: review\ndescription: \u003e\n  Scores any Claude Code artifact against Anthropic best practices.\n  Invoked when user asks to \"review\", \"score\", or \"audit\".\nargument-hint: \"[file path or leave empty for current dir]\"\n---\n2. [+4.8 pts overall] All 6 SKILL.md files — Add concrete input→output examples\n3. [+3.2 pts overall] reviewer.md + write-capable skills — Add frontmatter + disable-model-invocation\n4. [+2.5 pts overall] security.md — Rewrite vague principles to specific imperatives\n5. [+2.0 pts overall] CLAUDE.md — Group floating commands into a \"Development Commands\" section\n```\n\n### 2. Challenge a Score or Fix\nThe plugin includes a Devil's Advocate agent (`challenger`) to debate review scores or analyze architectural trade-offs of proposed fixes. Just ask Claude to \"challenge the score\" or \"debate this fix\".\n\n### 3. Auto-Improve a File\nThis command reviews the file, displays a before/after plan, generates an improved version, and requests your confirmation before writing any changes.\n```shell\n/code-auditor:fix skills/review/SKILL.md\n```\n\n## Understanding Scoring \u0026 Grades\n\nAll components are scored from 0 to 100 and assigned an A–F grade based on the following scale:\n\n| Grade | Score Range | Meaning                                                    |\n|-------|-------------|------------------------------------------------------------|\n| A     | 90–100      | Production-ready. Excellent formatting and best practices. |\n| B     | 80–89       | Good. Only minor improvements needed.                      |\n| C     | 70–79       | Adequate. Several issues should be addressed.              |\n| D     | 60–69       | Below standard. Needs significant revision.                |\n| F     | \u003c 60        | Major restructuring required.                              |\n\n**Full Directory Audit Weighting:**\n\nThe plugin auto-detects `plugin-dir` mode (evaluating the current directory of markdown files):\n\n```text\nOverall Score = (Skills Avg × 30%) + (Agents Avg × 20%) + (Commands Avg × 10%)\n             + (Context Avg × 10%) + (Rules Avg × 10%) + (Memory Avg × 5%)\n             + (Output Styles Avg × 5%) + (CLAUDE.md × 10%)\n```\n\nIf a component is absent, redistribute its weight proportionally.\n\n## CI/CD GitHub Actions Integration\n\nYou can integrate Claude Code Auditor into your CI/CD pipeline to automatically score your plugin pull requests or commits.\n\n1. Ensure your repository contains a script like the included `scripts/ci-audit.py`.\n2. Ensure you have `.github/workflows/audit.yml` configured.\n3. Add `ANTHROPIC_API_KEY` to your repository's GitHub Secrets.\n4. On every pull request touching a Claude artifact, the action will trigger an Anthropic API call to the `auditor` agent, post the score in the logs, and fail the build if the plugin grades as an **F**.\n\n*Note: The CI script requires an Anthropic API key to invoke the Claude 3.7 Sonnet model for grading.*\n\n## Plugin Architecture\n\n```text\nclaude-code-auditor/\n├── .claude-plugin/\n│   ├── plugin.json              # Plugin manifest (name: code-auditor)\n│   └── marketplace.json         # Marketplace definition\n├── skills/\n│   ├── review/\n│   │   ├── SKILL.md             # Unified review skill (auto-detects file type)\n│   │   └── references/          # Per-component scoring rubrics\n│   │       ├── skill-criteria.md\n│   │       ├── agent-criteria.md\n│   │       ├── claude-md-criteria.md\n│   │       ├── rules-criteria.md\n│   │       ├── command-criteria.md\n│   │       ├── memory-criteria.md\n│   │       ├── output-style-criteria.md\n│   │       ├── context-criteria.md\n│   │       ├── security-criteria.md\n│   │       └── prompt-effectiveness-criteria.md\n│   └── fix/\n│       ├── SKILL.md             # Review + apply improvements\n│       └── references/\n│           └── fix-criteria.md  # Per-type fix rules\n├── agents/\n│   ├── auditor.md               # Deep audit specialist agent\n│   └── challenger.md            # Devil's advocate / debate agent\n├── hooks/\n│   ├── hooks.json               # PostToolUse + SessionStart hooks\n│   └── scripts/\n│       ├── suggest-review.sh    # Advisory: suggest review after write/edit\n│       └── welcome.sh           # Session start: show available commands\n├── CLAUDE.md                    # Plugin context loaded at session start\n├── LICENSE                      # MIT License\n└── README.md\n```\n\n## Requirements \u0026 Troubleshooting\n\n### Prerequisites\n*   [Claude Code CLI](https://code.claude.com) must be installed.\n*   `jq` must be installed (required by our shell hooks). You can install it via Homebrew:\n    ```shell\n    brew install jq\n    ```\n\n### Common Issues\n\n**1. The Plugin is not loading**\nRun the built-in validate command to check for errors:\n```shell\nclaude plugin validate .\nclaude plugin list\n```\n\n**2. The Hooks are not firing**\nEnsure the hook scripts have execute permissions and that `jq` is installed:\n```shell\nchmod +x hooks/scripts/*.sh\njq --version\n```\n\n**3. The Skills are not available**\nIf you don't see `/code-auditor:review` when typing `/help`:\n*   Make sure you have restarted Claude Code after installation.\n\n## Contributing\n\nWe welcome community improvements! To contribute:\n\n1. Clone this repository to your local machine.\n2. Add the marketplace locally: `claude plugin marketplace add .`\n3. Install the local plugin: `claude plugin install code-auditor@claude-code-auditor`\n4. Run the plugin against itself to establish a baseline: `/code-auditor:review .`\n5. Submit a PR and kindly include the review score generated by the tool in your pull request description.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fordinary9843%2Fclaude-code-auditor","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fordinary9843%2Fclaude-code-auditor","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fordinary9843%2Fclaude-code-auditor/lists"}