What is shipwrights-doctor?

A read-only diagnostic command for checking a Shipwrights installation and its project configuration. It checks YAML settings, agent references, workflow stages, command availability, data-source connections, guards, locking, and telemetry.

Use it to investigate whether `.shipwrights.yml` is valid and whether the configured roles, pipeline, commands, and services can be found and reached.

It helps identify configuration or connectivity problems without changing project files.

shipwrights-doctor — Skill for Claude Code and Codex by shipwrights

Install

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.

Any agent

npx skills add shipwrights/core --skill shipwrights-doctor

Clone the repo

git clone --depth 1 https://github.com/shipwrights/core

Made for: Claude Code, Codex.

Wrote this? Show the measurements

A badge with what this costs and how it scanned, read live from this page, so it follows the numbers instead of freezing them. Markdown for a README, HTML for a documentation site or a project page.

README.md

[![agentmods](https://agentmods.dev/badge/skills/shipwrights/core/shipwrights-doctor/github.svg)](https://agentmods.dev/skills/shipwrights/core/shipwrights-doctor)

Your own site

<a href="https://agentmods.dev/skills/shipwrights/core/shipwrights-doctor"><img src="https://agentmods.dev/badge/skills/shipwrights/core/shipwrights-doctor/github.svg" alt="Measured on agentmods" height="20"></a>

Or the 80×15 button, for a site that already has a row of RSS and ATOM ones. Only the verdict fits; the numbers stay here.

Your own site · 80×15

<a href="https://agentmods.dev/skills/shipwrights/core/shipwrights-doctor"><img src="https://agentmods.dev/badge/skills/shipwrights/core/shipwrights-doctor.svg" alt="Reviewed on agentmods" width="80" height="20"></a>

Per session 54 Skills are progressive disclosure: only the name and description are preloaded; the body loads when the skill is used.

When invoked 985 The whole file, excluding the scripts and references it only reads on demand.

Security scan A 0 findings. A grade says what 26 rules found in the file — not that it is safe.

Origin original No closer match found in the catalogue.

Token cost

What 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.1	$0.00054	$0.00985
Opus 5	$0.00027	$0.00492
Sonnet 5	$0.00011	$0.00197
Haiku 4.5	$0.00005	$0.00098

Measured 9d ago against content hash 67a5e0d07b84, method: parsed. Prices are Anthropic first-party input rates as of 2026-09-09, from the pricing page.

Security

Grade A, and why

shipwrights-doctor 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 9d 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.

skills/shipwrights-doctor/SKILL.md · 107 lines

How it starts

The opening of the file, as written. The whole thing — 107 lines — stays where its author put it; the contents beside it link to each section on GitHub.

/shipwrights-doctor — diagnose the install

Validates everything Shipwright depends on without modifying anything. Read-only.

What you check

1. Config validity

.shipwrights.yml exists.
Parses as YAML.
Validates against schemas/shipwrights-config.schema.json.
Required fields present.
version matches a known schema version.

2. Roles → agents

For each role in roles[]:

The agent reference resolves to an existing agent file.
- bundled → agents/<role>.md in plugin
- user: X → ~/.claude/agents/X.md
- custom: ./path → relative to project root
- npm: @org/pkg → installed in node_modules
The agent file's frontmatter declares tools: matching the role's capabilities.can_write setting (write-true roles need Write/Edit; read-only roles must not have Write).

3. Pipeline references

For each stage in pipeline[]:

Owner role(s) named exist in roles[] (or are the literal orchestrator).
The stage skill exists at skills/stages/<stage>.md (bundled) or at the path declared by stage.skill (override).
requires: and optional_when: expressions parse.

4. Backlog source

backlog.source.kind resolves to a known adapter (built-in or installed npm package).
Run the adapter's healthcheck() if it exposes one (e.g., Jira: ping the API; files: confirm state_dir is writable).

5. Verify discovery

The detected verify commands actually exist (e.g., pnpm verify runs without "command not found"). Just --help or --version — don't actually run verify here.

6. Guards

Each guard's runner resolves (built-in / npm / shell command).
If runs.shell:, confirm the command is invocable.

7. Lock service

The lock backend resolves.
Markdown: register file exists or is creatable.
GitHub Issues: token in env var, repo accessible.
Custom: healthcheck() if exposed.

8. Telemetry log

telemetry.log_path parent directory is writable.
File doesn't already exist as a directory.

Read the full file on GitHub · 107 lines

Changes

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.

9d ago First seen · 107 lines · 54 tokens per session scan A 67a5e0d07b84

Subscribe to this mod's changes

shipwrights-doctor is a skill published in the GitHub repository shipwrights/core (2 stars, last pushed 1mo ago), licensed MIT. It adds 54 tokens to every session and 985 once invoked, about $0.0003 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.

Claude Code Debugging Orchestration agentic-coding ai-agents claude-code-plugin epic-management

skeptical-triage

Reusable 3-round self-challenge + arbiter pattern for filtering false positives from findings/verdicts. Use when the cost of a false-positive gate block exceeds the cost of 4 extra LLM turns.

avelikiy/great_cto · 49 tokens

anti-patterns

Catalogue of known SDLC anti-patterns that greatcto agents must actively reject when reviewing architecture, plans, code, or post-mortems. Used by architect (pre-impl), pm (planning), senior-dev (impl), l3-support (post-incident).

avelikiy/great_cto · 59 tokens

observability-baseline

Scaffold-time observability so a shipped product is not blind in prod from day one — error capture (Sentry), request-id structured logging, and /healthz + /readyz endpoints. stack-baseline pins Sentry but nothing wires it; this is the wiring. Loaded by app-scaffolder (bake into the scaffold), infra-provisioner (prod…

avelikiy/great_cto · 100 tokens

shipwrights-doctor