Getting it into your agent
One page per mod, every tool's command on it. A separate URL per tool would split the same page into five that compete with each other.
npx agentmods add skills/vimalk0703/shipworthy/documentation-as-codenpx skills add Vimalk0703/shipworthy --skill documentation-as-codegit clone --depth 1 https://github.com/Vimalk0703/shipworthyWhat it costs to keep this loaded
Counted locally with the o200k_base tokenizer, which is exact for GPT models; Claude uses its own tokenizer and its counts differ. Treat this as one consistent yardstick across the catalogue rather than a bill. Prices are per million input tokens.
| Model | Per session | Once invoked |
|---|---|---|
| Fable 5 | $0.00027 | $0.00542 |
| Opus 5 | $0.00014 | $0.00271 |
| Sonnet 5 | $0.00005 | $0.00108 |
| Haiku 4.5 | $0.00003 | $0.00054 |
Grade A, and why
documentation-as-code scanned grade A with 0 findings against 26 rules in 11 categories — prompt injection, anti-refusal, data exfiltration, privilege escalation, supply chain, agent snooping, system-prompt leakage, SSRF and excessive agency — measured 2d ago.
A static scan of the body, not an audit. Every finding is printed with the line that produced it so you can judge whether it matters here. A mod is markdown that instructs an agent; that is exactly why what it instructs is worth reading.
Nothing flagged
None of the 26 patterns this scan looks for appear in this file: no shell pipes, no recursive deletes, no credential paths, no hidden text, no instruction-override or anti-refusal phrasing, no agent-config snooping. That is not a guarantee, it is the absence of the things that are checkable.
How it starts
The opening of the file, as written. The whole thing — 69 lines — stays where its author put it; the contents beside it link to each section on GitHub.
Documentation as Code
Principle
Documentation that lives outside the codebase rots. Keep documentation as close to the code as possible, ideally generated from it.
What to Document
Always Document
- Public API functions (JSDoc/docstrings with params, returns, throws)
- Module purpose (brief comment at top of file explaining what this module does)
- Non-obvious business logic (why, not what)
- Architecture decisions (ADRs in
.shipworthy/decisions/) - API endpoints (request/response types serve as documentation)
- Environment variables (what each one does, valid values)
Don't Document
- Self-explanatory code (
getUser(id)doesn't need a docstring saying "gets a user") - Implementation details that change frequently
- Code that should be refactored instead of documented
JSDoc Pattern (TypeScript/JavaScript)
/**
* Calculate insurance premium based on fleet safety score.
*
* @param fleetScore - Safety score from 0-100
* @param basePremium - Current annual premium in dollars
* @returns Adjusted premium with discount/surcharge applied
* @throws {AppError} If fleetScore is outside valid range
*/
export function calculatePremium(fleetScore: number, basePremium: number): number {
README Requirements
Every project README should have:
- What — one sentence explaining what this project does
- Quick start — how to run it locally (3 commands max)
- Architecture — high-level overview (link to architecture.md for details)
- Contributing — how to contribute
Architecture Decision Records
For significant decisions, create .shipworthy/decisions/NNN-title.md:
# ADR-NNN: [Decision Title]
## Status: Accepted | Superseded | Deprecated
## Date: YYYY-MM-DD
## Context: [What prompted this decision]
## Decision: [What was decided]
## Consequences: [What this means going forward]
Changelog
Maintain a CHANGELOG.md for user-facing changes:
- Added — new features
- Changed — changes in existing functionality
- Fixed — bug fixes
- Removed — removed features
- Security — vulnerability fixes
What this file has done since we first saw it
Hashed on every crawl. A supply-chain change to an agent config is a question of when, not whether, so the history is kept rather than the latest state alone.
- 2d ago First seen · 69 lines · 27 tokens per session scan A 145a2147ea3e
documentation-as-code is a skill published in the GitHub repository Vimalk0703/shipworthy (7 stars, last pushed 4mo ago), licensed MIT. It adds 27 tokens to every session and 542 once invoked, about $0.0001 per session on Opus 5. A static security scan graded it A with 0 findings. No closer match exists in the catalogue, so it is treated as the original; first seen 2026-08-31.
Other skills, from other repositories
roam
Codebase comprehension via roam-code CLI. Use when exploring codebases, planning modifications, debugging failures, assessing PR risk, or checking architecture health. Triggers on: understanding project structure, pre-change safety checks, finding symbols/files, blast radius analysis, affected tests, health scoring…
ring:writing-plans
Writing a rolling-wave phased implementation plan from a spec before coding: a phase-epic-task hierarchy where Phase 1 is detailed into dispatch-ready tasks and later phases stay epic-level for elaboration during execution. Use when a multi-file feature needs decomposition; runs after ring:exploring-codebases or…
ring:searching-code
Forensic code search and analysis with optional Chain of Draft (CoD) ultra-concise mode. Five-phase methodology (clarification, planning, execution, analysis, synthesis) with severity assessment. Use for targeted investigation of specific patterns, bugs, or vulnerabilities. Skip for broad architecture mapping (use…
ring:exploring-codebases
Exploring a codebase across phases: scopes the target, detects architecture, components, and layers, deep-dives each discovered perspective, then synthesizes findings into actionable guidance with file:line evidence. Use to understand how a feature or system works before planning changes, or to orient on an unfamiliar…
ring:writing-skills
Writing or editing a Ring skill: SKILL.md structure, frontmatter and Agent-Search-Optimization rules, token-efficiency targets, and bulletproofing (Iron Law, rationalization tables, Red Flags) so discipline-enforcing skills resist excuses. Use when creating or revising a skill. Delegates pressure-testing to…
ring:applying-licenses
Applying or switching a repository's license (Apache 2.0, Elastic License v2, or Proprietary): rewrites the LICENSE file, updates Go/TS source headers, sets SPDX identifiers, and validates consistency after user confirmation. Use when asked to set, apply, or switch a license, or when scaffolding a service with no…