just-init
just-init
Use __init__.py docstrings as the single source of truth for navigating and
documenting Python packages.
Read Rule
When navigating to a new directory in the codebase, read its __init__.py to
understand the package. The docstring tree tells you what's inside and where.
Subdirectory entries include [start:end] — the line range of that directory's
__init__.py docstring. Use these as offset and limit to read only the
docstring, not the entire file. This eliminates extra tool calls.
Docstring Format
Every __init__.py must start with a triple-quoted docstring:
"""
One-line description of what this package does.
package_name/
├── __init__.py # Package init and public exports.
├── subpackage/ # Brief description of subpackage. [1:15]
├── module_a.py # Brief description of module_a.
└── module_b.py # Brief description of module_b.
├── ClassA # Does something. [10:50]
└── func_b # Does something else. [52:80]
"""
Rules:
├──for all entries except the last (└──).- Subdirectories first (alphabetical), then
.pyfiles (alphabetical). - Subdirectories end with
/, not expanded.[start:end]= their__init__.pydocstring lines. - Files with 3+ public definitions get sub-entries with
description [start:end]. - Descriptions under 10 words. Package name matches the directory name.
Update Rule
After any file or directory add, remove, or rename — update the __init__.py
docstring. New package: create __init__.py first. Propagate changes to parent
if a sub-package entry changed.
Missing or outdated docstring: fix it before proceeding.
Automation
uv run scripts/just-init.py <generate|verify|update> <path> — see
automation for modes, options, and hook setup.
References
- Scoping — when to apply, what to skip
- Automation — script modes and Claude Code hook
- Line index — line-range sub-entry details
- Flat package
- Nested packages
- Non-Python directories
- Update: adding a file
- Update: adding a sub-package
More from fredericosantos/skills
astral-ruff
Guide for using ruff, the extremely fast Python linter and formatter. Use this when linting, formatting, or fixing Python code to maintain code quality and consistency.
35astral-uv
Guide for using uv, the extremely fast Python package and project manager. Use this when working with Python projects, scripts, packages, or tools to manage dependencies, environments, and project setup with universal lockfiles for reproducible builds.
18astral-ty
Guide for using ty, the extremely fast Python type checker and language server. Use this when type checking Python code or setting up type checking in Python projects.
17ghp
Guide for GitHub project management via `gh` CLI — issues, PRs, milestones, sub-issues, projects, and development workflow. Use this whenever you need to interact with GitHub issues, milestones, sub-issues, PRs, or projects. Also use when planning work, creating branches, structuring issues, or starting a development session on a repository.
2dotstate
Guide for using dotstate, a profile-based dotfile manager with GitHub sync. Use this when managing dotfiles across multiple machines (e.g., Ubuntu and macOS), adding files to sync, switching profiles, or troubleshooting symlinks.
2