003 v1.0 Core Learning Documented

Managing Skills

Provides guided workflows for creating, searching, listing, and organizing skills.

Structured Data

Capability Metadata

Field	Value
ID	CAP-003
Version	v1.0
Domain	Core Learning
Status	Documented
Related	CAP-002, CAP-004, CAP-005
Source	`src/management/skill-manager.ts`
Storage	~/.claude/commands/ (user) + .claude/commands/ (project)

Configuration Reference

Skill file format: YAML frontmatter + markdown body

---
name: my-skill
description: What this skill does
triggers:
  - keyword-one
  - keyword-two
tools:
  - Read
  - Edit
  - Bash
---

Skill instructions in markdown here.

Project skills: .claude/commands/ (override user-level)

User skills: ~/.claude/commands/ (cross-project defaults)

Technical Specifications

Class: SkillManager

class SkillManager {
  create(name: string, content: string): Skill;
  search(query: string): Skill[];
  list(scope?: 'project' | 'user'): Skill[];
  update(name: string, content: string): Skill;
  delete(name: string): void;
  resolve(name: string): Skill; // project overrides user
}

interface Skill {
  name: string;
  description: string;
  triggers: string[];
  tools: string[];
  scope: 'project' | 'user';
  path: string;
  content: string;
}

Resolution rule: project-level skills override user-level on name conflict

Overview

Managing Skills is the organizational layer — the library card catalog for everything the system learns. Skills live as markdown files with YAML frontmatter in two locations: .claude/commands/ for project-level skills and ~/.claude/commands/ for user-level skills. Project-level skills override user-level on name conflict, enabling project-specific specialization without losing cross-project defaults.

The SkillManager class provides the full CRUD interface: create new skills from suggested drafts or manually, search by keyword across all loaded skills, list skills by scope, update existing skills when they need refinement, and delete skills that are no longer relevant. Every operation is file-based — skills are just markdown files, readable and editable by humans without any tooling.

This file-based approach is a deliberate design decision. It keeps the skill library inspectable, version-controllable with git, portable between machines, and independent of any database or proprietary format. A skill is exactly what it looks like: a markdown file with metadata at the top and instructions in the body.

History

Managing Skills was part of the v1.0 core. The dual-location design — project-level and user-level skill directories — was fundamental from the start. Project-specific patterns (how this codebase handles authentication, this team's commit message style) belong in version control alongside the code. Cross-project habits (always run lint before commit, always read CLAUDE.md on session start) belong in the user's home directory, available everywhere. Keeping these separate prevents cross-project leakage while enabling knowledge reuse.

In v1.9, Progressive Disclosure (CAP-023) extended skill management by allowing large skills to auto-decompose into multi-file structures — a single entry-point skill that lazy-loads sub-skills on demand. This addressed a limitation that emerged as skill libraries grew: a single large skill file was wasteful to load when only part of it was needed. The core SkillManager remained unchanged; Progressive Disclosure added an optional decomposition layer on top.

Key Concepts

For Students & Teachers

Think of the skill library like a recipe box. Some recipes are family favorites — they go in the family recipe box (user-level), always available no matter whose kitchen you're cooking in. Others are specific to this week's meal plan — they go on the fridge (project-level), and they take priority when you're planning this specific dinner.

If both boxes have a recipe called "pasta sauce," you use the one on the fridge — the project-specific version wins. This lets each project customize shared skills without affecting everyone else's copy.

And because skills are just text files with a standard format, you can always open one in any text editor, read what it says, and understand exactly what it will do. There's no magic — just organized markdown files that Claude knows how to find and load.

Usage Examples

Example 1: Create a skill manually

# Create a new project-level skill file directly
cat > .claude/commands/my-workflow.md << 'EOF'
---
name: my-workflow
description: Run lint, test, and commit in sequence
triggers:
  - lint
  - test
  - commit
tools:
  - Bash
---

When asked to lint-test-commit:
1. Run `npm run lint` and fix any errors
2. Run `npm test` and confirm all tests pass
3. Stage and commit with a conventional commit message
EOF

Example 2: List all skills by scope

# Inside a Claude Code session
/sc:status

# Output shows loaded skills by scope:
# Project skills (.claude/commands/):
#   - my-workflow (triggers: lint, test, commit)
#   - cap-page-template (triggers: capability, page, CAP)
#
# User skills (~/.claude/commands/):
#   - beautiful-commits (triggers: commit, git)
#   - code-review (triggers: review, PR)

Example 3: Search skills by keyword

# Find skills related to testing
ls ~/.claude/commands/ | grep -i test
ls .claude/commands/ | grep -i test

# Or ask Claude directly in session:
# "What skills do you have loaded that relate to testing?"