# Pony Library Readme

> Conventions for Pony library project READMEs. Load when writing or updating a README.md for a ponylang library project.

- Skill: `ponylang/pony-library-readme` (Agent Skill)
- Install (CLI): `npx skillmds@latest add ponylang/pony-library-readme`
- Raw SKILL.md: https://api.skillmd.com/api/skills/ponylang/pony-library-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-library-readme

---


# Pony Library README Conventions

These conventions are derived from existing ponylang library READMEs and should be followed when writing or updating a README.md for a Pony library project.

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

## Required Sections (in order)

Every Pony library README has these sections in this order:

1. **Title** (`#`) — Lowercase matching the repo/package name (e.g., `# glob`, `# web_link`). Use proper capitalization only for proper nouns or acronyms (e.g., `# PEG`, `# Lori`, `# GitHub REST API`).

2. **Intro paragraph** (no heading) — 1-2 sentences describing what the library does. No section heading.

3. **`## Status`** — Short maturity statement. Common values:
   - `Production ready.`
   - `Beta`
   - `[Name] is beta-level software.`
   - Longer form: `[Name] is beta quality software that will change frequently. Expect breaking changes. That said, you should feel comfortable using it in your projects.`

4. **`## Installation`** — Standard 5-bullet list using `*` markers:
   ```markdown
   * Install [corral](https://github.com/ponylang/corral)
   * `corral add github.com/ponylang/<name>.git --version <X.Y.Z>`
   * `corral fetch` to fetch your dependencies
   * `use "<package>"` to include this package
   * `corral run -- ponyc` to compile your application
   ```
   If the package has sub-packages, the `use` bullet gets sub-bullets listing each (e.g., `use "ssl/crypto"`, `use "ssl/net"`).

5. **`## API Documentation`** — A markdown link to the docs: `[https://ponylang.github.io/<name>](https://ponylang.github.io/<name>)`. This is always the last section (or near-last if a project-specific section follows).

## Optional Sections

These go between Installation and API Documentation, in this order:

- **`## Dependencies`** — Only include when the library requires native C libraries the user must install (e.g., libpcre2, OpenSSL). If the dependency is transitive via the `ssl` package, a note after the installation bullets linking to ssl's installation instructions is sufficient instead of a full section.

- **`## Usage`** — Always include an inline code example showing core usage (a complete short program or a structural skeleton). Point to the `examples/` directory for more.

## Things Pony Library READMEs Do NOT Have

- No CI/coverage/version badges
- No "Contributing" section (that goes in CONTRIBUTING.md)
- No "License" section (that goes in LICENSE)
- No "Table of Contents"