# Custom Claude Skills — Memory

## Skill Development Learnings

- Skills in `~/.claude/skills/` are available across all projects (personal scope)
- `!`command`` injection runs at skill load time — great for pre-fetching git logs, file contents, etc.
- Inline skills (no `context: fork`) retain full conversation history — essential for reflection-type skills
- `allowed-tools` reduces permission prompts by declaring what the skill needs upfront
- **Bang-command exit codes matter:** `!`command`` fails the skill if the command exits non-zero, even if the output is valid. Scripts that use exit 1 as "issues found" (not error) need `|| true` appended in the skill invocation.
- **Every binary in bang-commands needs allowed-tools coverage:** `ls`, `head`, `cat`, `hostname` — each needs its own `Bash(<binary> *)` pattern or the skill fails to load
- **Broad `Bash(git *)` is acceptable when justified:** orchestrate skill needs worktree/branch/merge/checkout — listing 6+ specific subcommands is worse than the broad pattern with a validator warning
- **Skills that launch containers need careful entrypoint handling:** Use `--entrypoint uid-wrapper.sh` when running `claude --print` in agent containers — the default entrypoint expects AGENT_PAYLOAD

## Task Orchestration Skills (2026-03-24)

Added `/decompose` and `/orchestrate` for parallel container agent work:
- `/decompose` breaks tasks into subtasks with dependency graph → `.agent-tasks.json`
- `/orchestrate` dispatches container agents in git worktrees, checks status, updates state
- Designed for `/loop 2m /orchestrate` auto-polling pattern
- Git worktrees provide isolation: each agent gets its own branch, no file conflicts
- No hardcoded concurrency limit — user approves `max_concurrent` during decompose
- Memory files created in `claude-foundations/memory/skill-decompose.md` and `skill-orchestrate.md`