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

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

  • 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

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
  1. Distinctive:

    All exported functions, types, interfaces, and constants MUST have JSDoc docblocks.

    line 13
  2. Very specific:

    Start with /, use * prefix for each line, end with */ — each on its own line.

    line 14
  3. Very specific:

    Use {@link ...} to reference related items.

    line 17
  4. Distinctive:

    Do NOT modify real code outside of docblocks.

    line 18
  5. Distinctive:

    Use JSDoc format with the following conventions:

    line 24
  6. Very specific:

    Start with / on its own line.

    line 26
  7. Very specific:

    Use * prefix for each line.

    line 27
  8. Distinctive:

    Keep descriptions concise but complete.

    line 29
  9. Distinctive:

    Start your sentences with a capital letter and end with a period.

    line 30
  10. Distinctive:

    Add a blank line after the summary if adding more details.

    line 33
  11. Very specific:

    Add @throws for functions that may throw errors and list these errors.

    line 37
  12. Very specific:

    When an item is deprecated, include a @deprecated tag with a brief explanation and, if applicable, suggest an alternative.

    line 40
  13. Very specific:

    Use {@link ...} tags to reference other items in the codebase when relevant.

    line 41
  14. Very specific:

    Add @see tags at the very end when applicable to point to other related items or documentation.

    line 42
  15. Distinctive:

    When invoked as a command, follow these steps:

    line 143
  16. Distinctive:

    If a path argument is provided, scan only that path.

    line 152
  17. Very specific:

    Look for TypeScript/JavaScript files (.ts, .tsx, .js, .jsx).

    line 153
  18. Very specific:

    If --all is passed, also identify non-exported items.

    line 160

≈ “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

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 @example when helpful.
  • Use {@link ...} to reference related items. Add @see tags 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 @summary tag needed).
  • Add a blank line after the summary if adding more details.
  • Include @param tags for all parameters.
  • Include @typeParam tags for all type parameters. Use @typeParam, not @template.
  • Include @return tag briefly describing the return value.
  • Add @throws for functions that may throw errors and list these errors.
  • Include at least one @example section 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 @example tags and keep the first one as simple as possible to illustrate the basic usage. Never use any type in examples. Display the import statements required for the example to work when imports from multiple libraries are required. It is acceptable to use placeholder variable names like myUser or 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 @remarks tag 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 @deprecated tag with a brief explanation and, if applicable, suggest an alternative.
  • Use {@link ...} tags to reference other items in the codebase when relevant.
  • Add @see tags 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/utils or packages/my-lib/src).
  • [--all] (optional): Also scan non-exported items.

Steps

  1. If a path argument is provided, scan only that path; otherwise scan the entire repository.
  2. Look for TypeScript/JavaScript files (.ts, .tsx, .js, .jsx).
  3. Identify exported items without docblocks:
    • export function
    • export class
    • export interface
    • export type
    • export const (for constants and arrow functions)
  4. If --all is passed, also identify non-exported items.
  5. 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.
  6. Present all changes clearly, grouped by file. Apply all changes without requiring further approval.

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.