nixcfg/config/opencode/skills/ask-claude/SKILL.md

---
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 -- "<prompt>"` 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

Always use this shape: `-p` first, all flags next, then `--`, then the
prompt as a single positional argument.

```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.

### Always use `--` before the prompt

Several flags accepted by `claude` are **variadic** and will silently swallow
your prompt as if it were another value:

- `--allowedTools <tools...>`
- `--disallowedTools <tools...>`
- `--add-dir <directories...>`
- `--tools <tools...>`
- `--betas <betas...>`

Without `--`, the trailing prompt becomes the last "tool" (or directory, or
beta header) and `claude` exits with `Input must be provided either through
stdin or as a prompt argument when using --print`.

```bash
# BROKEN — "Review the changes…" parsed as a tool name
claude -p --allowedTools "Read Grep Glob" "Review the changes…"

# CORRECT — `--` terminates option parsing, the prompt is the lone positional
claude -p --allowedTools "Read Grep Glob" -- "Review the changes…"
```

Use `--` even when no variadic flag is in play. It is harmless when
unnecessary and removes a whole class of foot-guns.

## 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."
```

Only pipe when the context is small and self-contained. For anything that
spans multiple files, prefer giving Claude repo access (next section) so it
can read surrounding code, not just the patch.

## Code review pattern

For a review of the current branch / working tree, **do not** gather diffs
yourself and stuff them into the prompt. Point Claude at the directory and
let it run `git` and read files on its own — it sees more context (full
files, history, neighbouring code) than a piped diff alone can provide,
and it will only fetch what it actually needs.

Recommended invocation, run from the repo root:

```bash
claude -p --permission-mode dontAsk \
  --allowedTools "Read Grep Glob Bash(git diff:*) Bash(git log:*) Bash(git status:*) Bash(git show:*)" \
  -- "Review the changes on this branch vs main. Flag bugs, risky changes,
      and anything that violates the project's conventions. Read whatever
      files you need for context."
```

Why this is better than `git diff … | claude -p`:

- Claude can open the *full* file around a hunk, not just the ±3 lines of
  context in the patch.
- Claude can follow references — call sites, tests, related modules.
- The prompt stays small, so the model spends its tokens on reasoning
  instead of re-reading a diff you already had on disk.
- Works for large diffs that would otherwise blow the context window.

Use the piped form only for a tiny, self-contained snippet where extra
repo context genuinely adds nothing.

## 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 <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 gather a giant `git diff` and pipe it in for code review — give
  Claude read-only repo access (see "Code review pattern") and let it pull
  exactly the context it needs.
- 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.