Comprehensive Skill Module

A meta-skill for designing, documenting, and maintaining Claude Code skill libraries at scale. Comprehensive Skill Module provides frameworks for organizing skill collections, establishing naming conventions, creating skill catalogs, and managing skill dependencies across teams and projects.

When to Use This Skill

Choose Comprehensive Skill Module when:

• Building a shared skill library for a team or organization
• Establishing conventions for skill naming, structure, and documentation
• Auditing existing skills for quality, overlap, and coverage gaps
• Creating a skill catalog with search and categorization

Consider alternatives when:

• Creating a single skill (use Skill Developer Engine for individual skill authoring)
• You need hooks or MCP server configuration (different from skills)
• You're writing project documentation rather than skill management

Quick Start

Copy
claude "Audit my .claude/skills directory and suggest improvements"

Copy
# Skill Library Audit Report

## Current Skills (7 found)

| Skill | Lines | Auto-Activate | Category | Status |
|-------|-------|--------------|----------|--------|
| code-review.md | 45 | `src/**/*.ts` | Quality | ✅ Good |
| testing.md | 280 | `**/*.test.*` | Quality | ⚠️ Too broad |
| api-routes.md | 62 | `src/api/**` | Backend | ✅ Good |
| deploy.md | 35 | None (manual) | DevOps | ✅ Good |
| styles.md | 15 | `**/*.css` | Frontend | ⚠️ Too short |
| everything.md | 450 | `**/*` | General | ❌ Overloaded |
| db.md | 90 | `src/db/**` | Backend | ✅ Good |

## Recommendations
1. Split `everything.md` into focused skills by concern
2. Narrow `testing.md` pattern to `src/**/*.test.ts`
3. Expand `styles.md` with actual CSS conventions
4. Add missing skills: error handling, logging, auth patterns

Core Concepts

Skill Library Structure

Layer	Purpose	Example
Foundation	Language/framework conventions	typescript-conventions.md
Domain	Business logic patterns	payment-processing.md
Workflow	Process-specific guidance	pr-review-checklist.md
Project	Repo-specific rules	monorepo-navigation.md

Naming Conventions

Copy
## Skill Naming Rules

### Format: `{scope}-{concern}.md`

### Scopes
- Language: `python-`, `typescript-`, `rust-`
- Framework: `react-`, `fastapi-`, `rails-`
- Domain: `auth-`, `payments-`, `search-`
- Process: `review-`, `deploy-`, `migrate-`

### Examples
✅ typescript-testing.md
✅ react-component-patterns.md
✅ deploy-production-checklist.md
❌ stuff.md
❌ my-skill.md
❌ miscellaneous.md

Dependency Management

Copy
## Skill Dependencies

api-routes.md
├── depends on: typescript-conventions.md (types, imports)
├── depends on: error-handling.md (error responses)
└── extends: auth-middleware.md (route protection)

testing.md
├── depends on: typescript-conventions.md (types)
└── extends: api-routes.md (test patterns for routes)

Configuration

Parameter	Description	Default
catalog_format	Output format for skill catalog	markdown_table
audit_checks	Checks to run during audit	[overlap, coverage, size, patterns]
naming_convention	Enforce naming format	scope-concern
max_skill_lines	Warning threshold for skill length	200
require_description	All skills must have description	true

Best Practices

1. Organize skills in layers. Foundation skills (language conventions) should be general, while domain skills (business logic) should be specific. This prevents duplication and makes it clear which skill to modify when patterns change.

2. Maintain a skill catalog. Keep a SKILLS.md index file listing every skill with its purpose, activation pattern, and owner. This prevents duplicate skills and helps new team members discover existing guidance.

3. Review skills quarterly. Skills rot just like code. Schedule periodic reviews to update outdated patterns, remove skills for deprecated technologies, and add skills for new tools the team has adopted.

4. Use consistent internal structure. Every skill should follow the same template — purpose, when to use, conventions, examples. Consistency makes skills easier to read, maintain, and contribute to.

5. Track skill effectiveness. Ask the team which skills produce the best results and which ones Claude seems to ignore. Refine instruction wording based on actual usage rather than theoretical best practices.

Common Issues

Skills overlap and give conflicting advice. Map skill activation patterns to identify overlaps. If two skills activate on the same files, either merge them or narrow their scopes. Use a dependency diagram to visualize relationships.

New team members don't know skills exist. Add skill discovery to onboarding — include a "Claude Code Skills" section in the project README listing available skills and how to use them. Run claude "/skills" to show the team what's available.

Skill library grows too large for context. If you have 20+ skills, most shouldn't use alwaysActive: true. Use precise auto-activation patterns so only relevant skills load. Consider splitting the repository's skills into team-specific subdirectories.