e94417b896
Includes: spec-driven and test-driven development best practices, reproduce-before-fixing debugging workflow, require-plan-file hook, find-project-root script, session logs, memory files for decisions/ gotchas/process-lessons, and updates to existing best practice topics. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
37 lines
2.7 KiB
Markdown
37 lines
2.7 KiB
Markdown
# Claude Code Skills
|
|
|
|
## Skill Structure
|
|
|
|
- Each skill lives in `skills/<skill-name>/SKILL.md`
|
|
- Skills should be project-agnostic where possible — use dynamic context injection to adapt
|
|
- After adding a new skill, run the install script to register it
|
|
- Skills only useful for one project should live in that project's `.claude/skills/` instead
|
|
|
|
## Authoring Guidelines
|
|
|
|
- **Inline by default** — only use `context: fork` if the skill genuinely doesn't need conversation history
|
|
- **Pre-fetch context** with `!`command`` injection to reduce tool calls during execution
|
|
- **Restrict tools** with `allowed-tools` to the minimum needed — reduces permission prompts
|
|
- **Use $ARGUMENTS** for user input, `$0`, `$1` etc. for positional args
|
|
- Dynamic commands in `!`command`` run at skill load time, not during Claude's execution
|
|
|
|
## Portable Path Resolution
|
|
|
|
- **Use `CLAUDE_PROJECT_ROOT` env var** for cross-project path references in `!`command`` blocks. Hardcoded absolute paths (e.g., `~/dev/claude/...`) are user-specific. Relative paths (`../`) break depending on CWD and can trigger sandbox violations when they resolve outside allowed directories.
|
|
- **Add a detection fallback.** Include a "Step 0" in skill instructions that detects the project root by walking up the directory tree to find the highest `CLAUDE.md` if the env var isn't set. This makes skills work even without prior setup.
|
|
- **Keep config paths relative to the root.** Settings files should use paths relative to `CLAUDE_PROJECT_ROOT` (e.g., `projects_dir: projects`) rather than absolute paths, so they're portable across machines.
|
|
|
|
## Skill Discovery Timing
|
|
|
|
- **Skills are discovered at session start, not dynamically.** Creating or symlink a new skill mid-session requires restarting Claude Code to use it as a slash command.
|
|
- **Broken symlinks cause silent failures under `set -e`.** `readlink -f` on a broken symlink returns empty string. The install script should validate symlinks and remove stale ones.
|
|
|
|
## `!`command`` Gotchas
|
|
|
|
- **No `$()` command substitution** — the permission checker rejects commands containing `$()`
|
|
- **No complex shell pipelines relying on subshells** — keep commands simple and self-contained
|
|
- **`allowed-tools` patterns must match the command binary** — each binary used in `!`command`` blocks needs its own pattern
|
|
- **Prefer specific tool patterns over broad ones** — `Bash(git log *)` is safer than `Bash(git *)`
|
|
- **Fallback to tool instructions for dynamic paths** — if a command needs `$ARGUMENTS` to compute a path, use a plain-text instruction telling Claude to use the Read tool instead
|
|
- **Env var expansion works** — `${CLAUDE_PROJECT_ROOT}` expands in `!`command`` blocks because they run as shell commands. This is the recommended pattern for portable cross-project paths.
|