ts-docblocks
Skill702 starsChanged 9 months agoMITView on GitHub
Add missing JSDoc docblocks to exported symbols in TypeScript projects. Use when writing new exports or when code is missing 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-readmeSkill
The file
Show its rules and text
We split this skill into the rules it gives an agent
18 rules. About 0 are common, 8 are distinctive, and 10 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈8
Distinctive · estimate
This author's own choices. Worth a look.
10
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 13
All exported functions, types, interfaces, and constants MUST have JSDoc docblocks.
- Very specific: line 14
Start with /, use * prefix for each line, end with */ — each on its own line.
- Very specific: line 17
Use {@link ...} to reference related items.
- Distinctive: line 18
Do NOT modify real code outside of docblocks.
- Distinctive: line 24
Use JSDoc format with the following conventions:
- Very specific: line 26
Start with / on its own line.
- Very specific: line 27
Use * prefix for each line.
- Distinctive: line 29
Keep descriptions concise but complete.
- Distinctive: line 30
Start your sentences with a capital letter and end with a period.
- Distinctive: line 33
Add a blank line after the summary if adding more details.
- Very specific: line 37
Add @throws for functions that may throw errors and list these errors.
- Very specific: line 40
When an item is deprecated, include a @deprecated tag with a brief explanation and, if applicable, suggest an alternative.
- Very specific: line 41
Use {@link ...} tags to reference other items in the codebase when relevant.
- Very specific: line 42
Add @see tags at the very end when applicable to point to other related items or documentation.
- Distinctive: line 143
When invoked as a command, follow these steps:
- Distinctive: line 152
If a path argument is provided, scan only that path.
- Very specific: line 153
Look for TypeScript/JavaScript files (.ts, .tsx, .js, .jsx).
- Very specific: line 160
If --all is passed, also identify non-exported items.
≈ “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
Add Missing Docblocks
Scan the specified path (or entire repository if no path given) and add missing docblocks to all exported functions, classes, interfaces, types, and constants.
Key Rules
- All exported functions, types, interfaces, and constants MUST have JSDoc docblocks.
- Start with
/**, use*prefix for each line, end with*/— each on its own line. - Begin with a clear one-to-two line summary. Add a blank line before tags.
- Include
@param,@typeParam,@return,@throws, and at least one@examplewhen helpful. - Use
{@link ...}to reference related items. Add@seetags at the end for related APIs. - Do NOT modify real code outside of docblocks. Do NOT modify existing docblocks.
Guidelines
Style
Use JSDoc format with the following conventions:
- Start with
/**on its own line. - Use
*prefix for each line. - End with
*/on its own line. - Keep descriptions concise but complete.
- Start your sentences with a capital letter and end with a period.
- Limit your usage of em dashes but, when you do use them, use spaces on both sides.
- Begin with a clear one or two line summary (no
@summarytag needed). - Add a blank line after the summary if adding more details.
- Include
@paramtags for all parameters. - Include
@typeParamtags for all type parameters. Use@typeParam, not@template. - Include
@returntag briefly describing the return value. - Add
@throwsfor functions that may throw errors and list these errors. - Include at least one
@examplesection whenever usage examples would be helpful. If the file is a TypeScript file, use TypeScript syntax in examples. Try to make the examples realistic but concise and pleasant to read. They must illustrate the concepts clearly at first glance. When more than one example is preferred, use multiple@exampletags and keep the first one as simple as possible to illustrate the basic usage. Never useanytype in examples. Display theimportstatements required for the example to work when imports from multiple libraries are required. It is acceptable to use placeholder variable names likemyUseror even/* ... */for parts that are not relevant to the example. When multiple example sections are provided, add a brief description before each code block to quickly explain what the example illustrates. - In the rare case where more advanced documentation is also needed for the item, use the
@remarkstag to add this extra information after any example sections. These remarks can include longer explanations and even additional code blocks if necessary. - When an item is deprecated, include a
@deprecatedtag with a brief explanation and, if applicable, suggest an alternative. - Use
{@link ...}tags to reference other items in the codebase when relevant. - Add
@seetags at the very end when applicable to point to other related items or documentation. Use@see {@link ...}format when linking to other code items.
Examples
/**
* Creates a retry wrapper around an async function.
*
* Retries the given function up to `maxRetries` times with exponential
* backoff between attempts.
*
* @param fn - The async function to retry.
* @param maxRetries - Maximum number of retry attempts.
* @param baseDelay - Base delay in milliseconds between retries.
* @return A wrapped version of `fn` that retries on failure.
* @throws Throws the last error if all retry attempts are exhausted.
*
* @example
* ```ts
* const fetchWithRetry = withRetry(fetchData, 3, 1000);
* const data = await fetchWithRetry('/api/users');
* ```
*
* @example
* Custom retry configuration for flaky network calls.
* ```ts
* const resilientFetch = withRetry(
* () => fetch('https://api.example.com/data'),
* 5,
* 500,
* );
* ```
*/
export function withRetry<T>(
fn: (...args: unknown[]) => Promise<T>,
maxRetries: number,
baseDelay: number,
): (...args: unknown[]) => Promise<T>;/**
* Fixes a `Uint8Array` to the specified length.
*
* If the array is longer than the specified length, it is truncated.
* If the array is shorter than the specified length, it is padded with zeroes.
*
* @param bytes - The byte array to truncate or pad.
* @param length - The desired length of the byte array.
* @return The byte array truncated or padded to the desired length.
*
* @example
* Truncates the byte array to the desired length.
* ```ts
* const bytes = new Uint8Array([0x01, 0x02, 0x03, 0x04]);
* const fixedBytes = fixBytes(bytes, 2);
* // ^ [0x01, 0x02]
* ```
*
* @example
* Adds zeroes to the end of the byte array to reach the desired length.
* ```ts
* const bytes = new Uint8Array([0x01, 0x02]);
* const fixedBytes = fixBytes(bytes, 4);
* // ^ [0x01, 0x02, 0x00, 0x00]
* ```
*/
export const fixBytes = (
bytes: ReadonlyUint8Array | Uint8Array,
length: number,
): ReadonlyUint8Array | Uint8Array;/**
* A tree structure representing a set of instructions with execution constraints.
*
* Supports parallel execution, sequential execution, and combinations of both
* through recursive composition of plan nodes.
*
* @example
* ```ts
* const plan: InstructionPlan = parallelPlan([
* sequentialPlan([instructionA, instructionB]),
* instructionC,
* instructionD,
* ]);
* ```
*
* @see {@link SingleInstructionPlan}
* @see {@link ParallelInstructionPlan}
* @see {@link SequentialInstructionPlan}
*/
export type InstructionPlan =
| ParallelInstructionPlan
| SequentialInstructionPlan
| SingleInstructionPlan;Command Process
When invoked as a command, follow these steps:
Arguments
[path](optional): Narrow the scan to a specific path (e.g.src/utilsorpackages/my-lib/src).[--all](optional): Also scan non-exported items.
Steps
- If a path argument is provided, scan only that path; otherwise scan the entire repository.
- Look for TypeScript/JavaScript files (
.ts,.tsx,.js,.jsx). - Identify exported items without docblocks:
export functionexport classexport interfaceexport typeexport const(for constants and arrow functions)
- If
--allis passed, also identify non-exported items. - For each item missing a docblock:
- Analyze the code to understand its purpose (this may span multiple files).
- Examine parameters, return types, and behavior.
- Generate an appropriate docblock following the style guide.
- Present all changes clearly, grouped by file. Apply all changes without requiring further approval.
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.

