playbooks

home / skills / dropseed / plain / readme

readme skill

/.claude/skills/readme

This skill explains how to create and maintain package READMEs, ensuring clear structure and actionable guidance.

npx playbooks add skill dropseed/plain --skill readme

Review the files below or copy the command above to add this skill to your agents.

Files (1)
SKILL.md
1.8 KB
---
name: readme
description: Guidelines for writing and editing Plain package READMEs. Use this when creating or updating README files.
---

# README Guidelines

Each top-level package directory (e.g., `plain-api/`) has a `README.md` symlink pointing to the actual README inside the package (e.g., `plain-api/plain/api/README.md`). **Only edit the README inside the package itself.**

See [`plain-jobs/plain/jobs/README.md`](plain-jobs/plain/jobs/README.md) as a good example.

## Purpose

The README answers: "How do I use this?" It gets users productive quickly and points them to code for deeper exploration. It is not a complete API reference.

## Required Structure

Every README follows this order:

1. **h1** with package name
2. **Bold one-liner** describing the package
3. **Table of contents** with links to h2s and h3s
4. **Overview** section with basic working examples
5. **Feature sections** as needed
6. **FAQs** section (second to last) using h4s for questions
7. **Installation** section (always last)

## Style

- **Conversational tone**: "You can..." not "The module provides..."
- **First code example must be copy-paste ready** with imports included
- **Subsequent examples can be minimal**, building on what was shown
- **Link to source for advanced features**: `[ClassName](./file.py#ClassName)`
- **Cross-package references**: `[plain.auth](../../plain-auth/plain/auth/README.md)`

## What to Document

- **If users import it, document it**
- **Mention all public features**, even advanced ones briefly, then link to code
- **Internal APIs stay undocumented** (`_prefix` functions and `@internalcode`)
- **Don't fully document every parameter** - mention features exist, link to code

## Writing Tips

- Keep paragraphs short
- Put takeaways up front
- Use bullets and tables
- Bold important text
- Keep sentences simple and unambiguous

Overview

This skill provides concise guidelines for writing and editing Plain package README files. It explains where to edit, the required structure, tone, and what to document to make package READMEs useful and consistent. Use it to create copy-paste ready examples and clear navigation to source code. The goal is fast user onboarding, not exhaustive API reference.

How this skill works

The skill inspects a package README and checks it against the required structure: H1, bold one-liner, table of contents, overview with working examples, feature sections, FAQs, and installation last. It enforces conversational tone, first example copy-paste readiness with imports, and links to source for advanced details. It also guides what to include (public features) and what to omit (internal APIs).

When to use it

  • Creating a new package README inside the package directory
  • Updating an existing package README to match project conventions
  • Adding examples or feature summaries for users
  • Linking to source code for advanced features
  • Preparing documentation for release or handoff

Best practices

  • Edit the README file inside the package itself (not top-level symlinks).
  • Start with H1 then a bold one-liner that explains package purpose at a glance.
  • Include a table of contents linking to H2/H3 headings for quick navigation.
  • Make the first code example fully copy-paste ready, including imports and minimal setup.
  • Document every public importable feature briefly, then link to source for details.
  • Keep tone conversational, paragraphs short, and put takeaways up front.

Example use cases

  • Add a compact overview with a working example that demonstrates the common happy path.
  • Create feature sections that list capabilities with links to implementation files for advanced options.
  • Add an FAQ section using h4 questions to address common pitfalls and configuration notes.
  • Append an Installation section describing package install and runtime prerequisites.
  • Cross-link related package READMEs for integrated workflows (e.g., auth, jobs).

FAQ

Where exactly should I edit the README?

Edit the README inside the package directory (the real README), not the top-level symlink. This keeps the authoritative file with the code.

How detailed should examples be?

The first example must be copy-paste ready with imports; later examples can be minimal and build on the first. Link to source for parameter-level detail.