Skip to content

ByteTerrace/Puck / .claude/skills/content-search

content-search

Verified

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.

FileKindSize
SKILL.mdskill md4.4 KB
evals/t01-literal-verb-uncapped/graders/checkout-cli.mdmarkdown177 B
evals/t01-literal-verb-uncapped/graders/files-only-flag.mdmarkdown94 B
evals/t01-literal-verb-uncapped/graders/fixed-string-flag.mdmarkdown207 B
evals/t01-literal-verb-uncapped/graders/search-verb.mdmarkdown117 B
evals/t01-literal-verb-uncapped/graders/skill-fired.mdmarkdown36 B
evals/t01-literal-verb-uncapped/graders/uncapped-flag.mdmarkdown96 B
evals/t01-literal-verb-uncapped/prompt.mdmarkdown373 B
evals/t02-references-route-to-symbol-analysis/graders/semantic-verbs.mdmarkdown106 B
evals/t02-references-route-to-symbol-analysis/graders/skill-fired.mdmarkdown36 B
evals/t02-references-route-to-symbol-analysis/graders/text-is-not-evidence.mdmarkdown916 B
evals/t02-references-route-to-symbol-analysis/prompt.mdmarkdown338 B
evals/t03-fallback-when-puck-cannot-run/graders/discloses-host-fallback.mdmarkdown834 B
evals/t03-fallback-when-puck-cannot-run/graders/skill-fired.mdmarkdown36 B
evals/t03-fallback-when-puck-cannot-run/graders/verifies-the-negative-condition.mdmarkdown673 B
evals/t03-fallback-when-puck-cannot-run/prompt.mdmarkdown515 B
evals/t04-glob-brace-and-doublestar/graders/covers-both-trees-at-every-depth.mdmarkdown1.1 KB
evals/t04-glob-brace-and-doublestar/graders/no-brace-set.mdmarkdown432 B
evals/t04-glob-brace-and-doublestar/graders/search-verb.mdmarkdown117 B
evals/t04-glob-brace-and-doublestar/graders/separate-extension-globs.mdmarkdown195 B
evals/t04-glob-brace-and-doublestar/graders/skill-fired.mdmarkdown36 B
evals/t04-glob-brace-and-doublestar/graders/uncapped-flag.mdmarkdown96 B
evals/t04-glob-brace-and-doublestar/prompt.mdmarkdown340 B
evals/t05-contains-a-but-not-b/graders/excludes-refusal-correctly.mdmarkdown773 B
evals/t05-contains-a-but-not-b/graders/ignore-case-flag.mdmarkdown87 B
evals/t05-contains-a-but-not-b/graders/search-verb.mdmarkdown117 B
evals/t05-contains-a-but-not-b/graders/skill-fired.mdmarkdown36 B
evals/t05-contains-a-but-not-b/prompt.mdmarkdown329 B
evals/t06-flag-text-as-pattern/graders/dash-pattern-guarded.mdmarkdown140 B
evals/t06-flag-text-as-pattern/graders/explains-the-dash-rule.mdmarkdown661 B
evals/t06-flag-text-as-pattern/graders/search-verb.mdmarkdown117 B
evals/t06-flag-text-as-pattern/graders/skill-fired.mdmarkdown36 B
evals/t06-flag-text-as-pattern/graders/uncapped-flag.mdmarkdown96 B
evals/t06-flag-text-as-pattern/prompt.mdmarkdown418 B
evals/t07-cartridge-source-and-compile/graders/compiles-fresh-into-scratch.mdmarkdown901 B
evals/t07-cartridge-source-and-compile/graders/empty-source-search-is-not-absence.mdmarkdown769 B
evals/t07-cartridge-source-and-compile/graders/reads-the-exit-code.mdmarkdown657 B
evals/t07-cartridge-source-and-compile/graders/search-verb.mdmarkdown117 B
evals/t07-cartridge-source-and-compile/graders/searches-the-authored-sources.mdmarkdown696 B
evals/t07-cartridge-source-and-compile/graders/skill-fired.mdmarkdown36 B
evals/t07-cartridge-source-and-compile/prompt.mdmarkdown621 B
references/complete-reference.mdmarkdown25.3 KB
---
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` |
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: 198kUpdated Claude CodeCodexVerifiedInstall
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: 194kUpdated Claude CodeCodexVerifiedInstall
ponytail-debtDietrichGebert/ponytailHarvest every shortcut: comment into one debt ledger, so deferrals get tracked instead of forgotten. One-shot report.Stars: 194kUpdated Claude CodeCodexVerifiedInstall
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: 194kUpdated Claude CodeCodexVerifiedInstall