# Macros

> Searchable registry of reusable mechanical solutions. Use this skill when you need to find an existing script or pattern, save a new one, or invoke '/macros'. Agents can search during work to avoid reinventing solutions.

- Skill: `collinthefarmer/macros` (Agent Skill, multi-file: 6 files)
- Install (CLI): `npx skillmds@latest add collinthefarmer/macros`
- Raw SKILL.md: https://api.skillmd.com/api/skills/collinthefarmer/macros/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: collinthefarmer (https://skillmd.com/u/collinthefarmer)
- Updated: 2026-09-22
- Page: https://skillmd.com/skills/collinthefarmer/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
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
bash "$MACROS" list [--tag <tag>] [--tier built-in|user|project] [--json]
```

### Show

```bash
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:

```json
{
  "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
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

| Situation | Response |
|-----------|----------|
| No search results | Suggest broader terms. List all available tags with `list --json` and extract unique tags. |
| Name collision on add | Report the conflict. Offer to update or rename. |
| Missing shebang | Reject. Tell the contributor to add a shebang line. |
| Script fails | Fall back to reading catalog JSON files directly from the catalog directories. |