Skill Development Guidelines

How to design, validate, and implement new skills for claude-code-java

Purpose

This guide helps contributors create high-quality skills that:

Fill genuine gaps (not duplicate existing functionality)
Provide clear, actionable value
Integrate well with the existing skill ecosystem

Before You Start: Validation Checklist

Before implementing a new skill, answer these questions:

1. Does It Already Exist?

Check overlap with existing skills:

Existing Skill	Level	Focus
clean-code	Micro	Functions, naming, DRY/KISS
solid-principles	Micro/Meso	Classes, interfaces
design-patterns	Meso	Class collaboration patterns
java-code-review	Meso	Code review checklist
architecture-review	Macro	Packages, modules, layers
spring-boot-patterns	Framework	Spring Boot specifics
jpa-patterns	Framework	JPA/Hibernate specifics
security-audit	Cross-cutting	OWASP, input validation
test-quality	Cross-cutting	JUnit 5, AssertJ

Ask yourself:

Does an existing skill cover >50% of what I want to add?
Would extending an existing skill be better than creating a new one?

2. What Level Does It Operate At?

Skills should have a clear scope:

┌─────────────────────────────────────────────────┐
│  Macro    │ Packages, modules, architecture     │
├───────────┼─────────────────────────────────────┤
│  Meso     │ Classes, interfaces, collaboration  │
├───────────┼─────────────────────────────────────┤
│  Micro    │ Functions, variables, expressions   │
├───────────┼─────────────────────────────────────┤
│  Framework│ Spring, JPA, specific technologies  │
├───────────┼─────────────────────────────────────┤
│  Cross    │ Security, testing, logging          │
└───────────┴─────────────────────────────────────┘

Red flag: A skill that tries to cover multiple levels is probably too broad.

3. Is It "Audit" or "Template"?

Two types of skills:

Type	Purpose	Example
Audit	Review existing code, find issues	java-code-review, security-audit
Template	Show how to write new code	spring-boot-patterns, design-patterns

Ask yourself:

Which type is my skill?
Does an existing skill of the same type already cover this?

Example:

spring-boot-patterns = Template (how to write)
api-contract-review = Audit (check existing APIs)
Both deal with REST APIs, but serve different purposes ✅

4. What Unique Value Does It Add?

The skill should add something NEW:

Good reasons for a new skill:

Covers a topic no existing skill addresses
Same topic but different level (micro vs macro)
Same topic but different type (audit vs template)
Specialized depth that doesn't fit in a general skill

Bad reasons:

"It would be nice to have"
"Other tools have this" (without validating the gap)
"I want to reorganize existing content"

5. Will It Be Reached?

The description is not a label. It is the whole of what an agent sees when it decides which skill to load, alongside the name. Nothing else in SKILL.md takes part in that decision, so a skill with excellent content and a vague description is a skill that never runs, and a skill with a greedy description steals prompts from its neighbours.

Two rules follow.

Say where you stop. A description should name the boundary with the skills nearest to it and point at them. performance-smell-detection does this:

... Provides awareness, not absolutes - always measure before optimizing. For JPA/database performance, use jpa-patterns instead.

Without that sentence, prompts about slow queries split unpredictably between two skills.

Describe symptoms, not the subject. Users write what is wrong, not what the topic is called. "This class does too much" reaches solid-principles because the description mentions a class with too many responsibilities. It would not reach a description that only listed the five principles by name.

Adding a skill changes routing for every other skill, because they all compete for the same prompts. Add a case to evals/routing.tsv and run ./scripts/eval-routing.sh over the whole set, not just the new case.

6. Is It Focused Enough?

A skill should be completable in one session. Signs it's too broad:

More than 10-15 checklist items
Covers multiple unrelated topics
Would take hours to apply fully

Solution: Split into multiple focused skills.

Skill Anatomy

Every skill has two files:

skills/<skill-name>/
├── SKILL.md    # Instructions for the agent (the AI reads this)
└── README.md   # Documentation for humans

SKILL.md Structure

Frontmatter follows the Agent Skills specification. name and description are required; license, compatibility, metadata and allowed-tools are optional; no other top-level field is allowed. name must match the directory name. Run ./scripts/validate-skills.sh to check.

---
name: skill-name
description: One-line description. Use when [triggers].
license: MIT
---

# Skill Name

Brief intro (1-2 sentences).

## When to Use
- Trigger phrase 1
- Trigger phrase 2

## Quick Reference
[Table or summary for fast lookup]

## Main Content
[Checklists, patterns, examples]

## Token Optimization
[How to use efficiently on large codebases]

README.md Structure

# Skill Name

> One-line tagline

## What It Does
[2-3 sentences]

## When to Use
[Bullet points with example phrases]

## Key Concepts
[Brief explanation of main ideas]

## Example Usage
[Show a typical interaction]

## Related Skills
[Links to complementary skills]

## References
[External resources]

Quality Standards

Content Guidelines

Be Specific to Java
- Use Java syntax in examples
- Reference Java ecosystem tools (Maven, JUnit, Spring)
- Don't be generic - that's what other skills collections do
Provide Actionable Checklists
- ✅ - [ ] Check for null safety with Optional
- ❌ - [ ] Make sure code is good

Show Anti-Patterns

// ❌ BAD: Why this is wrong
badCode();

// ✅ GOOD: Why this is right
goodCode();

Include Severity Levels
- High: Bugs, security issues, performance killers
- Medium: Code smells, maintainability issues
- Low: Style, minor optimizations

Token Efficiency

Skills should help Claude work efficiently:

Prioritize checks - Most important first
Provide commands - Shell commands to gather info quickly
Suggest sampling - "Check 2-3 examples, not every file"
Exit early - "If X, skip Y checks"

Validation Process

Before submitting a new skill:

Step 1: Gap Analysis

## Proposed: <skill-name>

### What it does
[Description]

### Overlap check
| Existing Skill | Overlap? | Notes |
|----------------|----------|-------|
| skill-1 | None/Partial/High | ... |
| skill-2 | None/Partial/High | ... |

### Unique value
[What this adds that doesn't exist]

### Verdict
[ ] No significant overlap - proceed
[ ] Partial overlap - document distinction
[ ] High overlap - consider extending existing skill instead

Step 2: Peer Review Questions

Ask yourself (or a reviewer):

Would I actually use this skill in a real project?
Can I explain in one sentence when to use it vs related skills?
Does the checklist have <15 items?
Are all examples in Java (not pseudocode)?

Step 3: Test on Real Code

Before committing:

Apply the skill to a real Java project
Verify the checklist makes sense
Check that recommendations are actionable

Automated Review

PRs that modify skills/ are automatically reviewed against these guidelines. The review checks:

Structure: frontmatter, required files, folder convention
Overlap: comparison with existing skills
Quality: actionable content, Java-specific examples, focused scope

This automated check runs before human review to catch common issues early.

Anti-Patterns to Avoid

1. The Kitchen Sink

❌ Bad: A skill that tries to cover everything

java-best-practices/
  - Covers coding style
  - AND testing
  - AND architecture
  - AND security
  - AND performance

✅ Good: Focused skills that compose well

2. The Overlap Trap

❌ Bad: Creating exception-handling-review when java-code-review already has an exceptions section

✅ Good: Extend java-code-review or ensure the new skill has a clearly different scope

3. The Copy-Paste Skill

❌ Bad: Copying generic advice from the internet

✅ Good: Java-specific, opinionated, practical guidance

4. The Theoretical Skill

❌ Bad: Explaining concepts without actionable checks

✅ Good: Checklists that can be applied immediately

Extending vs Creating

Sometimes extending an existing skill is better:

When to Extend

Adding <5 new checklist items
Same level and type as existing skill
Naturally fits the existing structure

When to Create New

Different level (micro vs macro)
Different type (audit vs template)
Would make existing skill too long (>200 lines)
Distinct trigger phrases

How to Extend

Read the existing skill thoroughly
Identify where new content fits
Add new section or expand existing
Update README if needed
Commit with clear message: enhance(skill-name): add X checks

Commit Convention

For skill changes:

feat: add <skill-name> skill          # New skill
enhance(<skill-name>): add X checks   # Extend existing
fix(<skill-name>): correct Y example  # Fix issues
docs(<skill-name>): improve Z section # Documentation only

Iterative Improvement

Skills improve through real usage. A skill is never "done" after the first version.

Signs a Skill Needs Refinement

Signal	Problem	Solution
Claude asks clarifying questions	Missing context or defaults	Add explicit defaults and examples
You frequently correct the output	Missing constraints	Add "DO NOT" rules or format specs
Output varies too much	Too vague	Add concrete examples of expected output
Works on one project, fails on another	Too narrow	Generalize patterns, add edge cases
Takes many iterations to get right	Missing structure	Add step-by-step workflow

Improvement Workflow

Use the skill on real work
Note every correction you make to Claude's output
Update SKILL.md with the correction as a rule
Clear context and test again
Repeat 5-6 times until stable

Maturity Indicators

A skill is mature when:

Works on first try >80% of the time
No steering or corrections needed
Output is copy-paste ready
Works across different projects

Optional: Track Iterations

Consider adding to your skill folder:

skills/<skill-name>/
├── SKILL.md
├── README.md
└── CHANGELOG.md   # Optional: track refinements

Example CHANGELOG.md:

## Iteration History
- v1: Initial version, too vague
- v2: Added output format specification
- v3: Added "avoid" list after common mistakes
- v4: Added examples for edge cases
- v5: Stable - tested on 3 projects

Checklist Summary