Skills System Overview

The skills system is Luci's primary knowledge base for domain-specific workflows. Skills are the first thing to check before doing anything from scratch.

Inventory

• 147 active skills in ~/.claude/skills/ (as of 2026-05-17)
• 53 retired skills in ~/.claude/skills/_retired/
• Retired skills are indexed in ~/.claude/skills/_retired/INDEX.md with keyword triggers for lazy reactivation

Skill Architecture

Every skill is a directory under ~/.claude/skills/{skill-name}/ containing:

• SKILL.md -- the main file. Contains YAML frontmatter (metadata) and markdown body (instructions)
• references/ -- optional subdirectory for supporting files (data dictionaries, templates, examples)

SKILL.md Frontmatter

The YAML frontmatter controls discovery and auto-triggering:

---
name: dev-loop
preamble-tier: 2          # optional: controls load priority
version: 1.0.0            # optional: tracks skill evolution
description: >
  Universal development skill for ALL MC tickets...
  Triggers on: "dev loop", "development loop", "full dev workflow"...
---

Key fields: - name -- skill identifier (matches directory name) - description -- keyword-rich text that Claude matches against user messages for auto-triggering. This is the primary discovery mechanism. - preamble-tier -- optional priority level for context loading - version -- optional semantic version

Body Content

After the frontmatter, the markdown body contains: - Step-by-step workflow instructions - Decision trees and classification tables - Templates and examples - References to other skills or external tools

Discovery and Triggering

Skills are discovered through three mechanisms:

1. Auto-trigger -- Claude matches the user's message against the description field keywords. If a match is found, the skill is loaded and followed automatically.
2. Explicit invocation -- user types a slash command (e.g., /dev-loop, /deep-research) or mentions the skill by name
3. Lazy loading from retired -- if no active skill matches, Claude checks ~/.claude/skills/_retired/INDEX.md for keyword matches, then reads the full SKILL.md from the retired directory

Active vs Retired

Skill Management Rules

• Skills-first principle -- before doing anything from scratch, check if a skill exists. This is a hard rule across all Claude instances (Luci, Lucienne, CoWork).
• Edit in place -- skills are edited directly in ~/.claude/skills/. Changes take effect in the next session automatically.
• Copy to repo -- after editing, copy changed files to ~/.claude-repo/skills/ so the next skills-sync pushes to GitHub (conrelma/claude)
• Cross-machine sharing -- the skill repo is shared across Windows, Mac, Luci, and CoWork. Avoid hardcoded paths; use relative paths or platform detection.
• Never delete without approval -- skills are only deleted with explicit approval from Elmar. Retire instead.
• Role briefs reference skills, never copy them -- a role brief points to the skill path. When the skill improves, all consumers benefit.

Skill Sync

The skills-sync scheduled task pushes skill changes from ~/.claude-repo/skills/ to GitHub. All machines pull from the same repo, so a skill edited on Luci becomes available on Lucienne's Mac and vice versa.

See also: 03-scheduler/overview for the skills-sync task schedule.

Related

• 07-skills/key-skills -- the most important skills for daily operations
• 02-mission-control/overview -- how 07-skills/key-skills|dev-loop integrates with ticket processing
• 06-vault-and-memory/overview -- how skills reference vault data

Key Takeaways

• 147 active skills + 53 retired = 200 total skills in the system
• SKILL.md frontmatter description field is the primary auto-trigger mechanism
• Skills-first is a hard rule: always check before building from scratch
• Edit directly in ~/.claude/skills/, copy to ~/.claude-repo/skills/ for sync
• Retired skills are not deleted -- they live in _retired/ with an INDEX.md for lazy loading
• Never delete a skill without Elmar's explicit approval