From shipyard
Generates inline code docstrings, API documentation, README updates, and architecture docs for public interfaces, breaking changes, complex algorithms, and incomplete docs.
npx claudepluginhub lgbarn/shipyard --plugin shipyardThis skill uses the workspace's default tool permissions.
<!-- TOKEN BUDGET: 290 lines / ~870 tokens -->
Provides templates and best practices for README files, API documentation, user guides, changelogs, inline code comments, and architecture docs.
Provides templates and best practices for writing README files, API documentation, user guides, changelogs, architecture docs, and inline code comments.
Prevents silent decimal mismatch bugs in EVM ERC-20 tokens via runtime decimals lookup, chain-aware caching, bridged-token handling, and normalization. For DeFi bots, dashboards using Python/Web3, TypeScript/ethers, Solidity.
Share bugs, ideas, or general feedback.
Generate accurate, useful documentation that serves its audience. API docs for developers, guides for users, architecture docs for maintainers.
The documenter agent references this skill for systematic documentation generation.
Document non-obvious code for developers reading the implementation.
What to document:
What NOT to document: Anything a competent developer can understand by reading the code itself.
HOW — step by step:
Format: Docstrings with parameters, returns, exceptions, and examples for functions. Purpose and responsibilities for classes. Overview for modules.
Help developers use public interfaces correctly.
HOW — step by step:
Per endpoint/function:
Checklist:
Help developers understand system design and make consistent changes.
HOW — step by step:
Architecture doc example:
## Components
| Component | Responsibility | Does NOT handle |
|-----------|---------------|-----------------|
| API Gateway | Route requests, auth validation | Business logic |
| User Service | CRUD user accounts | Billing, permissions |
| Notification Worker | Send emails/SMS async | Template rendering |
## Key Decision: Event-Driven vs. Synchronous
**Decision:** Use async events for cross-service communication
**Rationale:** Decouples services; allows independent scaling
**Rejected:** Direct HTTP calls — too much coupling, cascading failures
Checklist:
Help end-users accomplish tasks.
HOW — step by step:
User guide example:
## How to Set Up Webhook Notifications
**Prerequisites:** Admin account, HTTPS endpoint that accepts POST requests
1. Go to Settings → Integrations → Webhooks
2. Click **Add Webhook**
3. Enter your endpoint URL (must start with `https://`)
4. Select events to subscribe to (e.g., `user.created`, `order.paid`)
5. Click **Save** — a test ping is sent to your endpoint immediately
**Expected:** Your endpoint receives a `POST` with `{"event": "test.ping"}`
**If it fails:** Check that your endpoint returns HTTP 200. Non-200 responses
are retried 3 times then marked failed.
Types:
Checklist:
NEVER SHIP A PUBLIC API WITHOUT DOCSTRINGS
No exceptions:
Spirit vs. Letter: Technically having a docstring that says "Creates a user" satisfies the letter but violates the spirit. Documentation must enable a developer to use the interface without reading the implementation.
Stop and fix before shipping:
TODO: inside documentation ("TODO: document this parameter")| Pitfall | Example | Fix |
|---|---|---|
| Over-commenting obvious code | x += 1 # increment x | Delete the comment |
| Redundant docstrings | def get_user(): → """Gets a user.""" | Add args, returns, raises, example |
| Missing "why" | Documents WHAT the code does, not WHY | Add rationale for non-obvious choices |
| Hallucinated examples | Example calls function with wrong signature | Run every example before committing |
| Template docs | Copies docstring structure without real content | Verify every field has actual values |
| Excuse | Reality |
|---|---|
| "It's obvious from the name" | Obvious names still need types, return values, and error conditions |
| "We'll document it later" | "Later" becomes "never" once the team moves on |
| "Only internal use" | Internal APIs become public APIs when the team grows |
| "The tests serve as docs" | Tests cover inputs/outputs; docs explain purpose and constraints |
| "Too busy right now" | Undocumented APIs cost more time in support and onboarding |
| "AI can read the code" | Future AI instances still benefit from documented intent and rationale |
x = 5 # set x to 5)# Cache invalidation here because user permissions
# affect multiple downstream services. Without this,
# stale permissions persist for up to 5 minutes (TTL).
invalidate_permission_cache(user.id)
x = x + 1 # increment x by 1
def create_user(name: str, email: str, role: str = "viewer") -> User:
"""Create a new user account.
Args:
name: Display name (1-100 characters).
email: Must be unique across all accounts.
role: One of "viewer", "editor", "admin". Defaults to "viewer".
Returns:
The newly created User object with generated ID.
Raises:
DuplicateEmailError: If email is already registered.
Example:
user = create_user("Alice", "alice@example.com", role="editor")
"""
def create_user(name, email, role="viewer"):
"""Creates a user."""
Called by: shipyard:documenter — when generating phase documentation Pairs with: shipyard:shipyard-verification — documentation completeness is part of "done" Pairs with: shipyard:code-simplification — clear code needs less documentation Leads to: shipyard:lessons-learned — after documentation is complete, capture what was learned