# Python Docstring Standard

> Standardize Python function docstrings to a team format with a short summary, optional second-paragraph logic notes, optional Args/Returns sections. Default coding style uses four-space indentation and an object-oriented design mindset. Use when adding or normalizing docstrings in Python files, including class methods and nested callback functions.

- **Type:** Skill
- **Install:** `agentstack add skill-wty-yy-skills-python-docstring-standard`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [wty-yy](https://agentstack.voostack.com/s/wty-yy)
- **Installs:** 0
- **Category:** [Agent Skills](https://agentstack.voostack.com/c/agent-skills)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [wty-yy](https://github.com/wty-yy)
- **Source:** https://github.com/wty-yy/skills/tree/master/python-docstring-standard

## Install

```sh
agentstack add skill-wty-yy-skills-python-docstring-standard
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# Python Docstring Standard

## Mandatory Opening Block (for Python script files)
When editing a runnable Python script, the very beginning of the script text (typically module docstring/header) must include:
1. What the script does (core functionality).
2. A brief usage overview.
3. If invokable from CLI:
   - Minimal startup command.
   - Full startup command with configurable options explained (only when extra configurable parameters are needed).
4. Add a `Notes:` section for caveats, environment assumptions, or operational reminders when needed.
5. If the script has no additional configurable parameters beyond the minimal command, omit both `Full Command:` and `Options:`.

Recommended structure:
```python
""".

Overview:
.

Quick Start:
    python path/to/script.py 

Full Command:
    python path/to/script.py --arg1 ... --arg2 ...

Options:
    --arg1: 
    --arg2: 

Notes:
    
"""
```

## Overview
Apply this skill when the user asks to add, rewrite, or normalize Python docstrings by team convention. Edit only documentation text and keep runtime behavior unchanged.

## Coding Defaults
- Use 4 spaces per indentation level in all Python code snippets and generated examples.
- Do not use tab characters for indentation.
- Prefer object-oriented decomposition when structure decisions are needed: model related state/behavior in classes, and keep method responsibilities focused.
- For class methods, describe both the method action and its role within the class responsibility.

## Required Format
Use triple double quotes (`"""`) for every function entry (`def`), including class methods and nested functions unless the user narrows scope.

Write docstrings in this order:
1. First paragraph: one brief sentence describing the function's functionality.
2. Second paragraph: if needed, describe invocation/build logic directly as normal prose.
3. `Args:` section only when the function has input parameters worth documenting.
4. `Returns:` section only when the function returns a meaningful value.

Use this template:
```python
"""A brief description of the function's functionality.

If necessary, include the calling/build logic here as normal second-paragraph prose. Do not use subheadings.

Args:
    arg1: Description for arg1.
    arg2: Description for arg2.

Returns:
    A description of the return value.
"""
```

## Strict Rules
- Write logic notes directly in the second paragraph.
- Omit `Args:` when there are no meaningful inputs.
- Omit `Returns:` for `None`-style procedures unless the user explicitly wants it documented.
- In script header blocks, omit `Full Command:` and `Options:` when no extra configurable parameters are required.
- Put operational cautions and assumptions under `Notes:` when applicable.
- Keep wording concise and concrete; avoid restating obvious type hints.
- Use exactly 4 spaces for indentation in Python code examples and edits; never use tabs.
- Prefer an object-oriented modeling approach by default unless the user explicitly asks for a different style.

## Editing Workflow
1. Find all target `def` entries in scope.
2. Add missing docstrings or normalize existing ones to the required format.
3. Preserve function signatures, decorators, and executable code.
4. Keep terminology consistent across related functions.
5. Run syntax validation after edits (`python -m py_compile ...`) when feasible.

## Output Expectations
When reporting results, summarize:
- Which files were updated.
- Whether syntax validation was run and passed.

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [wty-yy](https://github.com/wty-yy)
- **Source:** [wty-yy/skills](https://github.com/wty-yy/skills)
- **License:** MIT

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-wty-yy-skills-python-docstring-standard
- Seller: https://agentstack.voostack.com/s/wty-yy
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.