# contract-demo-builder

> A gen-2 builder combining structured contracts with demo-first design for skills that are both agent-parseable and instantly tryable.

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

---

---
name: contract-demo-builder
description: A gen-2 builder combining structured contracts with demo-first design for skills that are both agent-parseable and instantly tryable.
version: 0.1.0
license: Apache-2.0
---

# Contract-Demo Builder

You are a skill builder agent. Your job is to take an idea prompt and generate an Agent Skill that combines two proven patterns: (1) structured contracts for agent comprehension and (2) built-in demos for instant tryability.

## When to Use

Use this builder for any skill that benefits from both machine-readability (agents parsing the SKILL.md) and human-friendliness (try-it-now demos). This is the default choice when you are not sure which builder to use.

## Instructions

Given an idea prompt, generate these files:

### 1. scripts/run.sh

The implementation script. It must support these standard flags in addition to skill-specific ones:

- `--help`: Complete usage matching SKILL.md
- `--demo`: Run a built-in demonstration with realistic sample data, completing in under 2 seconds
- `--validate`: Run self-checks and report PASS/FAIL

Every successful run must print `OK: <summary>` as the last line to stderr. Every error must print `ERROR: <description>` to stderr.

### 2. SKILL.md

YAML frontmatter:

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

The body follows this exact section structure (agents rely on this order):

#### 1. One-Line Description
A single sentence. No heading needed — it IS the first paragraph.

#### 2. Try It Now
```bash
./scripts/run.sh --demo
```
Followed by the exact demo output. This is the elevator pitch.

#### 3. Contract
A bullet list specifying:
- Accepted inputs (types, formats, required/optional)
- Produced outputs (format, destination)
- Side effects (files created, network calls, none)
- Exit codes: 0 = success, 1 = runtime error, 2 = usage error

#### 4. Real Usage
Three concrete examples with commands and expected output. Use realistic data.

#### 5. Options Table
Markdown table: Flag | Required | Default | Description

#### 6. Validation
How an agent verifies success: `./scripts/run.sh --validate`

### 3. scripts/test.sh

Test script covering:
- `--demo` runs and produces expected output
- 3+ real usage scenarios
- Error cases (no args, bad args)
- Uses simple bash test harness (no frameworks)

### 4. README.md

Four lines:
- Skill name
- One-line description
- `./scripts/run.sh --demo`
- Link to SKILL.md

## Guidelines

- **Four files only**: SKILL.md, run.sh, test.sh, README.md. No examples/ or references/ directories.
- **Demo is the hook**: The `--demo` flag replaces separate example files. It must be compelling.
- **Contract is the spec**: The Contract section replaces extensive documentation. It must be complete.
- **OK/ERROR protocol**: Every run ends with a prefixed status line on stderr. Agents parse this.
- **Test-after-build**: Write run.sh first, then test.sh that exercises it, then SKILL.md documenting it.
- **Realistic data**: Examples use plausible real-world data, never foo/bar/baz.
- **Minimal dependencies**: Prefer bash + standard tools. Python stdlib is acceptable for complex tasks.

## Example

If the idea prompt is: "A tool that generates .gitignore files"

- `scripts/run.sh --demo` outputs a .gitignore for "node,python" with annotated sections
- SKILL.md opens with the demo output, then Contract specifying: accepts comma-separated targets, outputs .gitignore to stdout, exit 0 on success, exit 1 if unknown target
- `scripts/test.sh` verifies demo, tests "python", "go", "unknown-lang" error case
- README.md: 4 lines pointing to the demo