skill-judge
Evaluate Agent Skill design quality against official specifications and best practices
Install / Use
npx skills add softaworks/agent-toolkit --skill skill-judgeInstalls into whichever agent you are using.
SKILL.md
Installable skill definition
Quality Score
Category
Development & EngineeringSupported Platforms
Our assessment of skill-judge
skill-judge scores 87/100 on our quality scale, 2150th of 4,700 Development & Engineering skills we index (top 46%).
Its SKILL.md is 29 KB long, well organised into 44 sections with 34 code examples: a thorough specification that gives an agent plenty to work with.
With 2,502 GitHub stars, it is one of the more widely adopted skills in the catalogue.
Maintenance, license and trust
- The repository was last updated about 9 months ago. That is recent enough to be usable, but agent tooling moves fast, so check the instructions against your agent's current version.
- Our last check on 2026-11-02 found the source still online.
- It is released under the MIT license, a permissive license that allows use, modification and commercial use with attribution.
- Its trust signals score 94/100, with 1 caution from licensing, adoption, age or documentation. These come from repository metadata, not a code audit — read the skill file before letting an agent act on it.
Safety scan
No issues foundOur scan of the whole file found no instruction hijacking, hidden characters, credential access, data exfiltration or destructive commands. An AI review of the same text found nothing harmful.
AI review by kimi-k2.7-code on 2026-10-01. Automated pattern scan on 2026-10-01. It catches known dangerous patterns, not every risk — read a skill before letting an agent act on it.
skill-judge compared with similar skills
All 4 of these similar skills score higher than skill-judge; compare them before choosing.
| Skill | Score | Stars | Updated | Format |
|---|---|---|---|---|
| skill-judge (this skill)by softaworks | 87 | 2.5k | 9mo ago | SKILL.md |
| taste-skillby Leonxlnx | 100 | 116.8k | 8d ago | CLAUDE.md |
| ai-job-searchby ai-job-search-dev | 100 | 72.1k | today | CLAUDE.md |
| claude-howtoby luongnv89 | 100 | 47.3k | 2d ago | CLAUDE.md |
| Claude-Code-Game-Studiosby Donchitos | 100 | 39.7k | 7d ago | CLAUDE.md |
Frequently asked questions
- How do I install skill-judge?
- Run
npx skills add softaworks/agent-toolkit --skill skill-judge. The install tabs above show the steps for each supported agent. - Which AI agents does skill-judge work with?
- It is written for Universal, as a SKILL.md file. Other agents that read the same format can often use it too.
- Is skill-judge safe to use?
- Our scan of the whole file found no instruction hijacking, hidden characters, credential access, data exfiltration or destructive commands. An AI review of the same text found nothing harmful. It is MIT-licensed and scores 94/100 on trust signals. Skills are instructions an agent will follow, so read the file before installing it and do not approve commands you do not understand.
- Is skill-judge still maintained?
- The repository was last updated about 9 months ago. That is recent enough to be usable, but agent tooling moves fast, so check the instructions against your agent's current version.
Skill content
View source on GitHubname: skill-judge description: Evaluate Agent Skill design quality against official specifications and best practices. Use when reviewing, auditing, or improving SKILL.md files and skill packages. Provides multi-dimensional scoring and actionable improvement suggestions.
Skill Judge
Evaluate Agent Skills against official specifications and patterns derived from 17+ official examples.
Core Philosophy
What is a Skill?
A Skill is NOT a tutorial. A Skill is a knowledge externalization mechanism.
Traditional AI knowledge is locked in model parameters. To teach new capabilities:
Traditional: Collect data → GPU cluster → Train → Deploy new version
Cost: $10,000 - $1,000,000+
Timeline: Weeks to months
Skills change this:
Skill: Edit SKILL.md → Save → Takes effect on next invocation
Cost: $0
Timeline: Instant
This is the paradigm shift from "training AI" to "educating AI" — like a hot-swappable LoRA adapter that requires no training. You edit a Markdown file in natural language, and the model's behavior changes.
The Core Formula
Good Skill = Expert-only Knowledge − What Claude Already Knows
A Skill's value is measured by its knowledge delta — the gap between what it provides and what the model already knows.
- Expert-only knowledge: Decision trees, trade-offs, edge cases, anti-patterns, domain-specific thinking frameworks — things that take years of experience to accumulate
- What Claude already knows: Basic concepts, standard library usage, common programming patterns, general best practices
When a Skill explains "what is PDF" or "how to write a for-loop", it's compressing knowledge Claude already has. This is token waste — context window is a public resource shared with system prompts, conversation history, other Skills, and user requests.
Tool vs Skill
| Concept | Essence | Function | Example | |---------|---------|----------|---------| | Tool | What model CAN do | Execute actions | bash, read_file, write_file, WebSearch | | Skill | What model KNOWS how to do | Guide decisions | PDF processing, MCP building, frontend design |
Tools define capability boundaries — without bash tool, model can't execute commands. Skills inject knowledge — without frontend-design Skill, model produces generic UI.
The equation:
General Agent + Excellent Skill = Domain Expert Agent
Same Claude model, different Skills loaded, becomes different experts.
Three Types of Knowledge in Skills
When evaluating, categorize each section:
| Type | Definition | Treatment | |------|------------|-----------| | Expert | Claude genuinely doesn't know this | Must keep — this is the Skill's value | | Activation | Claude knows but may not think of | Keep if brief — serves as reminder | | Redundant | Claude definitely knows this | Should delete — wastes tokens |
The art of Skill design is maximizing Expert content, using Activation sparingly, and eliminating Redundant ruthlessly.
Evaluation Dimensions (120 points total)
D1: Knowledge Delta (20 points) — THE CORE DIMENSION
The most important dimension. Does the Skill add genuine expert knowledge?
| Score | Criteria | |-------|----------| | 0-5 | Explains basics Claude knows (what is X, how to write code, standard library tutorials) | | 6-10 | Mixed: some expert knowledge diluted by obvious content | | 11-15 | Mostly expert knowledge with minimal redundancy | | 16-20 | Pure knowledge delta — every paragraph earns its tokens |
Red flags (instant score ≤5):
- "What is [basic concept]" sections
- Step-by-step tutorials for standard operations
- Explaining how to use common libraries
- Generic best practices ("write clean code", "handle errors")
- Definitions of industry-standard terms
Green flags (indicators of high knowledge delta):
- Decision trees for non-obvious choices ("when X fails, try Y because Z")
- Trade-offs only an expert would know ("A is faster but B handles edge case C")
- Edge cases from real-world experience
- "NEVER do X because [non-obvious reason]"
- Domain-specific thinking frameworks
Evaluation questions:
- For each section, ask: "Does Claude already know this?"
- If explaining something, ask: "Is this explaining TO Claude or FOR Claude?"
- Count paragraphs that are Expert vs Activation vs Redundant
D2: Mindset + Appropriate Procedures (15 points)
Does the Skill transfer expert thinking patterns along with necessary domain-specific procedures?
The difference between experts and novices isn't "knowing how to operate" — it's "how to think about the problem." But thinking patterns alone aren't enough when Claude lacks domain-specific procedural knowledge.
Key distinction: | Type | Example | Value | |------|---------|-------| | Thinking patterns | "Before designing, ask: What makes this memorable?" | High — shapes decision-making | | Domain-specific procedures | "OOXML workflow: unpack → edit XML → validate → pack" | High — Claude may not know this | | Generic procedures | "Step 1: Open file, Step 2: Edit, Step 3: Save" | Low — Claude already knows |
| Score | Criteria | |-------|----------| | 0-3 | Only generic procedures Claude already knows | | 4-7 | Has domain procedures but lacks thinking frameworks | | 8-11 | Good balance: thinking patterns + domain-specific workflows | | 12-15 | Expert-level: shapes thinking AND provides procedures Claude wouldn't know |
What counts as valuable procedures:
- Workflows Claude hasn't been trained on (new tools, proprietary systems)
- Correct ordering that's non-obvious (e.g., "validate BEFORE packing, not after")
- Critical steps that are easy to miss (e.g., "MUST recalculate formulas after editing")
- Domain-specific sequences (e.g., MCP server's 4-phase development process)
What counts as redundant procedures:
- Generic file operations (open, read, write, save)
- Standard programming patterns (loops, conditionals, error handling)
- Common library usage that's well-documented
Expert thinking patterns look like:
Before [action], ask yourself:
- **Purpose**: What problem does this solve? Who uses it?
- **Constraints**: What are the hidden requirements?
- **Differentiation**: What makes this solution memorable?
Valuable domain procedures look like:
### Redlining Workflow (Claude wouldn't know this sequence)
1. Convert to markdown: `pandoc --track-changes=all`
2. Map text to XML: grep for text in document.xml
3. Implement changes in batches of 3-10
4. Pack and verify: check ALL changes were applied
Redundant generic procedures look like:
Step 1: Open the file
Step 2: Find the section
Step 3: Make the change
Step 4: Save and test
The test:
- Does it tell Claude WHAT to think about? (thinking patterns)
- Does it tell Claude HOW to do things it wouldn't know? (domain procedures)
A good Skill provides both when needed.
D3: Anti-Pattern Quality (15 points)
Does the Skill have effective NEVER lists?
Why this matters: Half of expert knowledge is knowing what NOT to do. A senior designer sees purple gradient on white background and instinctively cringes — "too AI-generated." This intuition for "what absolutely not to do" comes from stepping on countless landmines.
Claude hasn't stepped on these landmines. It doesn't know Inter font is overused, doesn't know purple gradients are the signature of AI-generated content. Good Skills must explicitly state these "absolute don'ts."
| Score | Criteria | |-------|----------| | 0-3 | No anti-patterns mentioned | | 4-7 | Generic warnings ("avoid errors", "be careful", "consider edge cases") | | 8-11 | Specific NEVER list with some reasoning | | 12-15 | Expert-grade anti-patterns with WHY — things only experience teaches |
Expert anti-patterns (specific + reason):
NEVER use generic AI-generated aesthetics like:
- Overused font families (Inter, Roboto, Arial)
- Cliched color schemes (particularly purple gradients on white backgrounds)
- Predictable layouts and component patterns
- Default border-radius on everything
Weak anti-patterns (vague, no reasoning):
Avoid making mistakes.
Be careful with edge cases.
Don't write bad code.
The test: Would an expert read the anti-pattern list and say "yes, I learned this the hard way"? Or would they say "this is obvious to everyone"?
D4: Specification Compliance — Especially Description (15 points)
Does the Skill follow official format requirements? Special focus on description quality.
| Score | Criteria | |-------|----------| | 0-5 | Missing frontmatter or invalid format | | 6-10 | Has frontmatter but description is vague or incomplete | | 11-13 | Valid frontmatter, description has WHAT but weak on WHEN | | 14-15 | Perfect: comprehensive description with WHAT, WHEN, and trigger keywords |
Frontmatter requirements:
name: lowercase, alphanumeric + hyphens only, ≤64 charactersdescription: THE MOST CRITICAL FIELD — determines if skill gets used at all
Why description is THE MOST IMPORTANT field:
┌─────────────────────────────────────────────────────────────────────┐
│ SKILL ACTIVATION FLOW │
│ │
│ User Request → Agent sees ALL skill descriptions → Decides which │
│ (only descriptions, not bodies!) to activate │
│ │
│ If description doesn't match → Skill NEVER gets loaded │
│ If description is vague → Skill might not trigger when it should │
│ If description lacks keywords → Skill is invisible to the Agent │
└─────────────────────────────────────────────────────────────────────┘
The brutal truth: A Skill with perfect content but poor description is useless — it will never be activated. The description is the only chance to tell the Agent "use me in these situations."
Description must answer THREE questions:
- WHAT: What does this Skill do? (functionality)
- WHEN: In what situations should it be used? (trigger scenarios)
- KEYWORDS: What terms should trigger this Skill? (searchable terms)
Excellent description (all three elements):
description: "Comprehensive document creation, editing, and analysis with support
for tracked changes, comments, formatting preservation, and text extraction.
When Claude needs to work with professional documents (.docx files) for:
(1) Creating new documents, (2) Modifying or editing content,
(3) Working with tracked changes, (4) Adding comments, or any other document tasks"
Analysis:
- WHAT: creation, editing, analysis, tracked changes, comments
- WHEN: "When Claude needs to work with... for: (1)... (2)... (3)..."
- KEYWORDS: .docx files, tracked changes, professional documents
Poor description (missing elements):
description: "处理文档相关功能"
Problems:
- WHAT: vague ("文档相关功能" — what specifically?)
- WHEN: missing (when should Agent use this?)
- KEYWORDS: missing (no ".docx", no specific scenarios)
Another poor example:
description: "A helpful skill for various tasks"
This is useless — Agent has no idea when to activate it.
Description quality checklist:
- [ ] Lists specific capabilities (not just "helps with X")
- [ ] Includes explicit trigger scenarios ("Use when...", "When user asks for...")
- [ ] Contains searchable keywords (file extensions, domain terms, action verbs)
- [ ] Specific enough that Agent knows EXACTLY when to use it
- [ ] Includes scenarios where this skill MUST be used (not just "can be used")
D5: Progressive Disclosure (15 points)
Does the Skill implement proper content layering?
Skill loading has three layers:
Layer 1: Metadata (always in memory)
Only name + description
Truncated for display — read the full file on GitHub.
Related Skills
taste-skill
116.8kAgent skills that give coding agents taste: art direction, reference images and a browser check instead of generic AI pages
ai-job-search
72.1kThe job search that runs on your machine. AI job application framework built on Claude Code: evaluate postings, tailor CVs, write cover letters, prep interviews. Fork it and own it.
claude-howto
47.3kA visual, example-driven guide to Claude Code — from basic concepts to advanced agents, with copy-paste templates that bring immediate value.
Claude-Code-Game-Studios
39.7kTurn Claude Code into a full game dev studio — 49 AI agents, 72 workflow skills, and a complete coordination system mirroring real studio hierarchy.
Languages
Trust signals
From repository metadata: license, adoption, age and documentation. Not a code audit — see the Safety scan above for what the skill file itself contains.
