agentleFS
anza-xyzanza-xyz/kit/.agents/skills/ts-readme/SKILL.md

ts-readme

Skill703 starsChanged 9 months agoMITView on GitHub

Guidelines for writing developer-friendly READMEs for TypeScript libraries. Use when creating a new package, changing a public API, or updating documentation.

1 other project uses a version of this.

Adopted by

Most recently taken up by

  • Other versions1 project uses a version of this.

    Word for word · 1

    1. lorisleiva/skills★ 1100% same

    Edited · 0

    None found.

    Wrote their own version · 0

    None found.

    How matches are found. Word for word: the exact same text. Edited: shares passages with this file (“99% same” means 99% of its five-word phrases also appear here; 10% or more counts). Their own version: similar meaning, or, weakest, the same name. We can’t tell which project had it first. Projects are counted among the 200 most-starred candidates, and mentions are links to the repository we found, up to 50 per site, so both counts are a floor.

  • In this repository5 other files it gives its agents.

The file

Show its rules and text

We split this skill into the rules it gives an agent

25 rules. About 0 are common, 21 are distinctive, and 4 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈21

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 4

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Distinctive:

    Create a new README or update an existing one for a TypeScript package, library, or project.

    line 9
  2. Distinctive:

    When adding a new public API, add or update the package's README.

    line 13
  3. Distinctive:

    Do NOT update any real code outside of the README file itself.

    line 17
  4. Distinctive:

    Only update the intro if you can meaningfully improve the summary.

    line 32
  5. Distinctive:

    Keep it extremely concise (1-2 lines of explanation max if necessary).

    line 36
  6. Distinctive:

    Document key features, concepts, or use cases.

    line 51
  7. Distinctive:

    No need for a "Requirements" section for peer dependencies.

    line 60
  8. Distinctive:

    Use TypeScript syntax for TypeScript projects.

    line 64
  9. Very specific:

    Use descriptive variable names (not foo, bar).

    line 67
  10. Distinctive:

    Keep examples focused on one concept at a time when possible.

    line 68
  11. Distinctive:

    When working in a monorepo:

    line 91
  12. Distinctive:

    Consistency: When updating a package README, check other package READMEs for structural consistency (heading levels, section order, code …

    line 95
  13. Distinctive:

    When invoked as a command, follow these steps:

    line 99
  14. Very specific:

    If a path argument is provided and ends with .md, use it directly.

    line 108
  15. Very specific:

    If the argument is a directory path, use <path>/README.md.

    line 109
  16. Very specific:

    If no argument is provided, use ./README.md.

    line 110
  17. Distinctive:

    Check if the README exists:

    line 112
  18. Distinctive:

    If it exists, read it to understand the current structure.

    line 113
  19. Distinctive:

    If it doesn't exist, prepare to create one from scratch.

    line 114
  20. Distinctive:

    Look at the source code to understand what the library does.

    line 118
  21. Distinctive:

    Check for existing tests or examples that show usage.

    line 120
  22. Distinctive:

    If in a monorepo, examine other package READMEs to ensure consistency in style and structure.

    line 122
  23. Distinctive:

    Create or update the README:

    line 124
  24. Distinctive:

    Ensure the Usage section has a strong, clear example.

    line 128
  25. Distinctive:

    Add or improve deep dive sections as needed.

    line 129

≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

Create or Update README

Create a new README or update an existing one for a TypeScript package, library, or project.

Key Rules

  • When adding a new public API, add or update the package's README.
  • Structure: brief intro, installation, usage (with code snippet), deep-dive sections.
  • Code snippets must be realistic, concise, and use TypeScript syntax.
  • Focus on the quickest path to success. Developers should feel excited, not overwhelmed.
  • Do NOT update any real code outside of the README file itself. If you identify errors in the codebase, warn the user but do not fix them.

Guidelines

A deep understanding of the project is necessary to create an effective README. Analyze the codebase, key features, and typical usage patterns to inform the content. If the project relies on other libraries or frameworks, consider how those influence usage and installation.

Structure

The layout of a README will vary from project to project, but they should generally follow these guidelines.

1. Intro Section

  • Package/library name as the main heading.
  • Badges for tests, package version, downloads, etc. (npm, GitHub, etc.).
  • Very brief summary (ELI5) — A single sentence or short paragraph that anyone can understand at first glance.
  • Only update the intro if you can meaningfully improve the summary; otherwise leave it intact.

2. Installation Section

  • Keep it extremely concise (1-2 lines of explanation max if necessary).
  • Show the install command in a code block.

3. Usage Section (Most Critical)

  • This is where readers' attention lands first after the intro.
  • Show the quickest path to success with this library.
  • Must include a code snippet illustrating basic usage.
  • Balance between brevity and clarity to create an "aha moment."
  • Optional: Brief text before/after the snippet if it adds clarity.
  • The code snippet should be realistic, concise, and immediately understandable.

4. Deep Dive Sections

  • Structure varies case-by-case based on the project.
  • Document key features, concepts, or use cases.
  • Each section should include at least one code snippet. Similar guidelines as the Usage section, that is, realistic and concise (shortest path to "aha moment").
  • Organize logically (e.g. by feature, by use case, by complexity).
  • Common patterns:
    • Features: Individual feature documentation with examples.
    • API Reference: Core APIs or functions.
    • Advanced Usage: More complex scenarios.
    • Configuration: Setup and customization options.
    • Examples: Real-world use cases.
  • No need for a "Requirements" section for peer dependencies. Just mention them in the "Installation" section if necessary to get started.

Code Snippets

  • Use TypeScript syntax for TypeScript projects.
  • Show realistic but concise examples.
  • Include necessary imports when relevant (e.g. when importing from multiple modules).
  • Use descriptive variable names (not foo, bar).
  • Keep examples focused on one concept at a time when possible.
  • Format for readability (proper indentation, spacing).

Tone

  • Friendly and approachable.
  • Clear and direct.
  • Avoid marketing speak.
  • Focus on practical value.
  • Use active voice.
  • Assume the reader is a developer who wants to get started quickly.

What to Avoid

  • Overly long introductions or preambles.
  • Walls of text without code examples.
  • Complex examples in the Usage section.
  • Unexplained jargon or acronyms.
  • Marketing-heavy language.
  • Duplicating information unnecessarily.

Monorepo Considerations

When working in a monorepo:

  • Package READMEs: Focus on the specific package — its API, installation, usage, and features. Include an installation note pointing to an umbrella package as an alternative if one exists.
  • Root README: Provides an overview of the entire monorepo, links to individual package READMEs for details. Focus on the quick-start experience rather than deep-diving into each package.
  • Consistency: When updating a package README, check other package READMEs for structural consistency (heading levels, section order, code example style).

Command Process

When invoked as a command, follow these steps:

Arguments

  • [path] (optional): Path to the README file or its parent directory. Defaults to ./README.md.

Steps

  1. Determine the target README path:
    • If a path argument is provided and ends with .md, use it directly.
    • If the argument is a directory path, use <path>/README.md.
    • If no argument is provided, use ./README.md.
  2. Check if the README exists:
    • If it exists, read it to understand the current structure.
    • If it doesn't exist, prepare to create one from scratch.
  3. Analyze the project context:
    • Examine package.json (if exists) for package name, description, dependencies.
    • Look at the source code to understand what the library does.
    • Identify key exports, main functions, and typical usage patterns.
    • Check for existing tests or examples that show usage.
    • Research any related libraries or frameworks that influence usage.
    • If in a monorepo, examine other package READMEs to ensure consistency in style and structure.
  4. Create or update the README:
    • For existing READMEs: Identify missing sections or areas needing improvement.
    • For new READMEs: Build the full structure following the guidelines.
    • Preserve the intro unless improvements are clear.
    • Ensure the Usage section has a strong, clear example.
    • Add or improve deep dive sections as needed.
    • Include realistic code snippets throughout.
  5. Present the complete README for review before applying changes.

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.