playbooks

home / skills / oimiragieo / agent-studio / detailed-docstrings

detailed-docstrings skill

/.claude/skills/_archive/dead/detailed-docstrings

This skill enforces detailed Google-style docstrings for all functions, methods, and classes in JavaScript, improving clarity, testing, and maintainability.

npx playbooks add skill oimiragieo/agent-studio --skill detailed-docstrings

Review the files below or copy the command above to add this skill to your agents.

Files (3)
SKILL.md
1.6 KB
---
name: detailed-docstrings
description: Requires detailed Google-style docstrings for all functions, methods, and classes.
version: 1.0.0
model: sonnet
invoked_by: both
user_invocable: true
tools: [Read, Write, Edit]
globs: '**/*.py'
best_practices:
  - Follow the guidelines consistently
  - Apply rules during code review
  - Use as reference when writing new code
error_handling: graceful
streaming: supported
---

# Detailed Docstrings Skill

<identity>
You are a coding standards expert specializing in detailed docstrings.
You help developers write better code by applying established guidelines and best practices.
</identity>

<capabilities>
- Review code for guideline compliance
- Suggest improvements based on best practices
- Explain why certain patterns are preferred
- Help refactor code to meet standards
</capabilities>

<instructions>
When reviewing or writing code, apply these guidelines:

- **Detailed Docstrings:** All functions, methods, and classes must have Google-style docstrings, thoroughly explaining their purpose, parameters, return values, and any exceptions raised. Include usage examples where helpful.
  </instructions>

<examples>
Example usage:
```
User: "Review this code for detailed docstrings compliance"
Agent: [Analyzes code against guidelines and provides specific feedback]
```
</examples>

## Memory Protocol (MANDATORY)

**Before starting:**

```bash
cat .claude/context/memory/learnings.md
```

**After completing:** Record any new patterns or exceptions discovered.

> ASSUME INTERRUPTION: Your context may reset. If it's not in memory, it didn't happen.

Overview

This skill enforces and produces detailed Google-style docstrings for all functions, methods, and classes in JavaScript codebases. It focuses on clarity and completeness so that each symbol has a clear purpose, parameter descriptions, return value documentation, exception notes, and usage examples. The goal is consistent, discoverable documentation that helps maintainers and users understand code quickly.

How this skill works

The skill scans JavaScript source files and inspects function, method, and class declarations and expressions. For each symbol it evaluates existing comments and either verifies compliance with Google-style docstring rules or generates a complete docstring that covers purpose, parameters, returns, throws, and usage samples. It can show inline suggestions and proposed refactors to improve clarity or fill missing details.

When to use it

  • Adding or updating public APIs and library code
  • Preparing code for release or external consumption
  • Enforcing documentation standards in a CI/CD pipeline
  • Code review focused on maintainability and onboarding
  • Refactoring modules where intent or error cases are unclear

Best practices

  • Document behavior, side effects, and assumptions, not just signatures
  • Describe parameters with types, expected shapes, and any default behavior
  • Include return value types and structure; state when null/undefined can be returned
  • List exceptions or error conditions a caller should handle
  • Provide a short usage example demonstrating common cases and edge handling

Example use cases

  • Audit a utilities module and generate docstrings for all exported functions
  • Convert inline comments into full Google-style docstrings during a refactor
  • Run as a pre-commit or CI checker to fail builds when docstrings are missing or incomplete
  • Suggest improved parameter names and descriptions to clarify ambiguous APIs
  • Produce example snippets for public methods to include in developer documentation

FAQ

Will the skill change code implementation when adding docstrings?

No. The skill only inserts or suggests comment blocks and may propose non-functional refactors (renames or small signature clarifications) separately; it does not alter runtime logic without explicit approval.

Does it support TypeScript and JSDoc types?

Yes. It recognizes TypeScript annotations and common JSDoc typing patterns and will include type information in generated Google-style docstrings when available.