# Pony Examples Readme

> Conventions for Pony examples/README.md files. Load when adding, updating, or reorganizing examples in a ponylang project.

- Skill: `ponylang/pony-examples-readme` (Agent Skill)
- Install (CLI): `npx skillmds@latest add ponylang/pony-examples-readme`
- Raw SKILL.md: https://api.skillmd.com/api/skills/ponylang/pony-examples-readme/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: ponylang (https://skillmd.com/u/ponylang)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/ponylang/pony-examples-readme

---


# Pony Examples README Conventions

These conventions are derived from existing ponylang examples/README.md files (postgres, redis, lori, crdt, uri, web_link). Follow them when writing or updating an examples/README.md.

Load `pony-prose` for how the prose reads. This skill says what an examples README holds; `pony-prose` says how to write it plainly.

## Structure

1. **Title** — Always `# Examples`.

2. **Intro paragraph** (no heading) — 1-3 sentences describing what the examples are and any useful context. Standard phrasing for library examples: "Each subdirectory is a self-contained Pony program demonstrating a different part of the X library." If examples are ordered by complexity or grouped by category, state that here.

3. **Example entries** — One `##` heading per example, using the directory name as the heading text. Optionally link to the directory: `## [example-name](example-name/)`.

4. **Category grouping** (when applicable) — If examples fall into natural categories, use `##` for category headings and `###` for individual examples within each category.

5. **Start-here marker** — When one example is clearly the simplest entry point, end its description with: "Start here if you're new to the library."

## Example Descriptions

Each example gets a paragraph of 2-4 sentences covering:

- **What it does**: The concrete workflow in present tense, third person ("Connects to Redis, executes SET, prints the response, and closes the session.")
- **What it demonstrates**: The specific APIs, interfaces, or patterns exercised, named with backtick formatting (e.g., "`Session.prepare()` and `NamedPreparedQuery`")
- **Key concepts**: Any non-obvious behavior, design pattern, or protocol detail the example illustrates

## Ordering

Choose one strategy and make it clear from the intro paragraph or the order itself:

- **By complexity** (simplest first) — Best when examples build on each other conceptually. State the ordering in the intro: "Ordered from simplest to most involved."
- **By category** — Best when examples cover distinct feature areas. Use `##` categories with `###` examples.
- **By directory name** — Acceptable when no natural ordering exists.

## What to Omit

- **Build instructions** — Build commands belong in the project's top-level README or Makefile. Exception: if examples have a separate build target (e.g., `make build-examples`), a one-line note in the intro is acceptable.
- **Source code snippets** — The README describes what each example does; the code speaks for itself.
- **Detailed setup instructions** — If an example needs external services (a database, Redis server, TLS certificates), mention it briefly in that example's description. Detailed setup belongs in the example's own directory.