diff --git a/config/opencode/skills/ask-claude/SKILL.md b/config/opencode/skills/ask-claude/SKILL.md new file mode 100644 index 0000000..b667eee --- /dev/null +++ b/config/opencode/skills/ask-claude/SKILL.md @@ -0,0 +1,149 @@ +--- +name: ask-claude +description: Consult Claude (Anthropic's flagship model, Opus-class) as an oracle when you are uncertain, stuck, or facing a problem that needs deeper reasoning than your current model provides. Trigger when you would otherwise guess, when the user asks a hard architectural / design / debugging question, when you have produced two contradictory hypotheses, or when a code review needs a second opinion. Calling out to `claude` gives you results from a much more intelligent model — use it instead of guessing. +--- + +# Ask Claude + +Run `claude -p ""` via the `bash` tool to get a one-shot answer from +Claude. Claude is significantly more capable at reasoning, code review, and +architectural judgment than smaller models — when you are not sure, ask. + +## When to use + +- You are uncertain between two approaches and want a second opinion. +- The user asked a question whose answer you would otherwise guess. +- You have a tricky bug, a subtle race condition, or a non-obvious design call. +- You want a code review on a diff before reporting "done". +- You need a careful read of a long document or a hairy stack trace. + +Do **not** use it for trivial lookups (use `web-search`), simple file edits, or +anything you are already confident about — calls cost money and time. + +## Basic invocation + +```bash +claude -p "Your question here, with all relevant context inline." +``` + +The prompt should be **self-contained** — Claude starts with no memory of this +conversation. Include the file paths, code snippets, error messages, and +what you have already tried. + +## Piping context via stdin + +For longer context (a file, a diff, log output), pipe it in: + +```bash +cat path/to/file.rs | claude -p "Review this for race conditions; explain any you find." +``` + +```bash +git diff main...HEAD | claude -p "Spot bugs or risky changes in this diff." +``` + +## Permissions + +In `-p` mode there is no human to approve prompts, so anything not explicitly +permitted is **denied**. Default behaviour: Claude can reason about the text +you give it but cannot touch the filesystem, run shell commands, or hit the +network. That is usually exactly what you want for an oracle call. + +When Claude does need tool access, you control it with these flags: + +### `--allowedTools` / `--disallowedTools` + +Whitelist or blacklist tools. Names are space- or comma-separated, and each +entry can carry a permission spec in parentheses to narrow the scope. + +```bash +# Read-only project access — the most common upgrade +claude -p --allowedTools "Read Grep Glob" "..." + +# Allow only specific bash subcommands +claude -p --allowedTools "Read Grep Glob Bash(git diff:*) Bash(git log:*)" "..." + +# Allow web fetches, but only to one domain +claude -p --allowedTools "WebFetch(domain:docs.python.org)" "..." + +# Block one tool, allow the rest of the defaults +claude -p --disallowedTools "Bash" "..." +``` + +Spec syntax cheatsheet: +- `Bash` — every shell command (broad; avoid). +- `Bash(git *)` — any `git` invocation. +- `Bash(git diff:*)` — `git diff` and its sub-args only. +- `Read` / `Grep` / `Glob` — usually safe to allow whole. +- `Edit(./src/**)` / `Write(./src/**)` — directory-scoped writes. +- `WebFetch(domain:example.com)` — pin web access to one host. + +### `--tools` + +Coarser switch over the built-in toolset. Use `--tools ""` to disable +**everything** built-in (only MCP tools and what `--allowedTools` adds), or +`--tools "Read,Edit,Bash"` to pick a subset. `--allowedTools` then layers on +top with finer-grained specs. + +### `--permission-mode ` + +Sets the default behaviour for anything not covered by allow/disallow: + +| Mode | Effect | +|---------------------|--------------------------------------------------------------| +| `default` | prompt; in `-p` mode this means "deny" (no human present). | +| `dontAsk` | silently deny anything not pre-allowed — clean for `-p`. | +| `plan` | read-only planning; Claude proposes but cannot edit or run. | +| `acceptEdits` | auto-accept file edits; still prompts for Bash etc. | +| `auto` | model decides per-call; treat as semi-trusted. | +| `bypassPermissions` | skip all checks. Equivalent to `--dangerously-skip-permissions`. | + +```bash +# Strict deny-by-default with an explicit allowlist (recommended for -p) +claude -p --permission-mode dontAsk \ + --allowedTools "Read Grep Glob" \ + "Audit error handling in src/auth/." + +# Plan mode for a design review — Claude reads, thinks, won't touch anything +claude -p --permission-mode plan "Propose a refactor for X." +``` + +### `--add-dir` + +Without it Claude only sees the current working directory. Add others when +the question spans repos: + +```bash +claude -p --allowedTools "Read Grep Glob" \ + --add-dir ../other-repo --add-dir /etc/nixos \ + "Compare how both projects handle config loading." +``` + +### `--dangerously-skip-permissions` + +Bypasses all checks. Only use inside a sandbox with no network and no secrets +mounted. For oracle-style calls there is essentially no reason to set this — +if Claude needs to do destructive things, you should be doing them, not it. + +### Cost and model controls + +These are not permissions but belong in the same risk-management box: + +- `--model opus` / `--model sonnet` — pick the tier. Opus for hard reasoning, + Sonnet when speed/cost matters. +- `--output-format json` — stable structured output for piping into `jq`. + +## Output + +Default output is plain text on stdout, suitable for piping or for showing to +the user. For machine-readable output use `--output-format json` and parse +with `jq`. + +## Don'ts + +- Don't call `claude -p` in a loop or for trivial questions — it is expensive. +- Don't pass the entire conversation history; distill the question first. +- Don't ask Claude to "do" multi-step refactors with file writes — collect its + recommendations and apply them yourself, so you stay in control. +- Don't forget that Claude has no memory between calls — every invocation + needs the full context.