[felixarntz]

Background

Package README.md files should be minimal starting points. Detailed documentation already lives in content/; duplicating it in READMEs risks drift.

Summary

• Standardize READMEs around a title, brief description, install command, one usage example, and documentation links.
• Preserve existing descriptions, selected examples, relevant callouts, and coding-agent skill sections; add docs-sourced examples where missing.
• Add an edit-package-readme skill to capture the conventions.
• Explicit format exceptions:
  • ai (also the repository README)
  • codemod (internal tooling)
  • provider, and provider-utils (internal foundations)

Checklist

• All commits are signed (PRs with unsigned commits cannot be merged)
• Tests have been added / updated (for bug fixes / features)
• Documentation has been added / updated (for bug fixes / features)
• A patch changeset for relevant packages has been added (for bug fixes / features - run pnpm changeset in the project root)
• I have reviewed this pull request (self-review)

Future Work

Update the angular README once a suitable documentation page exists. It remains untouched for now, but is not a format exception.

[roboeve]

This rule contradicts the READMEs this PR produces. 45 of them keep a ## Skill for Coding Agents section between Setup and Usage (e.g. packages/anthropic/README.md:13, packages/openai/README.md:14, packages/gateway/README.md:11), and the PR description says keeping it is intentional. An agent following this skill literally will delete that section on the next edit, and new provider READMEs will leave it out.

Can we add it to the ordered list as an optional item between Setup and Usage, with the exact block, and say which packages get it (provider packages)?

Related: skills/add-provider-package/SKILL.md:164 still says to write the README with "installation, authentication, configuration, supported models, and basic usage", which this format now forbids. Pointing it at edit-package-readme would keep the two skills from pulling in opposite directions.