Index of every page on this site: llms.txt
All skills
amanktyr avatar

/documentation

@5711aad
by Aman Ktyramanktyr/tailor6 stars
Run it yourself

Governs code comments, API documentation, JSDoc/TSDoc typing docs, README standards, and prevents verbose filler documentation.

Use this Skill: https://skilld.dev/gh/amanktyr/tailor/documentation

Nothing lands on disk. Nothing to clean up.

Fork this Skill

Edit a local copy. It keeps the author and licence.

SKILL.md

≈36 tokens for metadata: the name and description. ≈515 when used: this file.

Description uses 1.8% of example budget

Before choosing a Skill, your Agent reads its name and description. All available Skills share that space.

  • A shorter description leaves more room for other Skills. This entry exceeds our 1% size suggestion.

In our Claude Code example, all Skill names and descriptions share 8,000 characters. This Skill uses ≈143 characters, or 1.8%.

The 1% threshold is a size suggestion. Longer descriptions can still fit.

Your model, settings, and other Skills decide how much text your Agent can read.

Example settings and source

The example uses a 200k-token context and default Claude Code settings. The count includes the name, description, separators, and when_to_use when present. Codex also counts local file paths.

Skit's source and limits: Codex 0.160.1, Claude Code 2.1.292.

Documentation & Comments Skill

Activate this skill when documenting modules, writing API specifications, authoring READMEs, adding inline code comments, or updating project memory.

Documentation Law: Document the "Why" and non-obvious constraints, never the self-evident "What".


1. Code Comments: Document "Why", Not "What"

  • High-Value Comments (Encouraged):
    • Documenting subtle edge cases, workaround for upstream library bugs, concurrency locks, or regulatory/compliance reasons.
    • Explaining complex mathematical algorithms, bitwise tricks, or performance-critical micro-optimizations.
  • Low-Value Comments (Forbidden):
    • Restating obvious code (// increment counter by 1, // return user object).
    • Stale comments that no longer match the active code behavior.

2. JSDoc / TSDoc Standards for Public APIs

For public functions, exported hooks, and library interfaces, provide concise TSDoc comments:

/**
 * Synchronizes multi-agent adapter rules across 10+ AI coding assistant platforms.
 *
 * @param workspaceRoot - Absolute path to the active project root directory.
 * @param options - Synchronization flags including overwrite behavior and verbosity.
 * @returns Array of relative file paths that were generated or updated.
 * @throws {Error} If workspaceRoot does not exist or lacks write permissions.
 */
export async function syncAdapters(
  workspaceRoot: string,
  options: SyncOptions = {}
): Promise<string[]> {
  // ...
}

3. Evidence-Based Project Documentation Invariants

  1. Zero Placeholder Documentation: Never ship generic "TODO: Add documentation here" blocks in production memory files.
  2. Verifiable Command Examples: Every command listed in READMEs or .ai/ documentation must be directly runnable in the project workspace with zero guesswork.
  3. Keep a Changelog Standard: Record public releases in CHANGELOG.md following Semantic Versioning (MAJOR.MINOR.PATCH) with categories: Added, Changed, Deprecated, Removed, Fixed, Security.

Source: SKILL.md on GitHub

No rule matched.

skilld matched fixed text patterns in SKILL.md and file names. Patterns miss obfuscated code.

skilld run checks every file with the same patterns. It asks for approval before it loads a Skill with a behavior marked Needs approval.

No alerts3mo3 checks · Risk SAFE
  • Gen Agent Trust Hub3mo

    The skill provides guidelines for writing high-quality code documentation and comments. It does not contain any executable code, network operations, or sensitive data access.

  • Socket3mo

    No alerts

  • Snyk3mo

    Risk: LOW · No issues

Signed by skilld at 5711aad. This ties the file your Agent reads to that commit on GitHub. It does not review the instructions.

Last checked against GitHub last month.

Steadyupdated 3 months ago

README badge

README badge for amanktyr/tailor/documentation