chore: use ~/.agent/skills
This commit is contained in:
parent
c65c0d8756
commit
4d32148059
5 changed files with 5 additions and 0 deletions
|
|
@ -1,215 +0,0 @@
|
|||
---
|
||||
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.
|
||||
|
|
@ -1,10 +0,0 @@
|
|||
---
|
||||
name: grill-me
|
||||
description: Interview the user relentlessly about a plan or design until reaching shared understanding, resolving each branch of the decision tree. Use when user wants to stress-test a plan, get grilled on their design, or mentions "grill me".
|
||||
---
|
||||
|
||||
Interview me relentlessly about every aspect of this plan until we reach a shared understanding. Walk down each branch of the design tree, resolving dependencies between decisions one-by-one. For each question, provide your recommended answer.
|
||||
|
||||
Ask the questions one at a time.
|
||||
|
||||
If a question can be answered by exploring the codebase, explore the codebase instead.
|
||||
|
|
@ -1,86 +0,0 @@
|
|||
---
|
||||
name: web-search
|
||||
description: Search the web and fetch page content via the user's private SearXNG instance at search.hoyer.world. Use this whenever current information is needed - library docs, error message lookups, recent releases, API references, or any general research that goes beyond training data. Trigger words include "search", "look up", "find docs for", "what's the current", "latest version of". Always prefer this over guessing from memory.
|
||||
---
|
||||
|
||||
# Web Search via SearXNG
|
||||
|
||||
The user runs a private SearXNG instance at `$SEARXNG_URL`
|
||||
(default: `https://search.hoyer.world`). Use it for all web research.
|
||||
|
||||
Run searches via the `bash` tool. Do NOT attempt MCP or built-in web search.
|
||||
|
||||
## Search
|
||||
|
||||
```bash
|
||||
curl -sfG "${SEARXNG_URL:-https://search.hoyer.world}/search" \
|
||||
--data-urlencode "q=QUERY HERE" \
|
||||
--data-urlencode 'format=json' \
|
||||
--data-urlencode 'language=en' \
|
||||
--data-urlencode 'safesearch=0' \
|
||||
| jq -r '.results[0:8][] | "## \(.title)\n<\(.url)>\n\(.content // "")\n"'
|
||||
```
|
||||
|
||||
Keep queries short (3–6 words). For follow-ups, increment `pageno` instead of
|
||||
re-running the same query:
|
||||
|
||||
```bash
|
||||
... --data-urlencode 'pageno=2' ...
|
||||
```
|
||||
|
||||
## Categories
|
||||
|
||||
Bias results to relevant engines via `categories`:
|
||||
|
||||
| Category | Use for |
|
||||
|------------|-----------------------------------------------|
|
||||
| `general` | default |
|
||||
| `it` | programming, dev tools (GitHub, SO, MDN, …) |
|
||||
| `repos` | source-code search |
|
||||
| `news` | recent events |
|
||||
| `science` | papers, arXiv, PubMed |
|
||||
|
||||
```bash
|
||||
... --data-urlencode 'categories=it' ...
|
||||
```
|
||||
|
||||
## Time filtering
|
||||
|
||||
For "current"/"latest" queries add `time_range=month` or `year` to drop
|
||||
stale results:
|
||||
|
||||
```bash
|
||||
... --data-urlencode 'time_range=year' ...
|
||||
```
|
||||
|
||||
## Fetching a page
|
||||
|
||||
For full content of a result URL, use pandoc via `nix run` (no install needed):
|
||||
|
||||
```bash
|
||||
curl -sfL --max-time 15 \
|
||||
-H 'User-Agent: Mozilla/5.0' \
|
||||
"$URL" \
|
||||
| nix run nixpkgs#pandoc -- -f html -t gfm --wrap=none 2>/dev/null \
|
||||
| sed -E 's/!\[[^]]*\]\([^)]*\)//g' \
|
||||
| head -c 12000
|
||||
```
|
||||
|
||||
The first `nix run` invocation may take a few seconds while pandoc is fetched
|
||||
into the Nix store; subsequent calls are instant.
|
||||
|
||||
For very simple pages where you only want plain text:
|
||||
|
||||
```bash
|
||||
curl -sfL --max-time 15 -H 'User-Agent: Mozilla/5.0' "$URL" \
|
||||
| nix run nixpkgs#lynx -- -dump -nolist -stdin \
|
||||
| head -c 12000
|
||||
```
|
||||
|
||||
## Don'ts
|
||||
|
||||
- Do not paginate by re-running identical queries — use `pageno`.
|
||||
- Do not fetch more than 3 URLs per task without checking with the user first.
|
||||
- Do not ignore `time_range` for version- or release-related questions.
|
||||
- Do not return raw JSON to the user — always render as the markdown shown above.
|
||||
|
||||
|
|
@ -1,117 +0,0 @@
|
|||
---
|
||||
name: write-a-skill
|
||||
description: Create new agent skills with proper structure, progressive disclosure, and bundled resources. Use when user wants to create, write, or build a new skill.
|
||||
---
|
||||
|
||||
# Writing Skills
|
||||
|
||||
## Process
|
||||
|
||||
1. **Gather requirements** - ask user about:
|
||||
- What task/domain does the skill cover?
|
||||
- What specific use cases should it handle?
|
||||
- Does it need executable scripts or just instructions?
|
||||
- Any reference materials to include?
|
||||
|
||||
2. **Draft the skill** - create:
|
||||
- SKILL.md with concise instructions
|
||||
- Additional reference files if content exceeds 500 lines
|
||||
- Utility scripts if deterministic operations needed
|
||||
|
||||
3. **Review with user** - present draft and ask:
|
||||
- Does this cover your use cases?
|
||||
- Anything missing or unclear?
|
||||
- Should any section be more/less detailed?
|
||||
|
||||
## Skill Structure
|
||||
|
||||
```
|
||||
skill-name/
|
||||
├── SKILL.md # Main instructions (required)
|
||||
├── REFERENCE.md # Detailed docs (if needed)
|
||||
├── EXAMPLES.md # Usage examples (if needed)
|
||||
└── scripts/ # Utility scripts (if needed)
|
||||
└── helper.js
|
||||
```
|
||||
|
||||
## SKILL.md Template
|
||||
|
||||
```md
|
||||
---
|
||||
name: skill-name
|
||||
description: Brief description of capability. Use when [specific triggers].
|
||||
---
|
||||
|
||||
# Skill Name
|
||||
|
||||
## Quick start
|
||||
|
||||
[Minimal working example]
|
||||
|
||||
## Workflows
|
||||
|
||||
[Step-by-step processes with checklists for complex tasks]
|
||||
|
||||
## Advanced features
|
||||
|
||||
[Link to separate files: See [REFERENCE.md](REFERENCE.md)]
|
||||
```
|
||||
|
||||
## Description Requirements
|
||||
|
||||
The description is **the only thing your agent sees** when deciding which skill to load. It's surfaced in the system prompt alongside all other installed skills. Your agent reads these descriptions and picks the relevant skill based on the user's request.
|
||||
|
||||
**Goal**: Give your agent just enough info to know:
|
||||
|
||||
1. What capability this skill provides
|
||||
2. When/why to trigger it (specific keywords, contexts, file types)
|
||||
|
||||
**Format**:
|
||||
|
||||
- Max 1024 chars
|
||||
- Write in third person
|
||||
- First sentence: what it does
|
||||
- Second sentence: "Use when [specific triggers]"
|
||||
|
||||
**Good example**:
|
||||
|
||||
```
|
||||
Extract text and tables from PDF files, fill forms, merge documents. Use when working with PDF files or when user mentions PDFs, forms, or document extraction.
|
||||
```
|
||||
|
||||
**Bad example**:
|
||||
|
||||
```
|
||||
Helps with documents.
|
||||
```
|
||||
|
||||
The bad example gives your agent no way to distinguish this from other document skills.
|
||||
|
||||
## When to Add Scripts
|
||||
|
||||
Add utility scripts when:
|
||||
|
||||
- Operation is deterministic (validation, formatting)
|
||||
- Same code would be generated repeatedly
|
||||
- Errors need explicit handling
|
||||
|
||||
Scripts save tokens and improve reliability vs generated code.
|
||||
|
||||
## When to Split Files
|
||||
|
||||
Split into separate files when:
|
||||
|
||||
- SKILL.md exceeds 100 lines
|
||||
- Content has distinct domains (finance vs sales schemas)
|
||||
- Advanced features are rarely needed
|
||||
|
||||
## Review Checklist
|
||||
|
||||
After drafting, verify:
|
||||
|
||||
- [ ] Description includes triggers ("Use when...")
|
||||
- [ ] SKILL.md under 100 lines
|
||||
- [ ] No time-sensitive info
|
||||
- [ ] Consistent terminology
|
||||
- [ ] Concrete examples included
|
||||
- [ ] References one level deep
|
||||
Loading…
Add table
Add a link
Reference in a new issue