e7c8214499
- Add statusline.sh and set-topic.sh for per-session status line topics - Update context-load with improved directory walking and output format - Update CLAUDE.md with status line docs and early-call safety note - Update MEMORY.md and README.md with new script/skill entries - Add memory files: script-statusline, skill-decompose, skill-orchestrate, gotchas-gitea - Add networking.md best practice (nftables, systemd sockets, Docker forwarding, TLS) - Update best practices from prior distill: documentation, kubernetes, scripting, secrets-management, skills-development - Prune reflected session logs, add new session logs - Update reflection state Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
47 lines
3.6 KiB
Markdown
47 lines
3.6 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.
|
|
|
|
## Non-ASCII in YAML Frontmatter
|
|
|
|
Skills with em dashes (`—`), smart quotes (`"`), or other non-ASCII characters in the YAML frontmatter `description` field fail to load silently — the skill appears as "Unknown skill" with no error message. The markdown body below the frontmatter can contain any characters.
|
|
|
|
AI models commonly generate em dashes instead of regular dashes. Always validate skill files (e.g., with `cat -A` or a dedicated validator) before committing.
|
|
|
|
## Profile-Independent Skills Directories
|
|
|
|
Each Claude Code profile maintains a completely independent skills directory. Skills installed in one profile (e.g., default) are unavailable in other profiles (e.g., `.claude-octopus`). Install scripts must use the profile-aware config directory path rather than hardcoded paths like `~/.claude/skills/`.
|