python docstring generator

    1

    Automated Python docstring generator using AST analysis for Google and NumPy styles.

    Free

    Security scanned

    Works with the AI Agents you already use

    Claude CodeClaude CodeCursorCursorCodex CLICodex CLIMuseMuseDotsDots+21 more

    python docstring generator

    Example session with this skill installed

    Run a dry-run on the ./src folder using numpy style. Show me a diff for what it would add to the existing functions, but skip private methods.

    • Read your context and instructions
    • Compiled the python docstring generator

    I have performed a dry-run on the ./src directory. The AST analysis found 3 undocumented functions and 1 class.

    Proposed Docstring Changes

    --- src/calculator.py
    +++ src/calculator.py
    @@ -10,6 +10,16 @@
         def add_vectors(self, vec_a: list[float], vec_b: list[float]) -> list[float]:
    +        """
    +        Add vectors.
    +        
    +        Parameters
    +        ----------
    +        vec_a : list[float]
    +            Description.
    +        vec_b : list[float]
    +            Description.
    +            
    +        Returns
    +        -------
    +        list[float]
    +            Description.
    +        """
             if len(vec_a) != len(vec_b):
                 raise ValueError("Vectors must be equal length")
             return [a + b for a, b in zip(vec_a, vec_b)]
    
    --- src/utils.py
    +++ src/utils.py
    @@ -42,5 +42,15 @@
     async def fetch_data(url: str, timeout: int = 30):
    +    """
    +    Fetch data.
    +    
    +    Parameters
    +    ----------
    +    url : str
    +        Description.
    +    timeout : int, default 30
    +        Description.
    +        
    +    Raises
    +    ------
    +    ConnectionError
    +        Description.
    +    """
         # implementation details...
    

    Next steps

    1. Review the diff above to ensure the AST correctly identified all type annotations.
    2. Run python scripts/docstring_gen.py --target ./src --style numpy --skip-private --write to apply these changes.
    3. Manually replace the "Description." placeholders with actual functional explanations.

    Connects securely to your tools. The creator never sees your data.

    About this skill

    Writing docstrings by hand is a repetitive drain on development time. This skill automates the creation of Google or NumPy style documentation stubs for Python classes and functions using AST analysis.

    What it does

    • Automated stubbing generates docstring skeletons for functions, async functions, and classes.
    • AST introspection extracts argument names, type annotations, default values, and return types.
    • Exception mapping identifies raise statements in function bodies to populate the "Raises" section.
    • Style support toggles between Google and NumPy formatting standards.
    • Safety checks utilizes dry-runs and unified diffs to prevent accidental file corruption.

    How it works

    1. Point the tool at a specific file or source directory using the --target flag.
    2. Select a formatting style and run a dry-run to see a count of undocumented objects.
    3. Review the proposed changes using --diff to verify structural accuracy.
    4. Execute with --write to apply the docstrings directly to the source code.

    Frameworks & tools

    This skill is built for Python 3.8+ environments. It uses the standard library ast module and requires no third-party dependencies.

    Why this beats prompting it yourself

    Generic LLM prompts often hallucinate types or miss edge-case exceptions hidden in deep logic. This skill uses a deterministic AST parser to guarantee every argument and explicit raise statement is captured without context-window limitations.

    Use cases

    • Legacy cleanup to document large, undocumented codebases before a handoff.
    • CI preparation to ensure all public APIs meet documentation standards.
    • Library publishing to generate NumPy-style skeletons for scientific packages.
    • Refactoring to keep docstrings in sync with updated type annotations.

    Known limitations

    Does not infer logic or write natural language descriptions. Skips files over 500 KB or those with syntax errors. Requires valid UTF-8 encoding.

    Descriptions are placeholders. Skips non-UTF-8 files and files over 500 KB. Requires Python 3.8+. Skips dunder methods by default.

    How to use

    1. 1

      Connect your agent to the Agensi MCP

      Copy the prompt and paste it into Claude, ChatGPT, Cursor or any agent that supports MCP. It sets up the connection for you. Manual setup

    2. 2

      Sign in to Agensi

      Your agent shows a sign-in link. Sign in and click Allow.

    3. 3

      Ask for what you need

      Your agent loads this skill and uses it on your task. It always asks before any payment.

    Reviews

    No reviews yet

    Be one of the first to try it. Every listed skill goes through the trust checks below.

    Security scanned

    Checked by our 8-point scan before listing

    Fresh listing

    Recently published to Agensi

    Free forever

    No account required to browse

    Trust & safety

    Security scan

    Security scan passed 4 days ago

    • Free with an Agensi account

    Requires

    Python

    Permissions

    Terminal / Shell
    Read Files
    Write Files
    Listed4 days ago

    What's inside

    Frequently Asked Questions

    This skill uses Abstract Syntax Tree (AST) analysis to deterministically extract argument names, type hints, and exceptions directly from your code, ensuring 100% accuracy that generic LLMs often miss due to hallucinations or context limits.

    The skill is compatible with Python 3.8+ and operates as a standalone CLI tool or integrated module, requiring no third-party dependencies for maximum portability across different AI agent environments.

    No, the tool generates structural skeletons including parameters, types, and raises; it does not write natural language descriptions of 'why' the code exists, allowing you to fill in the logic-specific details manually.

    The skill includes a safety-first workflow featuring a 'dry-run' mode and a unified diff viewer, allowing you to preview exactly how your source code will be modified before any changes are committed to disk.

    You receive the complete Python skill package, documentation for CLI usage, and support for both Google and NumPy formatting styles, allowing you to standardize documentation across diverse project types.

    New in Prompt & Skill Engineering