Skip to content

AGENTS.md

Latest commit

 

History

History
123 lines (89 loc) · 5.21 KB

AGENTS.md

File metadata and controls

123 lines (89 loc) · 5.21 KB
Raw

Ponylang Website

MkDocs-based website for the Pony programming language.

Contributing with an AI assistant

This is a Pony project. The ponylang org maintains a set of LLM coding skills. Get set up with them before contributing:

  • Not set up yet? Install them once:

    git clone https://github.com/ponylang/llm-skills.git
cd llm-skills
python install.py

  • Already set up? Make sure you're on the latest. If you installed with the script above, git pull in the directory where you cloned llm-skills and the symlinked skills update automatically — if you set them up another way, refresh them however that setup expects.

See the llm-skills README for details and other harnesses.

When you start working on this project, load the pony-skills skill — it tells your assistant which Pony skill to use for each task.

Read CONTRIBUTING.md.

Prose model

If you are running on an Anthropic model, use claude-opus-4-6 for writing comments, documentation, and other prose. Prose quality from Anthropic models dropped starting with Opus 4.7 and has gotten worse with each subsequent release.

llms.txt

The llmstxt MkDocs plugin (configured in mkdocs.yml) auto-generates llms.txt and llms-full.txt during build. When making changes to docs content or nav structure, verify that the llms.txt output is updated accordingly.

The Contribute, Community, and Blog sections are intentionally excluded from llmstxt. They're operational and community content that would drown out the language-focused material (Learn, Use, FAQ, Discover) that LLMs actually need.

External PDFs

All external, non-Pony PDFs linked from the site must be stored locally in docs/media/other-papers/ with a meaningful name (e.g., champ-steindorfer-vinju-2015.pdf, not oopsla15.pdf). Link to the local copy instead of the external URL to avoid broken links.

Internal Links

When linking to other pages within this site, use relative markdown paths with .md extensions (e.g., ../use/debugging/pony-lldb-cheat-sheet.md), not URL-style paths (e.g., /use/debugging/pony-lldb-cheat-sheet/).

Last Week in Pony

Editorial Guidelines

The tone is informal and Hemingway-esque. Short sentences. Minimal adjectives and adverbs except where they serve a conversational tone. The result should not sound clipped or like a series of notes — it should read like a person talking to you.

Study recent posts in docs/blog/posts/ for voice calibration before writing.

Domain-Specific Notes

  • "Office Hours" is the title of a meeting and is singular. "Office Hours was attended by..." not "Office Hours were attended by..."
  • The Pony Development Sync is sometimes called just "the sync" in casual context.
  • Refer to repositories as owner/repo (e.g., ponylang/msgpack, not msgpack) — no one owns a name. This applies everywhere: section headings, inline prose, not just the releases list. Link to the repo on first mention.
  • Em dashes (—) are fine but use them sparingly. Heavy use reads as AI-generated. Prefer a period, comma, colon, or parentheses when one works just as well. Never replace an em dash with double hyphens (--).
  • Technical terms (type names, function names, system calls, language keywords) go in backticks: HashMap, writev, None, not HashMap, writev, None.
  • The opening hook should unfurl naturally, not read as a bulleted list of topics.

Post Format

Filename: docs/blog/posts/last-week-in-pony-MMDDYY.md

Front matter:

---
draft: false
authors:
  - seantallen
categories:
  - "Last Week in Pony"
title: "Last Week in Pony - Month Day, Year"
date: YYYY-MM-DDTHH:MM:SS-04:00
---

Structure (in order):

  1. Opening hook — 1-2 sentences, conversational, teasing what's in the post
  2. <!-- more --> marker
  3. ## sections for highlighted items only (see the lwip skill for what qualifies — most items do not)
  4. ## Items of Note with ### subsections — the default home for most content (community items, routine releases, Office Hours, Pony Development Sync, etc.)
  5. ## Releases — bullet list of all releases with links, format: - [org/repo version](release-url)
  6. --- separator
  7. Footer boilerplate (always the same):
_Last Week In Pony_ is a weekly blog post to catch you up on the latest news for the Pony programming language. To learn more about Pony, check out [our website](https://ponylang.io) or our [Zulip community](https://ponylang.zulipchat.com).

Got something you think should be featured? There's a GitHub issue for that! Add a comment to the [open "Last Week in Pony" issue](https://github.com/ponylang/ponylang-website/issues?q=is%3Aissue+is%3Aopen+label%3Alast-week-in-pony).

Review

Review the draft with the ponylang-prose-review skill before opening the post PR (see .claude/README.md). It runs an ensemble of lens reviewers — house voice, agency, narrative, reader-orientation, tightness, content-honesty, plus a conditional accuracy lens — against these editorial guidelines and the craft rules, and returns findings to apply or raise. It replaces the single copy-editing pass this section used to describe.