Confirm successful installation by checking the skill directory location:
.cursor/skills/skill-judge
Restart Cursor to activate skill-judge. Access via /skill-judge in your agent's command palette.
β
Security Notice
We perform automated surface-level scans (Gen AI Scanner, Socket, Snyk) during installation. These checks detect common vulnerabilities but do not guarantee complete security. Always review skill source code and verify the publisher's reputation before production use.
Skills execute code in your environment. Always review source, verify the publisher, and test in isolation before production.
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."
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
description: 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"
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
~100 tokens per skill
Layer 2: SKILL.md Body (loaded after triggering)
Detailed guidelines, code examples, decision trees
Ideal: < 500 lines
Layer 3: Resources (loaded on demand)
scripts/, references/, assets/
No limit
Score
Criteria
0-5
Everything dumped in SKILL.md (>500 lines, no structure)
6-10
Has references but unclear when to load them
11-13
Good layering with MANDATORY triggers present
14-15
Perfect: decision trees + explicit triggers + "Do NOT Load" guidance
For Skills WITH references directory, check Loading Trigger Quality:
Trigger Quality
Characteristics
Poor
References listed at end, no loading guidance
Mediocre
Some triggers but not embedded in workflow
Good
MANDATORY triggers in workflow steps
Excellent
Scenario detection + conditional triggers + "Do NOT Load"
The loading problem:
Loading too little βββββββββββββββββββββββββββββββββββΊ Loading too much
- References sit unused - Wastes context space
- Agent doesn't know when to load - Irrelevant info dilutes key content
- Knowledge is there but never accessed - Unnecessary token overhead
Good loading trigger (embedded in workflow):
### Creating New Document**MANDATORY - READ ENTIRE FILE**: Before proceeding, you MUST read
[`docx-js.md`](docx-js.md) (~500 lines) completely from start to finish.
**NEVER set any range limits when reading this file.****Do NOT load**`ooxml.md` or `redlining.md` for this task.
Bad loading trigger (just listed):
## References- docx-js.md - for creating documents
- ooxml.md - for editing
- redlining.md - for tracking changes
For simple Skills (no references, <100 lines): Score based on conciseness and self-containment.
D6: Freedom Calibration (15 points)
Is the level of specificity appropriate for the task's fragility?
Different tasks need different levels of constraint. This is about matching freedom to fragility.
Score
Criteria
0-5
Severely mismatched (rigid scripts for creative tasks, vague for fragile ops)
6-10
Partially appropriate, some mismatches
11-13
Good calibration for most scenarios
14-15
Perfect freedom calibration throughout
The freedom spectrum:
Task Type
Should Have
Why
Example Skill
Creative/Design
High freedom
Multiple valid approaches, differentiation is value
frontend-design
Code review
Medium freedom
Principles exist but judgment required
code-review
File format operations
Low freedom
One wrong byte corrupts file, consis
β
Make data-driven prioritization decisions faster
Stakeholder Communication
Draft PRDs, status updates, and stakeholder presentations
βΊAccess to product documentation and roadmap tools (Jira, Notion, etc.)
βΊUnderstanding of product management frameworks (RICE, Jobs-to-be-Done, etc.)
βΊStakeholder contact information and communication channels
Time Estimate
30-60 minutes to see productivity improvements
Steps
1Install product management skill
2Start with user story generation for known feature
3Progress to competitive analysis: research 2-3 competitors
4Use for roadmap prioritization: apply RICE/ICE scoring
5Draft stakeholder communications and refine based on feedback
6Build template library for recurring PM tasks
7Share effective prompts with product team
Common Pitfalls
β Not validating competitive researchβverify facts before sharing
β Accepting user stories without involving engineering team
β Over-relying on frameworks without qualitative judgment
β Not customizing outputs to company culture and communication style
β Skipping stakeholder validation of generated requirements
Best Practices
β Do
+Validate research and competitive analysis with real data
+Collaborate with engineering when generating technical requirements
+Customize frameworks and templates to your company context
+Use skill for first drafts, refine with stakeholder input
+Document successful prompt patterns for PM tasks
+Combine AI efficiency with human judgment and intuition
β Don't
βDon't publish competitive analysis without fact-checking
βDon't finalize user stories without engineering review
βDon't make prioritization decisions solely on AI scoring
βDon't skip customer validation of generated requirements
βDon't ignore company-specific context and culture
π‘ Pro Tips
β Provide context: company goals, constraints, customer feedback
β Ask for alternatives: 'Show 3 ways to prioritize this roadmap'
β Request stakeholder-specific formatting: 'Executive summary vs. engineering spec'
β Use skill for 70% generation + 30% customization to company needs
When to Use This
β Use when
Use for user story writing, competitive research, roadmap prioritization, stakeholder communication, and PRD drafting. Best for reducing repetitive documentation and research work.
β Avoid when
Avoid for strategic product vision (requires deep customer empathy), pricing decisions (needs market and financial expertise), or when face-to-face customer discovery is more valuable than speed.
Learning Path
1Basic: user stories, feature specs, status updates
