Imported from edouard-claude/snip (SKILL.md). Install upstream with npx skills add edouard-claude/snip. Copyright stays with the author.

Creating snip Filters

You are an expert at writing declarative YAML filters for snip, a CLI proxy that reduces LLM token consumption by filtering shell output.

Filter File Location

• Built-in filters: filters/*.yaml (embedded in the binary at build time)
• User filters: ~/.config/snip/filters/*.yaml (override built-in filters by name)
• Per-project filters: configure additional directories via filters.dir array in ~/.config/snip/config.toml (e.g. dir = ["~/.config/snip/filters", "${env.PWD}/.snip"]). Later directories take priority.

Trust store: filters in any directory outside ~/.config/snip/ are ignored (with a stderr warning) until approved once with snip trust <dir>, which pins each file's SHA-256. Re-run snip trust after editing a trusted file.

Filter Structure

Every filter is a YAML file with this structure:

name: "tool-subcommand"          # Required. Unique identifier, used for registry lookup.
version: 1                       # Informational revision number of the filter (bump on behavior change).
description: "What this filter does"  # Human-readable purpose.

match:                           # Required. When to apply this filter.
  command: "tool"                # Required. The CLI tool name (e.g., "git", "go", "npm").
  subcommand: "sub"             # Optional. First non-flag argument (e.g., "test", "log").
                                # Also accepts a list: ["install", "add", "i"]; include ""
                                # in the list to match the bare command invocation too.
  exclude_flags: ["-v", "--json"]  # Optional. Skip filter if user passes any of these.
  require_flags: ["--all"]      # Optional. Only apply if user passes ALL of these.

inject:                          # Optional. Modify command args before execution.
  args: ["--json"]              # Arguments to append to the command.
  defaults:                     # Flag defaults, only added if flag not already present.
    "-n": "10"
  skip_if_present: ["--json"]   # Don't inject anything if any of these flags are present.

streams: ["stdout", "stderr"]    # Optional. Which streams to filter. Default: ["stdout"].
                                 # Use ["stderr"] for tools that output to stderr (e.g., bun test).
                                 # Use ["stdout", "stderr"] to filter both streams merged together.

pipeline:                        # Required. Ordered list of transformation actions.
  - action: "keep_lines"
    pattern: "\\S"
  - action: "head"
    n: 20

on_error: "passthrough"          # Descriptive convention: the engine ALWAYS falls back to raw
                                 # output when a pipeline fails; no other value is implemented.

Match Rules

• command is matched exactly against the first token of the shell command.
• subcommand is matched against the first non-flag argument.
• Flag matching uses prefix matching: "-v" matches both -v and -verbose.
• Registry lookup is O(1) by key "command" or "command:subcommand".

Inject Behavior

• Injected args are inserted before any -- separator, otherwise appended.
• defaults only apply if their flag key is not already present in the user's args.
• If any flag in skip_if_present is found, the entire inject block is skipped.

The 20 Pipeline Actions

Line Filtering

Line Transformation

Extraction & Grouping

JSON Processing

Formatting & Conditionals

Template Data for format_template

The template receives:

• {{.lines}} - all current lines joined with newlines
• {{.count}} - number of lines
• {{.groups}} - map from group_by action (if used earlier in pipeline)
• {{.stats}} - map from aggregate action (if used earlier in pipeline)

{{.count}} trap: it counts the lines reaching the template, not entities. After any stage that emits a summary, an overflow marker or a cap, the number is wrong (caused bug #125). Prefer the tool's own count over recomputing one.

Metadata Flow Between Actions

• group_by sets metadata "groups" (map[string]int)
• aggregate sets metadata "stats" (map[string]int)
• format_template can access both via {{.groups}} and {{.stats}}
• All other actions pass metadata through unchanged

Design Principles

1. Start with keep_lines pattern "\\S" to strip blank lines early.
2. Use inject to request machine-readable output (e.g., --json, --porcelain) then filter that structured data.
3. Respect user intent: use exclude_flags to skip filtering when the user explicitly requests a different format.
4. Keep the conventional on_error: "passthrough" line: it documents the engine's actual fallback behavior (raw output on any pipeline failure).
5. Chain actions from broad to specific: filter noise first, then extract, then format.
6. Keep output minimal but useful: the goal is 60-90% token reduction while preserving actionable information.

Examples

Simple: remove noise lines

name: "npm-install"
version: 1
description: "Condensed npm install output"
match:
  command: "npm"
  subcommand: "install"
pipeline:
  - action: "remove_lines"
    pattern: "^(npm warn|npm notice)"
  - action: "keep_lines"
    pattern: "\\S"
  - action: "aggregate"
    patterns:
      added: "^added "
      removed: "^removed "
      up_to_date: "up to date"
    format: "{{if gt .up_to_date 0}}up to date{{else}}{{.added}} added, {{.removed}} removed{{end}}"
on_error: "passthrough"

Intermediate: inject flags + extract structured data

name: "go-test"
version: 1
description: "Condensed go test output with pass/fail summary"
match:
  command: "go"
  subcommand: "test"
  exclude_flags: ["-json", "-v", "-bench", "-run"]
inject:
  args: ["-json"]
  skip_if_present: ["-json", "-v", "-bench"]
pipeline:
  - action: "keep_lines"
    pattern: "\\S"
  - action: "keep_lines"
    pattern: "\"Test\":\""
  - action: "keep_lines"
    pattern: "\"Action\":\"(pass|fail)\""
  - action: "aggregate"
    patterns:
      passed: '"Action":"pass"'
      failed: '"Action":"fail"'
    format: "{{if and (eq .passed 0) (eq .failed 0)}}No tests found{{else}}{{.passed}} passed, {{.failed}} failed{{end}}"
on_error: "passthrough"

Advanced: state machine for multi-section output

name: "cargo-test"
version: 2
description: "cargo test summary lines, plus the failure report when a test fails"
match:
  command: "cargo"
  subcommand: "test"
pipeline:
  - action: "remove_lines"
    pattern: "^\\s*(Compiling|Downloading|Downloaded|Updating|Running|Executable)"
  - action: "keep_lines"
    pattern: "\\S"
  - action: "state_machine"
    states:
      start:
        keep: "^test result"
        until: "^failures"
        next: "failures"
      failures:
        keep: "."
  - action: "head"
    n: 150
  - action: "format_template"
    template: "{{.lines}}"
on_error: "passthrough"

The until on start is what makes this safe. Everything after the first failures: line is the failure report, and a panic message can hold any text at all — including a line that looks exactly like a test result. So every stage that drops or counts lines has to sit on the start side of that boundary, which keep does. A remove_lines placed after the state machine would instead run over the panic messages and delete them.

Workflow to Create a New Filter

1. Identify the command and its typical verbose output.
2. Run the command and capture raw output to understand the structure.
3. Decide what to keep: what information does the LLM actually need?
4. Check if the tool has a machine-readable flag (--json, --porcelain, etc.) that would make filtering easier -- use inject if so.
5. Write the pipeline: strip blanks, filter/extract, aggregate, format.
6. Test the filter by placing it in ~/.config/snip/filters/ and running the command through snip.
7. To contribute: add the YAML to filters/ in the repo and submit a PR.