From tools
Deep-dive the current project and write durable context files for future Claude sessions
How this skill is triggered — by the user, by Claude, or both
Slash command
/tools:diveThis skill is limited to the following tools:
The summary Claude sees in its skill listing — used to decide when to auto-load this skill
Perform a comprehensive deep-dive on the current project. The user has explicitly invoked this — burn the tokens, take the time, capture every minute detail. Future Claude sessions will Read the artifacts you produce.
Perform a comprehensive deep-dive on the current project. The user has explicitly invoked this — burn the tokens, take the time, capture every minute detail. Future Claude sessions will Read the artifacts you produce.
Write durable context files into <project>/.claude/context/. Do not touch the project's CLAUDE.md or the user's global CLAUDE.md. After you finish, tell the user the single line they can add to their project CLAUDE.md if they want the context auto-loaded: @.claude/context/index.md.
For a genuinely tiny project (a single-file script, a config-only repo), don't pad six files — collapse to just index.md + workflows.md and say so in the report. "All six" is the default for anything with real structure, not a hard floor.
| Path | Contents |
|---|---|
.claude/context/index.md | One-paragraph project summary + table of contents linking to the other five files. ~150 words. |
.claude/context/architecture.md | System layering, data flow, key abstractions, module boundaries, where state lives, how external services are integrated. |
.claude/context/conventions.md | Lint-enforceable surface AND non-trivial code style — see expansion below. Cite real examples with path:line. |
.claude/context/gotchas.md | Surprises, footguns, "looks wrong but is right" cases, known sharp edges. Mine from comments, commit messages, code that contradicts intuition. |
.claude/context/workflows.md | Exact commands for: install, build, dev, test, lint, typecheck, deploy. Mirror CI exactly. Note required env vars / credentials. |
.claude/context/entry-points.md | Where execution starts. Main/index/cli/server files. Route registrations. Background workers. Cron jobs. With path:line references. |
pwd # confirm project root
ls -la # top-level
git rev-parse --show-toplevel 2>/dev/null # confirm git repo
git log --oneline -30 2>/dev/null # recent activity
Then Read the root-level config files that exist: package.json, pnpm-workspace.yaml, pyproject.toml, Cargo.toml, go.mod, Gemfile, composer.json, Makefile, justfile, Taskfile.yml, tsconfig.json, .editorconfig, .eslintrc*, .prettierrc*, ruff.toml, biome.json, .github/workflows/*.yml, existing CLAUDE.md, existing README.md, existing CONTRIBUTING.md, existing AGENTS.md. Skip what doesn't exist.
Glob top-level directories: Glob "*/".
This is enough to identify project type, build/test commands, and area boundaries.
Use the superpowers:dispatching-parallel-agents skill. Dispatch ONE Explore agent per major area discovered in step 1. Common areas:
Each agent prompt should include:
path:line references to key symbols), recurring patterns observed, conventions specific to this area, any surprisespath:line. This is raw material for step 6's code-style pass — the synthesis happens later, the agent's job is to surface examples.Read files, not just Glob them — they need real understandingFor small projects (one or two top-level dirs), skip parallelization and do it serially.
After agent reports come back, pick the single most important user-facing flow (e.g., for a web app: HTTP request → route → handler → DB → response; for a CLI: argv parse → command → business logic → output; for a library: public API → core → side effects). Trace it file-by-file. Note layering, error handling style, where transactions/locks happen, where logging happens. This goes into architecture.md.
If .github/workflows/, .gitlab-ci.yml, circle.yml, or similar exists, read the actual CI commands. They are the gold standard for workflows.md — match them exactly.
Run Grep for these patterns to surface non-obvious things:
rg -n "TODO|FIXME|HACK|XXX|WORKAROUND|NOTE:" -g '*.{ts,tsx,js,jsx,py,go,rs,rb,php,java,kt,swift}' .
git log --oneline -100 --grep='fix\|bug\|hotfix\|revert' -i
(Use rg — grep -r --include="*.{a,b}" does not expand brace globs on BSD/macOS grep and would silently match nothing. rg is in the Brewfile; if a project is somehow without it, fall back to multiple grep --include= flags or find -name.)
Recent reverts and "fix" commits often point at subtle issues worth recording.
A linter enforces formatting; it cannot tell future Claude how this team writes code. This step is
about the abstract, sentimental, taste-driven style that survives prettier --check and still
makes a PR feel wrong. Do this before writing conventions.md, not after.
Open 6–10 real source files spanning the languages in the repo (handlers, library helpers, components,
shell, infra modules). Read them top-to-bottom. Then characterize each axis below with at least one
path:line citation and a one-line claim. If a claim has counter-examples, note them — don't lie.
Required axes:
Naming
is*/has*-prefixed? Do module-scope singletons get a different convention from locals?<noun>Handler? *Service? use*?).snake_case vs kebab-case vs PascalCase enum values).Function shape
function declarations? Does it depend on
exported-vs-internal?Module layout
types.ts, or co-located with the function that returns
them?Comments
NOTE:, WARNING:, TODO:)? JSDoc/docstrings?
Inline? File headers?Repetition vs reuse
Error handling
Response object? plain object? framework helper?).console.error? observability lib? What does the team consider
"enough" context in a log line?Domain-specific patterns (cover whichever applies)
tailwind-variants, cva), slot vs snippet, prop spreading,
where state lives (component-local vs context vs store).What the linter cannot enforce but the team clearly cares about
fix(convention) / cleanup(style) commit, a NOTE
comment scolding a prior PR, a wrapper around a stdlib call that has no functional purpose.
These reveal the "taste" rules.Output of this step lives in conventions.md under a dedicated "Code style — <lang>" section
per language with sub-headings for the axes above. Cite path:line ruthlessly. Don't paraphrase what
a linter could check — describe what a senior engineer on this team would catch in code review.
If a style guide exists at style/*, docs/style*, CONTRIBUTING.md, or AGENTS.md, Read it and
treat it as prescribed style — then verify against real code whether the prescription is
actually followed and note any drift.
Style for all files:
path:line for every code reference so the user can jump.conventions.md may run longer (~1500–2500) because the code-style
pass produces dense, citation-heavy content. Sparse sections are fine — write "(none observed)"
rather than padding.index.md includes a one-line summary per other file and a Last generated: <date> footer.conventions.md MUST contain the code-style pass output from step 6 — not just lint rules.Create .claude/ and .claude/context/ directories if they don't exist. Use Write for each file (these are new artifacts — no need to Read first unless overwriting).
After all writes complete, print to chat:
CLAUDE.md if the user wants auto-loading: @.claude/context/index.md.CLAUDE.md or any global Claude config file..claude/context/ already contains files, ask the user whether to overwrite before proceeding.verify skill's discipline — every claim about the project should be backed by a file you actually Read (or a command you actually ran). Don't speculate.npx claudepluginhub pandoks/.dotfiles --plugin toolsCreates, edits, and optimizes skills for Claude Code, including drafting, evaluating with test prompts, iterating on performance, and improving skill descriptions for better triggering accuracy.