Macros

Macros — Mechanical Solution Registry

Search, browse, and contribute reusable mechanical solutions — shell snippets, Python one-liners, patterns. Macros are reference material: read them, adapt them, don't execute blindly.

Setup

MACROS=~/.claude/skills/macros/scripts/macros.sh

Lookup Mode

Search

bash "$MACROS" search <query>
bash "$MACROS" search --tag <tag>

Returns matching macros as JSON, ranked by relevance (name > description > tags). Present the results to the user showing name, description, tags, and the snippet.

List

bash "$MACROS" list [--tag <tag>] [--tier built-in|user|project] [--json]

Show

bash "$MACROS" show <name>

Returns the full macro entry including snippet and examples.

Using a macro

Macros are reference, not black-box invocations. When you find a macro:

1. Read its snippet, input, and output fields
2. Adapt it to the current context — adjust paths, flags, piping
3. Run the adapted version via Bash

Do NOT copy-paste snippets blindly. They are templates.

Contribution Mode

When to contribute

After solving a mechanical problem that is:

• Reusable — not specific to one project or one-time task
• Snippet-scale — under ~50 lines. Larger solutions belong in claude-lib.
• Self-contained — has a shebang, takes clear input, produces clear output

How to contribute

1. Draft the macro entry with all required fields:

{
  "name": "slug-name",
  "description": "What it does (1-2 sentences)",
  "snippet": "#!/usr/bin/env bash\n...",
  "input": "What goes in (stdin, args, files)",
  "output": "What comes out (stdout format, side effects)",
  "tags": ["keyword1", "keyword2", "keyword3"],
  "examples": [
    {"use": "Concrete use case", "invocation": "how to call it"}
  ]
}

2. Present the entry to the user for review. Show it formatted:

Proposed macro: slug-name

  Description: What it does
  Tags: keyword1, keyword2, keyword3
  Input: What goes in
  Output: What comes out

  Snippet:
    #!/usr/bin/env bash
    ...

  Example: Concrete use case
    how to call it

Save to user tier? (or: project tier, edit, discard)

3. Wait for user confirmation. Agents cannot save without approval.

4. Once confirmed, write the JSON to a temp file and save:

bash "$MACROS" add <name> --tier <user|project> --from-json /tmp/macro-entry.json

Validation rules

• Snippet must start with a shebang (#!/usr/bin/env bash, #!/usr/bin/env python3, etc.)
• All required fields must be present: name, description, snippet, input, output, tags
• Name must be unique within its tier
• Tags should reuse existing tags where possible (check list first)

Error Recovery