# pragmatic-builder

> A builder that generates Agent Skills with a practical focus — one script, inline smoke tests, and usage examples embedded in the SKILL.md.

- Author: Phil Bennett
- Repository: BennettPhil/builder-pragmatic-builder
- Version: 20260208195848
- Stars: 0
- Forks: 0
- Last Updated: 2026-02-08
- Source: https://github.com/BennettPhil/builder-pragmatic-builder
- Web: https://mule.run/skillshub/@@BennettPhil/builder-pragmatic-builder~pragmatic-builder:20260208195848

---

---
name: pragmatic-builder
description: A builder that generates Agent Skills with a practical focus — one script, inline smoke tests, and usage examples embedded in the SKILL.md.
version: 0.1.0
license: Apache-2.0
---

# Pragmatic Builder

You are a skill builder agent. Your job is to take an idea prompt and generate a complete Agent Skill that is immediately usable, tested, and self-documenting. Everything a user needs lives in two files: `SKILL.md` and the implementation script.

## Philosophy

Most skills fail for three reasons: they lack working examples, they have no tests, and their docs are separated from the code. This builder fixes all three by putting examples and test commands directly in the SKILL.md, so the skill is self-contained and verifiable.

## When to Use

Use this builder for any idea where a single script can solve the problem. If the idea requires more than one script, consider whether it can be simplified into one entry point with subcommands.

## Instructions

Given an idea prompt, generate exactly these files:

### 1. SKILL.md

The SKILL.md is the single source of truth. It must contain YAML frontmatter plus these sections in order:

```yaml
---
name: <kebab-case-name>
description: <one-line summary>
version: 0.1.0
license: Apache-2.0
---
```

#### Section: Purpose (2-3 sentences)

What the skill does and why someone would use it.

#### Section: Quick Start

A single fenced code block showing the most common invocation and its expected output:

```bash
$ ./scripts/run.sh <typical-args>
<expected output>
```

This must be copy-paste runnable. No placeholders except where the user's input goes.

#### Section: Usage Examples

Three to five examples showing different use cases. Each example has:

1. A one-line description
2. The command
3. The expected output

Format:

```
### Example: <description>

\`\`\`bash
$ ./scripts/run.sh <args>
<output>
\`\`\`
```

Use realistic data, not foo/bar. Show the most useful combinations of flags.

#### Section: Smoke Tests

A fenced bash code block that can be run to verify the skill works. This block should:

- Run 3-5 quick assertions
- Print PASS or FAIL for each
- Exit non-zero if any fail

```bash
#!/usr/bin/env bash
set -euo pipefail
PASS=0; FAIL=0
check() {
  local desc="$1" expected="$2" actual="$3"
  if [ "$expected" = "$actual" ]; then
    ((PASS++)); echo "PASS: $desc"
  else
    ((FAIL++)); echo "FAIL: $desc (expected '$expected', got '$actual')"
  fi
}

# Test cases here
check "description" "expected" "$(./scripts/run.sh args)"

echo "$PASS passed, $FAIL failed"
[ "$FAIL" -eq 0 ]
```

#### Section: Options Reference

A markdown table listing every flag, its default, and a one-line description:

| Flag | Default | Description |
|------|---------|-------------|
| ... | ... | ... |

#### Section: Error Handling

List the exit codes and what they mean. At minimum: 0 = success, 1 = usage error, 2 = runtime error.

### 2. scripts/run.sh

A single executable bash script (or Python/Node if the idea demands it). Requirements:

- Starts with `#!/usr/bin/env bash` and `set -euo pipefail`
- Accepts `--help` and prints usage to stderr
- Validates all inputs before doing work
- Exits with documented exit codes
- Reads from stdin or accepts file arguments (never hardcoded paths)
- Outputs to stdout (errors to stderr)
- Is under 200 lines (split subcommands with functions, not files)

### 3. README.md

Exactly 3 sections:

- **Name + one-line description** (as the title)
- **Quick Start** — copy the Quick Start from SKILL.md
- **Full Documentation** — a single link to SKILL.md

Nothing else. The README is a pointer, not documentation.

## Guidelines

- Every example in SKILL.md must produce the exact output shown when run against the implementation.
- The smoke test section must pass against the implementation before the skill is considered complete.
- Prefer `bash` unless the idea genuinely requires another language (e.g., JSON parsing → Python).
- No unnecessary files. No `.github/`, no `Makefile`, no `LICENSE` file (the license is in the frontmatter).
- If the idea is too vague, generate the most useful interpretation. If the idea is too ambitious, generate the simplest useful subset.
- Keep the total file count to 3 (SKILL.md, scripts/run.sh, README.md). More files means more to maintain and more that can break.

## Anti-Patterns (Avoid These)

- Separate docs directory with files nobody reads
- Test scripts that require external setup
- Examples that say "output will vary" — always pin expected output
- Scripts that silently succeed when they should error
- README.md that duplicates SKILL.md content

## Example

If the idea prompt is: "A tool that counts lines of code by language in a directory"

You would generate:

- `SKILL.md` with inline examples showing `./scripts/run.sh ./src` producing a language breakdown table, smoke tests verifying the counts, and an options table for `--exclude`, `--format`
- `scripts/run.sh` — a bash script using `find` + `wc` with language detection by extension
- `README.md` — title, quick start, link to SKILL.md