Agent skill
doc-generator
Generate markdown documentation from Python codebases by analyzing source files, extracting docstrings, type hints, and code structure. Use when the user asks to document Python code, create API docs, or generate README files from source code.
Install this agent skill to your Project
npx add-skill https://github.com/basher83/agent-auditor/tree/main/.claude/skills/doc-generator
SKILL.md
Python Documentation Generator
Generate comprehensive markdown documentation from Python source code.
When to Use This Skill
- User asks to "document this code" or "generate docs"
- Creating API documentation from Python modules
- Generating README files with usage examples
- Extracting docstrings and type signatures into readable format
- User mentions "documentation", "docstrings", or "API reference"
Input
Accept either:
- Single Python file path
- Directory path (recursively process .py files)
- List of specific files
Output Format
Generate standard markdown with:
# Module Name
Brief description from module docstring.
## Classes
### ClassName
Description from class docstring.
**Methods:**
- `method_name(param: type) -> return_type`: Brief description
## Functions
### function_name(param: type) -> return_type
Description from docstring.
**Parameters:**
- `param` (type): Description
**Returns:**
- type: Description
## Usage Examples
```python
# Extract from docstring examples or generate basic usage
## Analysis Approach
1. **Parse Python files** using AST or inspection
2. **Extract key elements:**
- Module-level docstrings
- Class definitions and docstrings
- Function/method signatures with type hints
- Docstring content (support Google, NumPy, Sphinx formats)
3. **Organize hierarchically** (modules -> classes -> methods -> functions)
4. **Generate clean markdown** with consistent formatting
## Quality Guidelines
- Preserve original docstring formatting when meaningful
- Include type hints prominently in signatures
- Group related items (all classes together, all functions together)
- Add table of contents for large modules
- Skip private members (leading underscore) unless explicitly requested
- Handle missing docstrings gracefully (note "No description provided")
## Python Tools
Prefer standard library:
- `ast` module for parsing
- `inspect` module for runtime introspection
- `pathlib` for file handling
No external dependencies required for basic documentation generation.
## Error Handling
- Skip files with syntax errors (log warning)
- Handle missing type hints gracefully
- Warn if no docstrings found but continue processing
- Validate file paths exist before processing
Recommended Agent Skills
Expand your agent's capabilities with these related and highly-rated skills.
basher83/agent-auditor
crawl4ai
This skill should be used when users need to scrape websites, extract structured data, handle JavaScript-heavy pages, crawl multiple URLs, or build automated web data pipelines. Includes optimized extraction patterns with schema generation for efficient, LLM-free extraction.
basher83/agent-auditor
multi-agent-composition
This skill should be used when the user asks to "choose between skill and agent", "compose multi-agent system", "orchestrate agents", "manage agent context", "design component architecture", "should I use a skill or agent", "when to use hooks vs MCP", "build orchestrator workflow", needs decision frameworks for Claude Code components (skills, sub-agents, hooks, MCP servers, slash commands), context management patterns, or wants to build effective multi-component agentic systems with proper orchestration and anti-patterns guidance.
basher83/agent-auditor
command-creator
This skill should be used when the user asks to "create a slash command", "write a command file", "add command to plugin", "create /command", "write command frontmatter", "add command arguments", "configure command tools", needs guidance on command structure, YAML frontmatter fields (description, argument-hint, allowed-tools), markdown command body, or wants to add custom slash commands to Claude Code plugins with proper argument handling and tool restrictions.
basher83/agent-auditor
test-blocked-fixture
This is a test fixture with intentional violations for regression testing. It contains <angle brackets> which trigger B5, and has an unexpected frontmatter property which triggers W2.
basher83/agent-auditor
skill-factory
Research-backed skill creation workflow with automated firecrawl research gathering, multi-tier validation, and comprehensive auditing. Use when "create skills with research automation", "build research-backed skills", "validate skills end-to-end", "automate skill research and creation", needs 8-phase workflow from research through final audit, wants firecrawl-powered research combined with validation, or requires quality-assured skill creation following Anthropic specifications for Claude Code.
basher83/agent-auditor
hook-creator
This skill should be used when the user asks to "create a hook", "write hook config", "add hooks.json", "configure event hooks", "create PreToolUse hook", "add SessionStart hook", "implement hook validation", "set up event-driven automation", needs guidance on hooks.json structure, hook events (PreToolUse, PostToolUse, Stop, SessionStart, SessionEnd, UserPromptSubmit), or wants to automate workflows and implement event-driven behavior in Claude Code plugins.
Didn't find tool you were looking for?