Claude Skills

Package repeatable expertise that the AI loads only when it's actually needed

🎯 What is a Skill?

A Skill is a folder containing a SKILL.md file that documents a specific piece of expertise — a coding standard, a debugging workflow, a checklist, a domain-specific procedure. Claude Code reads the skill's short description at startup, and only loads the full content into context when the current task matches that description.

This is the key difference from just pasting rules into CLAUDE.md: skills keep your context window clean. A 2,000-line Java coding standard doesn't cost you a single token until you're actually writing Java.

💡 Skills vs. Rules vs. CLAUDE.md

• CLAUDE.md — always loaded, for things the AI must know on every single turn (tech stack, build commands)
• Rules (.claude/rules/*.md) — auto-loaded based on file path being edited (see .claude Configuration Layers)
• Skills (.claude/skills/*/SKILL.md) — loaded on demand based on task description matching, can be large and detailed

📦 Directory structure

.claude/
└── skills/
    ├── java-coding-standards/
    │   └── SKILL.md
    ├── java-unit-testing/
    │   └── SKILL.md
    └── java-security-standards/
        └── SKILL.md

Each skill lives in its own directory named after the skill, containing a SKILL.md file. A skill can also bundle supporting scripts or reference files alongside SKILL.md if the task requires running code, not just reading instructions.

🧩 Anatomy of a SKILL.md

---
name: java-coding-standards
description: Alibaba Java coding conventions covering naming, formatting, OOP rules,
  date/time handling, collections, and concurrency. Use when writing Java code,
  reviewing code, or enforcing Alibaba Java style.
---

# Coding Conventions

## Naming
...

## Code Formatting
...

Field	Purpose
name	Unique identifier, matches the directory name
description	The most important field. This is what Claude scans to decide whether to load the skill. Be specific about triggers ("Use when...") and non-triggers ("Skip when...")
Body	The full instructions, examples, checklists — only loaded when triggered

⚠️ Write the description like a trigger condition, not a summary

A vague description ("Java best practices") won't reliably fire. A good description names concrete signals: file extensions, keywords in the request, error messages, or explicit exclusions for adjacent skills that could be confused with this one.

🚀 Common skill categories in enterprise repos

Real-world engineering teams typically split skills by concern rather than by writing one giant document:

Skill	Covers
*-coding-standards	Naming, formatting, language idioms
*-project-structure	Module layout, package conventions
*-exception-logging	Error handling and logging patterns
*-security-standards	Input validation, auth, secrets handling
*-unit-testing	Test structure, mocking rules, coverage expectations
*-database	Schema conventions, migration rules, query patterns

Splitting this way means each skill's description can be narrow and precise, which makes triggering more reliable and keeps unrelated context out of unrelated tasks.

🛠️ Creating a skill

1. Create the directory: .claude/skills/<skill-name>/
2. Add SKILL.md with frontmatter (name, description) and the full instructions in the body
3. Write the description as an explicit trigger condition — think "when should this fire" first, content second
4. Test it: start a task that should trigger the skill and confirm Claude picks it up
5. Commit it to the repo (project skills) so the whole team benefits

💡 Personal vs. team skills

• Project skills — .claude/skills/ inside the repo, committed to git, shared by the whole team
• Global skills — ~/.claude/skills/, personal, available across every project on your machine (good for skills like "how I like commit messages formatted" that aren't project-specific)

📖 Example: a real SKILL.md excerpt

---
name: java-exception-logging
description: Exception handling and logging conventions — custom exception hierarchy,
  global exception handlers, SLF4J usage, log level rules. Use when writing try/catch
  blocks, custom exceptions, or logging statements in Java code.
---

# Exception & Logging Conventions

## Exception Hierarchy
- Business exceptions extend `BusinessException`, carry an error code and message
- Never catch `Exception` broadly — catch specific exception types
- Never swallow exceptions silently; log or rethrow

## Logging
- Use SLF4J (`@Slf4j`), never `System.out.println`
- `log.error` must include the exception object as the last argument for stack traces
- Don't log and rethrow the same exception at multiple layers (log-and-throw anti-pattern)

🎉 Result

When a developer's Claude Code session touches a try/catch block, this skill's description matches and the full convention loads automatically — no need to repeat it in every prompt.