Three axes scored well across the board: descriptions were generally good, progressive disclosure was reasonable, and most skills had adequate scope boundaries.

But one axis was catastrophic.

85% of skills had no Output Contract

163 out of 191 skills had no section declaring what they produce. They'd tell you when to use them. They'd show you patterns and anti-patterns. They'd give you code examples. But they never said: "When this skill is done, here's what you'll have."

This matters more than it sounds.

When Claude activates a skill, it loads the SKILL.md into context and follows its instructions. If those instructions never define the deliverables, the output is... whatever Claude feels like producing. Sometimes that's a complete solution. Sometimes it's a partial explanation. The skill can't enforce consistency because it never declared what "done" looks like.

Compare:

Without an output contract:

Claude knows the topic but not the deliverables. It might produce a code snippet, or a tutorial, or a lecture about when useMemo is appropriate.

With an output contract:

Now Claude knows the checklist. Four deliverables. Each one concrete. Skip one and the output is visibly incomplete.

19% lacked Common Mistakes

36 skills had no anti-pattern coverage at all. These include domains where mistakes are most dangerous — auth, migrations, compliance, recovery apps, legal tools. Skills without anti-patterns teach the happy path and leave you to discover the traps on your own.

The Fix

We ran it in two waves.

Wave 1: The 30-Skill Pilot — hand-crafted Output Contracts and Common Mistakes for the pilot batch. Each contract was written by reading the skill, understanding its domain, and specifying 3-5 concrete deliverables. Seven skills also got Common Mistakes tables. 27 improved, 3 already had contracts.

Wave 2: The Full Library — we built a categorization engine that classifies skills into 22 domain categories (backend, database, devops, security, testing, ML, frontend, design, visual, career, business, health, legal, geospatial, and more), then applies category-appropriate Output Contract templates. But templates alone aren't enough — we then hand-reviewed and rewrote 81 contracts where the automatic categorization produced a mismatch. A music visualization tool shouldn't get an API endpoint contract. A clinical reasoning skill shouldn't get a mobile UI contract.

Results

Every skill in the library now declares its deliverables.

The Meta-Skill Ecosystem

This pass was possible because of four complementary meta-skills:

skill-grader — The rubric. 10 axes, letter grades A+ through F, weighted scoring. It's designed for mechanical evaluation: a sub-agent or non-expert can grade a skill consistently without deep domain knowledge. It told us that Output Contracts were the weakest axis.

skill-architect — The design manual. 13 reference documents covering progressive disclosure, anti-patterns, knowledge engineering, and visual artifacts. It has a scoring rubric too, but at the 0-10 quantitative level. When we needed to know what a good output contract looks like, we consulted the architect.

skill-coach — The implementation guide. Step-by-step creation workflow with validation scripts. When we needed to verify our additions didn't break frontmatter or structure, the coach's validators caught it.

skill-logger — The measurement layer. If we wanted to track whether output contracts actually improve Claude's behavior over time, the logger's quality scoring framework (completion, efficiency, output quality, user satisfaction) is how we'd measure it.

What This Means for Skill Authors

If you're writing Claude Code skills, here's the takeaway:

1. Add an Output Contract

Every skill should declare what it produces. Format:

## Output Contract

This skill produces:
- **Deliverable 1** with specific details about format and content
- **Deliverable 2** with what makes it useful
- **Deliverable 3** with how to verify it's correct

Be specific. "Code" is not a deliverable. "Multi-stage Dockerfile optimized for layer caching, minimal image size, and security" is.

2. Add Common Mistakes

Every skill should teach what NOT to do. Format:

## Common Mistakes

| Mistake | Symptom | Fix |
|---------|---------|-----|
| Specific thing people do wrong | What goes wrong when they do it | How to do it right |

The table format is important. It's scannable. Claude can reference it quickly. And it encodes expert knowledge that the skill can then prevent rather than repair.

3. Follow the Description Formula

[What it does] [When to use it — specific trigger phrases]. NOT for [explicit exclusions with alternatives].

The NOT clause matters more as your skill library grows. With 5 skills, false positives are rare. With 191, they're constant.

4. Stay Under 500 Lines

If your SKILL.md exceeds 500 lines, move depth to /references/. The skill body should be procedural — do this, then this, watch out for that. Long-form explanations, code examples, and configuration details belong in reference files that load on demand.

What's Next

This was a structural pass — adding the one section that was universally missing. The next passes go deeper:

• Description optimization — running eval loops to test activation rates across all 191 skills
• Progressive disclosure audit — skills over 500 lines need content moved to references
• Visual artifact pass — adding decision trees and Mermaid diagrams where workflows are currently described in prose
• Impact measurement — comparing skill output quality before and after Output Contracts using skill-logger's framework

The improvement scripts are at corpus/scripts/batch_improve_all.py. The 10-axis rubric is defined in skill-grader. The meta-skill ecosystem — architect, grader, coach, logger — is available at someclaudeskills.com.