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
- lorisleiva/skillsword for word, first seen Feb 27, 2026
Other versions1 project uses a version of this.
Word for word · 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.
- CLAUDE.mdCLAUDE.md
- changesetsSkill
- shipping-gitSkill
- shipping-graphiteSkill
- ts-docblocksSkill
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
- Distinctive: line 9
Create a new README or update an existing one for a TypeScript package, library, or project.
- Distinctive: line 13
When adding a new public API, add or update the package's README.
- Distinctive: line 17
Do NOT update any real code outside of the README file itself.
- Distinctive: line 32
Only update the intro if you can meaningfully improve the summary.
- Distinctive: line 36
Keep it extremely concise (1-2 lines of explanation max if necessary).
- Distinctive: line 51
Document key features, concepts, or use cases.
- Distinctive: line 60
No need for a "Requirements" section for peer dependencies.
- Distinctive: line 64
Use TypeScript syntax for TypeScript projects.
- Very specific: line 67
Use descriptive variable names (not foo, bar).
- Distinctive: line 68
Keep examples focused on one concept at a time when possible.
- Distinctive: line 91
When working in a monorepo:
- Distinctive: line 95
Consistency: When updating a package README, check other package READMEs for structural consistency (heading levels, section order, code …
- Distinctive: line 99
When invoked as a command, follow these steps:
- Very specific: line 108
If a path argument is provided and ends with .md, use it directly.
- Very specific: line 109
If the argument is a directory path, use <path>/README.md.
- Very specific: line 110
If no argument is provided, use ./README.md.
- Distinctive: line 112
Check if the README exists:
- Distinctive: line 113
If it exists, read it to understand the current structure.
- Distinctive: line 114
If it doesn't exist, prepare to create one from scratch.
- Distinctive: line 118
Look at the source code to understand what the library does.
- Distinctive: line 120
Check for existing tests or examples that show usage.
- Distinctive: line 122
If in a monorepo, examine other package READMEs to ensure consistency in style and structure.
- Distinctive: line 124
Create or update the README:
- Distinctive: line 128
Ensure the Usage section has a strong, clear example.
- Distinctive: line 129
Add or improve deep dive sections as needed.
≈ “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.
Files
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
- 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.
- If a path argument is provided and ends with
- 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.
- 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.
- Examine
- 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.
- Present the complete README for review before applying changes.
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
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.

