ByteTerrace/Puck / .claude/skills/content-search
content-search
VerifiedSearches Puck repo text with puck search, not grep or rg: files or lines mentioning a verb, flag or key, regex, contains-A-not-B, counts, uncapped file lists. C# usages go to symbol-analysis.
SKILL.md
View on GitHub---
name: content-search
description: "Searches Puck repo text with puck search, not grep or rg: files or lines mentioning a verb, flag or key, regex, contains-A-not-B, counts, uncapped file lists. C# usages go to symbol-analysis."
---
# Content search
`puck search` is the repository's content search: a ripgrep-shaped verb over a
linear-time, leftmost-longest regex engine with intersection, complement and
lookaround. Use it in place of Grep, `rg` and `grep` for anything inside the
checkout. Reach for the Glob tool only when the question is purely about path
names: `--files` answers that inside the verb, over the same walk a search
uses. Use `symbol-analysis` when the question is semantic rather than textual.
## Start the CLI from a clean checkout
Run from the repository root with the checkout's own CLI build, never a
published copy or the global `puck` tool, both of which lag the head. Copy
`src/Puck.Cli/bin/Release/net11.0/` to a scratch directory named for your lane
and run the copy, so the running tool never locks the build output another
build needs:
```text
dotnet <lane>-cli/Puck.Cli.dll search <pattern> [path] [options]
```
If that build is absent, build it (`dotnet build src/Puck.Cli -c Release
-nodeReuse:false`) and copy it
([verification](../verification/SKILL.md#run-verbs-from-your-own-cli-copy)); `dotnet
run` on the project runs the build in place and locks its output, so it is not a
substitute for the copy.
If the copy cannot run, fall back to the host's literal or regex search.
Say in the result that it came from a degraded fallback, keep the requested
path, glob and case semantics, and never claim Puck-only intersection,
complement or lookaround behavior for it. A "contains A but not B" condition
still has to be checked: use a second filter or per-line inspection with the
host tool.
## Rules that prevent wrong answers
- Search paths are repository-relative unless the task says otherwise.
- Positional roots must exist and are literal paths, never wildcard paths. Discover
an uncertain filename with `--files`, or search an existing directory with `-g`;
`src/Puck.World*` is not a family of search roots.
- Use `-F` for literal text; otherwise the pattern is the Puck regex dialect.
- Add `-M 0` when all results are required; the default result cap is 250 and
only a stderr line reports a truncation. `-l` lists files, `-c` counts matching lines per file,
and `-s` matches across whole-file text and prints line ranges.
- Matching is case-sensitive by default. `-i` fixes the pattern and never the
globs, and a stray case mismatch is the most common empty result.
- Globs are not ripgrep's. Brace sets and character classes are literal
characters, and `**` requires an intermediate directory, so `src/Puck.Cli/**/*.cs`
silently misses `src/Puck.Cli/Program.cs`. Write `-g "*.cs"` for an extension and
`-g "src/**"` for a subtree, repeating `-g` instead of writing `{cs,md}`.
- A pattern that starts with `-` needs `--` before it, or it is parsed as a
flag.
- Treat exit `0` as a match, `1` as no match, and `2` as an error. When a result
surprises you, `--files` prints exactly which files the run would read.
- Text occurrences do not prove C# references, implementers, overrides, rename
safety or deletion safety. Route those questions to `symbol-analysis`, whose
verbs are `puck references` and `puck declarations`.
- Quote patterns for the active shell; do not silently rewrite regex syntax.
- The walk reads `.puck` DSL sources by default. The owner's ruling removes
committed cartridge JSON twins: search the authored source and its imported
modules. If the question concerns lowered defaults or expanded values, compile
into a lane scratch directory and inspect that fresh output explicitly; ignored
generated output is outside the default walk. An empty source search cannot
establish that a generated value is absent.
## Load the full reference selectively
Read [references/complete-reference.md](references/complete-reference.md) when
you need exact flags, walk and glob behavior, engine semantics, syntax
extensions, cookbook patterns (contains A but not B, files without a pattern,
multiline blocks, whole-word alternations), shell escaping, or known
limitations.
## Related skills
| Question | Skill |
|---|---|
| Who references, implements, overrides or can delete a C# symbol (`puck references`, `puck declarations`) | `symbol-analysis` |
| `.puck` name resolution and diagnostics | `puck-dsl` |
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| slack-gif-creatoranthropics/skillsKnowledge and utilities for creating animated GIFs optimized for Slack. Provides constraints, validation tools, and animation concepts. Use when users request animated GIFs for Slack like "make me a GIF of X doing Y for Slack." | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| ponytailDietrichGebert/ponytailLazy senior dev mode for any coding task: the smallest change that fully solves it, and a reply a busy human understands in one read. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-debtDietrichGebert/ponytailHarvest every shortcut: comment into one debt ledger, so deferrals get tracked instead of forgotten. One-shot report. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-debtDietrichGebert/ponytailList every `shortcut:` comment (and older `ponytail:` ones) as a debt ledger. One-shot report, changes nothing. Use for "ponytail debt", "what did ponytail defer", "list the shortcuts", /ponytail-debt. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |