Skills Format

File Structure

Skills are stored as markdown files in .claude/skills/ within each project directory:

{project}/
├── .skilltrace                          # marker file
├── .claude/
│   └── skills/
│       └── setting-up-nextjs-auth/
│           └── SKILL.md                 # current version
└── .claude/
    └── skilltrace/
        ├── registry.json
        └── versions/
            └── setting-up-nextjs-auth/
                └── v1.md                # archived version

Skill Template

Every skill is a SKILL.md file with YAML frontmatter and a structured body:

---
name: nextjs-clerk-auth
description: Set up Clerk authentication in Next.js 14
version: 2
tags: [auth, nextjs, clerk]
project: www-myapp
created: 2026-05-20
updated: 2026-05-24
---

## Overview
Brief description of what this skill accomplishes.

## When to Use
Conditions and scenarios where this skill applies.

## Quick Reference
Key commands, endpoints, or config at a glance.

## Implementation
1. Install dependencies
2. Configure environment variables
3. Set up middleware
...

## Common Mistakes
Pitfalls and how to avoid them.

Quality Standards

• Specific but agnostic:concrete steps, not tied to one codebase
• Reusable:works in any matching project
• Atomic:one skill, one task, one outcome
• Self-contained:no external dependencies
• End-to-end:complete replay flow

Registry

The .claude/skilltrace/registry.json file maintains an index of all skills. Rebuilt automatically by /skilltrace-reindex.