# Evaluate Skills

> Evaluates and authors agent skills against the Agent Skills spec. Use when reviewing, writing, or refactoring a SKILL.md, or asking about structure, frontmatter, or naming.

- Skill: `altertable-ai/evaluate-skills` (Agent Skill, multi-file: 3 files)
- Install (CLI): `npx skillmds@latest add altertable-ai/evaluate-skills`
- Raw SKILL.md: https://api.skillmd.com/api/skills/altertable-ai/evaluate-skills/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: altertable-ai (https://skillmd.com/u/altertable-ai)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/altertable-ai/evaluate-skills

---


# Evaluate Skills

## Quick Start

1. **Validating**: Run `skills validate <skill-dir>` for structural checks
2. **Scoring**: Run `python scripts/score-skills.py <skill-dir>` for spec-grounded LLM evaluation

## When to Use This Skill

- User wants to create a new skill
- User asks to review or evaluate an existing skill
- User needs help with skill format or structure
- User asks about skill best practices
- User wants to refactor or improve a skill
- Keywords: "skill", "SKILL.md", "create skill", "evaluate skill", "skill quality"

## Authoritative References

The scorer grounds evaluation against these live documents (with vendored snapshot fallback):
- [Specification](https://agentskills.io/specification.md) - Field constraints, structure rules
- [Best Practices](https://agentskills.io/skill-creation/best-practices.md) - Quality criteria
- [Evaluating Skills](https://agentskills.io/skill-creation/evaluating-skills.md) - Evaluation methodology

## Skill Anatomy

```
skill-name/                    # Imperative verb, lowercase, hyphens
├── SKILL.md                   # Main documentation (<500 lines)
└── references/                # Optional detailed references
    ├── topic-1.md            # One level deep only
    └── topic-2.md
```

### Frontmatter (Required)

```yaml
---
name: skill-name                    # Imperative verb, lowercase, hyphens, max 64 chars
description: "Third person description with trigger keywords. Max 1024 chars."
---
```

**Description Rules:**
- Third person: "Analyzes data..." not "I help you..."
- Include trigger keywords for agent activation
- Describe what AND when to use

## Recommended Section Order

| Section | Purpose | Guidelines |
|---------|---------|------------|
| Quick Start | Immediate value | 2-5 lines, actionable |
| When to Use | Activation triggers | Bullet points, keywords |
| Core Concepts | Mental models | Build understanding |
| Workflow/Procedures | Step-by-step | Progressive complexity |
| Examples | Concrete patterns | Code blocks, scenarios |
| Common Pitfalls | Mistakes to avoid | 5-10 items |
| References | Deep dives | Link to references/ with trigger context |

## Skill Types & Patterns

### Exploratory Skills
Explain concepts, provide reference material, build mental models.
- Lead with fundamentals
- Include terminology glossary
- Show common patterns

### Procedural Skills
Step-by-step guides for completing tasks.
- Start with quick start
- Show code examples early
- Progress simple → complex

### Decision/Framework Skills
Help make choices between options.
- Lead with decision trees (ASCII)
- Provide decision matrices
- Include keyword signals

### Analytical Skills
Interpret data or outputs.
- Explain interpretation frameworks
- Pattern recognition guidance
- Good vs bad examples

## Evaluation Checklist

### Frontmatter
- [ ] Name uses an imperative verb
- [ ] Name is lowercase with hyphens only
- [ ] Name matches directory name
- [ ] Description is third person
- [ ] Description includes trigger keywords
- [ ] Description < 1024 characters

### Structure
- [ ] SKILL.md body < 500 lines
- [ ] Total skill < 5000 tokens
- [ ] References one level deep only
- [ ] Has Quick Start section
- [ ] Has When to Use section

### Content Quality
- [ ] Paragraphs 3-5 lines max
- [ ] Uses headers for organization
- [ ] Code in fenced blocks with language
- [ ] Tables for comparisons
- [ ] Concrete examples (not abstract)
- [ ] No time-sensitive information
- [ ] Consistent terminology

### Common Pitfalls
- [ ] Includes pitfalls section
- [ ] 5-10 specific mistakes
- [ ] Explains why they're wrong

## Creating a New Skill

### Step 1: Choose the Name

```
Good: analyze-data, create-reports, manage-users
Bad:  analyzing-data, report-creator, user-management
```

Use an imperative verb. The action should be clear.

### Step 2: Write the Description

Template:
```
"{Verb}s {what} for {purpose}. Use when {trigger conditions}."
```

Example:
```
"Analyzes chart visualizations to extract insights. Use when interpreting
dashboards, identifying trends, or explaining data patterns to stakeholders."
```

### Step 3: Structure Content

1. Start with Quick Start (2-5 actionable lines)
2. Add When to Use (bullet list of triggers)
3. Write core content (concepts, workflows, examples)
4. Add Common Pitfalls
5. Move detailed content to references/ with loading triggers (e.g. "Read when implementing X")

### Step 4: Validate

Run through the evaluation checklist above.

## Using the Scorer

### Validate Only (fast, no LLM)
```bash
uv run python scripts/score-skills.py <skill-dir> --validate_only
```

### Full Scoring (with spec grounding)
```bash
uv run python scripts/score-skills.py <skill-dir>
```

### Batch All Skills
```bash
uv run python scripts/score-skills.py . --scan_all
```

## Common Pitfalls

1. **First-person descriptions** - Use "Analyzes..." not "I analyze..."
2. **Missing trigger keywords** - Agents can't find the skill
3. **Too long SKILL.md** - Move details to references/ and add trigger context (e.g. "Read when working with X")
4. **Nested reference folders** - Only one level allowed
5. **Abstract examples** - Use concrete, real scenarios
6. **Noun-form names** - Use "analyze-data" not "data-analyzer"
7. **No Quick Start** - Users abandon without immediate value
8. **Inconsistent terminology** - Pick terms and stick with them
9. **Missing pitfalls section** - Helps users avoid mistakes
10. **Time-sensitive content** - Skills should be evergreen

## References

- [skill-checklist.md](references/skill-checklist.md) - Read when scoring or reviewing a skill to get the full rubric breakdown, anti-patterns, and evaluation template
- [examples.md](references/examples.md) - Read when creating a new skill or refactoring an existing one to see concrete patterns from well-designed skills