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

/code-documentation

@ff6d472 official
by flutterflutter/agent-plugins3.2k stars
193
Run it yourself

Guide for writing effective code documentation, including docstrings, JSDoc, dartdoc, and implementation comments. Use this skill when writing new code, adding features, or improving existing documentation in Dart, Python, or TypeScript to ensure clarity and maintainability.

Use this Skill: https://skilld.dev/gh/flutter/agent-plugins/code-documentation

Nothing lands on disk. Nothing to clean up.

Fork this Skill

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

SKILL.md

≈74 tokens for metadata: the name and description. ≈919 when used: this file. ≈2.3k more on demand in 3 files.

Description uses 3.7% 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 ≈296 characters, or 3.7%.

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.

Code Documentation Skill

This skill provides comprehensive guidelines for documenting code, prioritizing user-centric writing, clarity, and consistency.

1. General Philosophy

  • User-Centric: Write for the person using your API. If you had to look up how to use something, document it so others don't have to.
  • Explain "Why": Explain why code exists and how to use it effectively, since the code signature already tells what it does.
  • Be Concise: Omit fluff. Avoid merely restating the code name, as it is not helpful.
  • Consistency: Use standard terminology and consistent formatting.
  • Public APIs: Document all public APIs (classes, members, top-level functions) without exception.
  • Code Samples: Strongly consider adding code samples to explain usage.

2. General Structure

Follow this general structure for documentation comments across languages:

  1. Summary Sentence: Start with a single-sentence summary on the first line, ending with a period.
  2. Blank Line: Follow the summary with a blank line.
  3. Details: Add paragraphs, code samples, or lists as needed to explain parameters, return values, exceptions, and behavior.
  4. Annotations: Place doc comments before any metadata annotations.

3. Writing Guidelines

Brevity & Style

  • Avoid Fluff: Omit "This class...", "This method...", "Is used to...", "Note that...".
    • Bad: "This method is used to calculate the total."
    • Good: "Calculates the total."
  • Third-Person Verbs: Start function/method docs with a third-person singular verb.
    • Examples: "Returns...", "Calculates...", "Updates...", "Creates...".
  • Noun Phrases: Start variable/property docs with a noun phrase.
    • Examples: "The current color.", "A list of active users.".
  • Booleans: Always start with "Whether" (or similar clear indicator).
    • Good: "Whether this widget is enabled."
    • Bad: "If this widget is enabled...", "True if...", "Flag to indicate...".
  • Avoid Jargon: Use plain English unless the term is a widely accepted standard (e.g., "HTTP", "URL").

Formatting

  • Sparingly: Use Markdown features (bold, lists) sparingly.
  • No HTML: Avoid HTML unless strictly necessary and supported by the documentation tool.
  • Parameters/Returns/Exceptions: Use prose to describe parameters, return values, and thrown exceptions. Do not rely solely on tags like @param unless mandated by the language standard (e.g., Javadoc).

4. Implementation Comments

Ensure implementation comments (//) are accurate, relevant, factual, and provide information that is not readily understandable from the code. Remove or reword comments that do not meet these criteria. If an implementation comment provides information useful to an API consumer that is not already in the documentation comments, move it to the documentation comments.

5. Review Checklist

Use this checklist to verify your documentation:

  1. Summary: Ensure every public member starts with a one-sentence summary ending in a period.
  2. Brevity: Remove "This class..." or "This function..." fluff.
  3. Completeness: Document strict constraints (e.g., "must not be null") and exceptions.
  4. Examples: Consider adding a code sample for complex widgets or methods.

6. Language Specific Instructions

Refer to the language guides for detailed instructions on structure, linking, and framework-specific patterns:

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

    This skill provides educational guidelines and style conventions for writing code documentation. It contains no executable scripts, external dependencies, or security risks.

  • Socket3mo

    No alerts

  • Snyk3mo

    Risk: LOW · No issues

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

Last checked against GitHub yesterday.

Activeupdated 4 months ago

README badge

README badge for flutter/agent-plugins/code-documentation