Blog
How to Write a /done Skill for Claude Code
Every coding session with Claude Code ends the same way: you've built something, files are scattered across your working tree, and you need to wrap up cleanly. A /done skill automates that entire process — updating docs, fixing lint, committing with a meaningful message, and generating a productivity report.
March 2026 · Alex Miller
What Are Claude Code Skills?
Skills are markdown files that live in your project at .claude/skills/<name>/SKILL.md. When you type /<name> in a Claude Code session, the skill's content gets injected as a prompt. Think of them as reusable, project-specific instructions that Claude follows step by step.
Skills can accept arguments, reference other skills, and use any tool Claude Code has access to — reading files, running shell commands, editing code, and more. They're checked into your repo so every team member gets the same workflow.
Why Build a /done Skill?
Without a structured wrap-up process, sessions tend to end with uncommitted changes, missing docs, and lint warnings that pile up. A /done skill solves this by enforcing a consistent end-of-session checklist:
Architecture docs stay current
Every session updates the relevant docs in docs/architecture/, so the next person (or Claude session) has context.
Lint stays clean
Errors get fixed before they compound. Only session files are touched — no surprise diffs in unrelated code.
Commits are meaningful
Conventional commits with productivity stats in the body. You can see duration, files changed, and areas touched at a glance.
File sizes stay under control
A per-session file size report shows how many files are in each line-count bucket, broken down by type. Spot bloated files before they become a problem.
Test coverage is tracked
If you have a test runner, coverage stats are included in every commit. If not, the skill notes it and moves on — no broken builds.
You get a productivity report
Session duration, prompt count, lines changed — all computed automatically so you can track how you work.
Anatomy of a /done Skill
The skill file lives at .claude/skills/done/SKILL.md. It starts with YAML frontmatter for metadata, then contains the full instructions in markdown. Here's the structure:
1. Frontmatter & Timing
The frontmatter tells Claude Code when to suggest this skill and what arguments it accepts. The timing section ensures every phase is benchmarked.
--- name: done description: Wrap up a coding session — update docs, lint, then commit. argument-hint: "[optional commit message]" --- Wrap up the current coding session. ## Timing & Stats At the start of EACH phase, run `date +%s` to capture a timestamp. At the end of each phase, capture another timestamp and compute the elapsed time. After all phases complete, output a summary table like this: ``` /done summary ─────────────────────────────────────── Phase Time Count ─────────────────────────────────────── Architecture docs 12s 2 updated, 1 created Lint fix 18s 3 errors fixed, 0 remaining File sizes 5s 42 files, 1 over 500 lines Tests + coverage 8s 12 passed, 0 failed, 42% lines Commit 3s 1 commit, 14 files staged Report 1s session complete ─────────────────────────────────────── Total 47s ```
2. Session File Detection
This is the most important design decision. You can't rely on git diff HEAD~N because multiple Claude Code sessions might be running on the same branch. Instead, the skill tells Claude to use its own conversation memory.
## Determining Session Files Multiple Claude Code sessions may run concurrently on the same branch, so git history (e.g., `HEAD~3`) is NOT a reliable way to determine which files this session changed. **Use your own memory of the conversation.** You know every file you read, edited, created, or wrote during this session. Compile that list directly — it's the only reliable source. To get the list: 1. Review the conversation history for all Read, Edit, Write, Bash tool calls that modified files 2. Compile the deduplicated list of file paths 3. For line counts, run `git diff --stat` on only uncommitted files
3. The Phases
Break the wrap-up into discrete phases. Each project will have different needs — a project with tests might include a testing phase, while a static site might skip it. Here's a 6-phase setup that covers most projects:
### Phase 1: Update Architecture Docs 1. Gather session changes — compile the list of files YOU touched 2. Identify affected areas (pages, components, styles, etc.) 3. Read the changed code to understand the current state 4. Check existing docs in `docs/architecture/` 5. Write/update docs covering: Overview, Key files, Data flow, Important patterns ### Phase 2: Lint Fix Run your linter and fix errors ONLY in session files. Do NOT fix pre-existing errors in untouched files. ### Phase 3: File Sizes Scan all source files and build a distribution table by line-count bucket and file type. Compare to previous snapshot. ### Phase 4: Tests + Coverage Run tests if a runner is configured. Generate a short coverage summary. Skip gracefully if no test runner exists. ### Phase 5: Commit Stage all changed files and commit using conventional commits. Include a session productivity summary in the commit body. ### Phase 6: Report Output timing table, productivity stats, ASCII art of what was built, and a dramatic goodbye message.
4. Safety Rules
Guardrails prevent the skill from doing anything destructive. These are non-negotiable.
## Rules - Only fix lint errors in files you changed this session - NEVER use --no-verify, --amend, or force push - NEVER commit .env, secrets, or credential files - Do NOT push unless the user explicitly asks
What It Looks Like in Action
Here's real output from running /done at the end of a session where we built this very blog post:
The summary table and productivity report
ASCII art and the dramatic goodbye
Tracking File Sizes & Test Coverage
Two optional phases that pay dividends over time. The file size report gives you a birds-eye view of your codebase health — how many files are small and focused vs. bloated and overdue for a refactor. The test coverage report keeps you honest.
File Size Distribution
The skill scans all source files, groups them by line count and file type, and outputs a table. It also saves a snapshot to Claude Code's memory so the next session can show a trend comparison — are your files getting smaller or bigger?
File sizes by type ────────────────────────────────────────────────────────── Lines .tsx .ts .css .md .json Total ────────────────────────────────────────────────────────── ≤ 50 3 1 0 4 2 10 51–150 5 0 1 2 1 9 151–300 4 1 0 1 0 6 301–500 2 0 0 0 0 2 501–1000 1 0 1 0 0 2 1001–2000 0 0 0 0 0 0 2000+ 0 0 0 0 0 0 ────────────────────────────────────────────────────────── Total 15 2 2 7 3 29 Largest: page.tsx (491 lines)
Test Coverage Summary
If your project has a test runner configured, the skill runs your test suite and generates a coverage summary. If not, it gracefully notes "no test runner configured" and moves on — no broken builds, no skipped commits.
Test coverage ────────────────────────────────────── Stmts: 45% Branch: 30% Funcs: 38% Lines: 42% Tests: 12 passed, 0 failed ──────────────────────────────────────
Customizing for Your Project
The beauty of a /done skill is that it adapts to your stack. Here are the knobs you should tune:
Add or remove phases
A React Native app might add a "Write Tests" phase that extracts pure logic from components into utils/ and writes unit tests. A static site might skip testing entirely. A monorepo might add a "Type Check" phase with tsc --noEmit.
Add coverage and file size tracking
For projects with tests, add phases that run coverage reports and compare against previous sessions. You can save snapshots to Claude Code's memory directory and show trend lines over time — watch your coverage climb session by session.
Compose with other skills
Instead of inlining lint logic, create a separate /lint-fix skill and call it from /done. Same for /rename (to name the session) or /simplify (to review for code quality before committing).
Tune the commit format
The commit body is where the session summary lives. Customize what metrics matter to your team. Here's what ours looks like:
feat: add workshop scheduling page Session summary: - Duration: 1h 23m - User prompts: 8 - Files modified: 14, created: 3 - Lines: +187 / -42 - Lint: 3 errors fixed, 0 remaining in session files - File sizes: 29 files, largest 491 lines - Tests: 12 passed, 0 failed - Coverage: Stmts 45% | Lines 42% - Docs: 2 updated, 1 created - Areas: src/app/workshop, src/app/page.tsx Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Getting Started
Create the skill file
Make a directory at .claude/skills/done/ and add a SKILL.md file with the frontmatter, phases, and rules shown above.
Adapt the phases to your stack
Add test phases if you have a test runner. Remove architecture docs if you don't want them. The phases are just markdown sections — add or remove as needed.
Commit it to your repo
Check the skill into version control so every team member and every Claude Code session gets the same workflow.
Type /done at the end of your session
That's it. Claude handles the rest — docs, lint, commit, and a productivity report with ASCII art.
The Full Picture
Here's the entire /done workflow visualized — from the summary table to the before/after comparison to the 6-phase pipeline:
Want help setting up Claude Code for your team?
I run AI workshops that cover Claude Code skills, workflows, and getting the most out of AI-assisted development.
Book a 30-Minute Call