agentleFS
Sign inStart free
Rtur2003Rtur2003/Claude-Code-Promts-Skills/.agents/skills/skill-audit/SKILL.md

skill-audit

Skill53 starsChanged 52 days agoMITView on GitHub

Use when a skill isn't triggering as expected, before adding a new skill (to check for a name collision), during periodic cleanup of an accumulated skills directory, or when asked to review skill quality — checks frontmatter validity, description quality against Skill Discovery Optimization conventions, body size, and cross-scope name collisions.

58 other projects use a version of this.

Adopted by

Most recently taken up by

Used with

Projects with it also use root-cause, write-a-skill and 8 more.

Other files people use alongside this one.

Files found in the same public projects as a version of this one, more often than they turn up anywhere else. Each project counts once, large collections count for less, and this file's own repository is left out.
  • Ingramradical235Skill

    root-cause

    Structured root cause analysis using WHERE (MECE decomposition) then WHY (causal structure diagrams) pipeline. Includes coin-flip detection, logical-leap detection, and vicious cycle intervention. Use when buffer enters YELLOW/RED, when metrics stall, or when Actions execute but don't produce results.

    Also in 3 projects that use this

  • simo97Skill

    write-a-skill

    Create new agent skills with proper structure, progressive disclosure, and bundled resources. Use when user wants to create, write, or build a new skill.

    Also in 4 projects that use this

  • Microsoft AzureSkill

    reflect

    Learning capture system that extracts HIGH/MED/LOW confidence patterns from conversations to prevent repeating mistakes. Use after user corrections ("no", "wrong"), praise ("perfect", "exactly"), or when discovering edge cases. Complements .squad/agents/{agent}/history.md and .squad/decisions.md.

    Also in 5 projects that use this

  • sunnyclinches44Skill

    explain

    Explains code using real-world analogies and ASCII diagrams

    Also in 4 projects that use this

  • eherrerosjSkill

    humanize

    Remove signs of AI-generated writing from text. Use when editing or reviewing text to make it sound more natural and human-written. Based on Wikipedia's comprehensive 'Signs of AI writing' guide. Detects and fixes patterns including: inflated symbolism, promotional language, superficial -ing analyses, vague attributions, em dash overuse, rule of three, AI vocabulary words, negative parallelisms, and excessive conjunctive phrases. Triggers on: 'humanize', 'make this sound human', 'remove AI writing', 'de-AI', 'sound more natural', 'less robotic', 'too AI-sounding', or when reviewing text that reads like AI output.

    Also in 3 projects that use this

  • MicrosoftSkill

    report

    Turn an exploration (threads, findings, charts) into a single Markdown report — note, blog post, executive summary, KPI dashboard, slide brief, or multi-section analytical report, with embedded charts.

    Also in 3 projects that use this

The file

Create a free account to mount
Files
SKILL.md

Skill Audit

Overview

Skills accumulate. Nobody deletes them, most developers hit 8-12 installed skills before the per-session token cost of loading every description starts to outweigh the benefit, and a skill installed at both the personal and project scope with the same name fails silently — the higher-precedence one wins and the other never fires, with no error anywhere. This script checks the mechanical properties that predict a skill working or silently failing: valid frontmatter, a description that leads with the trigger (not a workflow summary), a body under the token-efficiency guideline, and no name collision across scopes.

Core principle: A skill that never triggers and a skill that doesn't exist have the same effect on the user, but only one of them is visible in a directory listing. This script finds the invisible kind.

Usage

python3 ${CLAUDE_SKILL_DIR}/scripts/audit.py [skills_dir ...]

With no arguments, checks .claude/skills/ (project) and ~/.claude/skills/ (personal) if they exist. Pass explicit paths to also check a plugin's skills/ directory. Exit code 0 = clean, 1 = findings, 2 = usage error.

python3 ${CLAUDE_SKILL_DIR}/scripts/audit.py .claude/skills ~/.claude/skills ./my-plugin/skills

What it checks

CheckWhy it matters
Frontmatter parsesA SKILL.md without valid ----delimited YAML at the top cannot be discovered reliably by the host
name field matches directory nameThe command comes from the directory name for personal/project skills; a mismatched name field is almost always a copy-paste leftover from another skill
Description opens with a trigger phrasePer Skill Discovery Optimization: "Route the task and adopt it as your instructions" (what it does) trains the model to act on the summary instead of reading the body; "Use when the user names a task" (when to fire) doesn't
Description doesn't summarize the workflowA description that describes the process ("dispatches a subagent per task, reviews between each") gives the model a shortcut that has been observed to cause it to skip steps the actual skill body specifies
Description lengthOver 1024 characters fails the Agent Skills spec limit
Body word countPast ~2000 words (~500 lines), token cost per invocation is high enough that a reference file loaded on demand almost always beats keeping everything inline
Cross-scope name collisionsTwo SKILL.md files with the same name (or same directory name) at different scopes — one always wins, the other never triggers, and nothing tells you which

What it does not check

Whether the skill's instructions are correct, whether it actually gets invoked on the prompts it should (that requires running real scenarios — see the with-skill/without-skill baseline in agent-skills-prompt.md), or whether supporting files referenced from the body actually exist and are useful. This script catches the mechanical failure modes; it is not a substitute for testing trigger accuracy.

Remember

A clean audit means the skill is structurally capable of working. It says nothing about whether it triggers on the right prompts or produces the right output — that's a separate, behavioral test, not a static one.

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

Check your setup, free