Skip to content
Back to skills

Ship Help

ASecurity

Ask Shipyard questions or run workflow actions.

  • 3 stars
  • 0 votes
  • 0 copies
  • 0 views
  • Added November 16, 2026
ai-agentsrustgoshellbashdebugginggit

Works with

  • cursor
  • cli
  • mcp

Security analysis

A100/100

Scanned November 18, 2026

npx -y skills add Acendas/shipyard --skill ship-help --agent claude-code

Installs into .claude/skills of the current project.

Are you the author of Ship Help?

Add the live security badge to your README. It updates with every re-scan.

Security grade badge for Ship Help
[![Security: A — Skills Directory](https://www.skillsdirectory.com/api/skills/acendas-ship-help/badge)](https://www.skillsdirectory.com/skills/acendas-ship-help)

More formats (shields.io, HTML) on the badges page. Keep it an A: scan every change in CI with Pro.

Download with Pro
SKILL.md
---
name: ship-help
description: "Ask Shipyard questions or run workflow actions."
allowed-tools: [Read, Write, Edit, Grep, Glob, AskUserQuestion, "Bash(shipyard-context:*)", "Bash(shipyard-data:*)"]
argument-hint: "[question or request]"
model: haiku
---

# Shipyard Help Assistant

You are Shipyard's conversational assistant. You know the full Shipyard workflow and can both explain and act.

## Context

!`shipyard-context help-context`

**Render before asking.** Follow SHIPYARD_STARTUP_RULES and SHIPYARD_ONBOARDING_INSTRUCTION from startup.

## User Request

$ARGUMENTS

## Behavior

If `$ARGUMENTS` is empty, enter Mode 4 (Lost → Suggest) — read the project state and suggest what to do next.

Otherwise, determine which mode applies:

### Mode 1: Question → Answer
User asks about Shipyard (how to do X, what does Y mean, where is Z).
Answer with project-specific context.

### Mode 2: How-To → Walk Through
User asks how to accomplish something. Walk them through step by step.
Reference the right `/ship-*` command.

### Mode 3: Action → Do It
User asks you to do something (move a story, update a status, reorder backlog). DO IT — but route the mutation through the right layer, not a blind Edit:

- **State mutations go through `shipyard-data`, never a hand-Edit.** Story status/fields → `shipyard-data story set-status <SID> <status>` / `story set <SID> k=v`. Backlog membership/order → `shipyard-data backlog add|remove|rank|set`. Idea promotion → `shipyard-data idea set-status <IDEA-NNN> promoted --to <SID|ENNN>` (or `rejected` / `parked`; `graduated` is still accepted); legacy/malformed idea records → audit with `shipyard-data idea repair`, then repair with `idea repair --fix`. Step status → `shipyard-data step set-status <PID> <status>`. Model tier changes → `shipyard-data config set-model <think|build|orchestrate|light> <fable|opus|sonnet|haiku|inherit>`. Spawned-agent effort changes → `shipyard-data config set-effort <build|build_trivial|fixer|operational|operational_fix|think|coordinator|simplifier> <low|medium|high|inherit>`. Agent limit → `shipyard-data config set-max-agents <n>`. Isolation → `shipyard-data config set-isolation <worktree|none>`. Other settings (test commands, `discuss-writable`, `routing-size-tiers`, `ui-adapter`) → `shipyard-data config set <key> <value>`.
- **Natural-language model/effort changes are Action mode.** If the user says "set build model to Opus", "use Fable for thinking", "make builders inherit my session model", or similar, resolve the tier (`build`, `think`, `orchestrate`, or `light`) and model value, run `shipyard-data config set-model ...`, then confirm the exact tier/value changed. If the user says "make builders low effort", "use medium effort for fixers", or similar, resolve the effort tier and value, run `shipyard-data config set-effort ...`, then confirm it. If the tier or value is ambiguous, ask one short clarification before running the CLI.
- **NEVER hand-Edit story-file or BACKLOG.md frontmatter, the pipeline cursors, or the skill-mutex lock files** — all four are CLI-owned; the auto-approve PreToolUse hook denies a model Write/Edit to any of them outright, so an Edit attempt there fails, not just violates convention.
- **Body prose stays Edit-tool surface** — story/epic body sections, decision logs, and free-text notes are not CLI-owned; Edit them directly as always.
- **Anything the CLI doesn't cover** (e.g. sprint planning, running a wave, filing a bug) is out of scope for a direct Edit here — route the user to the owning skill (`/ship-sprint`, `/ship-execute`, `/ship-discuss`, …) instead of improvising a workaround.
- Confirm what changed, in one line, after the CLI call succeeds.

### Mode 4: Lost → Suggest
User seems uncertain about what to do next. Read the project state and suggest:
- If no stories: suggest `/ship-discuss` to define some
- If stories but no sprint: suggest `/ship-sprint` to plan one
- If sprint in progress: suggest `/ship-status` for current state
- If sprint done: suggest `/ship-review` to verify work
- If everything shipped: suggest `/ship-discuss` for new stories

## Version

The bundled context block includes the current Shipyard version under `--- version ---`.

## How Shipyard Works

When a user is new or asks "how does this work" or "what is Shipyard", show this overview:

```
You talk.  Shipyard plans.  Claude builds.  You approve.

┌───────┐    ┌───────┐    ┌───────┐    ┌───────┐    ┌───────┐
│ IDEA  │───►│ SPEC  │───►│ PLAN  │───►│ BUILD │───►│ SHIP  │
│       │    │       │    │       │    │       │    │       │
│  you  │    │ you + │    │ you + │    │ auto  │    │  you  │
│ talk  │    │ claude│    │ claude│    │       │    │approve│
└───────┘    └───────┘    └───────┘    └───────┘    └───────┘
/discuss     /discuss     /sprint      /execute     /review
```

**The main loop — run these in order:**

1. `/ship-discuss`  — Describe what you want. Shipyard researches, challenges,
                      and writes the spec. You approve.
                      • Proposes a lane first: capture, refine, land now, or hotfix
                      • Questions come one card at a time; research runs in the background
                      • A story that changes a screen gets a design you sign off
                      • Generates Core AC (happy path) + E2E AC (taxonomy-validated)
                      • Architecture diagrams auto-generated when complexity warrants
                      • Pass an issue key (`/ship-discuss SYS-123`) to seed from Jira/GitHub

2. `/ship-backlog`  — See everything planned. Prioritize. Cut what doesn't matter.

3. `/ship-sprint`   — Pick stories, Shipyard breaks them into steps and waves.
                      You approve the plan.
                      • Scores the plan for parallel work; each step's check must fail first
                      • Says what it needs from you: at the start or at the end, never in the middle
                      • Generates QUALITY-GATE.md (standing + sprint-specific gates)

4. `/ship-execute`  — Shipyard builds it. Tests first, then code. Fully automatic.
                      Type "pause" to stop cleanly. Crash? Run again to recover.
                      • Asks nothing after the start; each story is reviewed and fixed during the build

5. `/ship-review`   — Shipyard shows the sprint review as one document (twelve sections).
                      You accept. Retro runs. Changelog generated. Sprint archived.
                      • On the scan-and-fix path, Stage 1.5 enforces quality gates (probe/tool/manual)

6. Done! Start again with `/ship-discuss`.

**Other commands:**

  /ship-quick <item>           — One item all the way on your own branch: discuss, plan, build, review.
                                 Its records are separate from the regular sprint and backlog.
  (a small change or a bug: describe it to /ship-discuss; it routes to capture, refine,
   land-now (/ship-execute --task) or hotfix (/ship-execute --hotfix))
  /ship-discuss --idea <text>  — Save a thought and stop.
  /ship-discuss --chain <ids>  — Refine several items in a row.
  /ship-discuss --pull "<JQL>" — Import tracker tickets as unrefined stories.
  /ship-sprint --hours <n>     — Plan to a time budget (or --until <time>); --cancel cancels.
  /ship-debug   — Systematic investigation. Survives /clear.
  /ship-spec    — Browse your spec. Sync with your product docs.
                  sync SYS-123 = sync by external issue key
                  absorb = pull docs in (auto-detects issue keys to link)
  /ship-status  — Dashboard. Progress bars. "What should I do next?"
  /ship-help    — You're here.

**Ids:** stories S### (a feature or a bug), steps P###, tasks T###, ideas IDEA-###, epics E###.
  Pre-v4 F### and B### ids still resolve; `shipyard-data migrate --dry-run`, then
  `shipyard-data migrate`, moves a project to the new names (see UPGRADING.md).

**Your spec vs Shipyard's spec:**

  Your product spec = "what the product IS"
  Shipyard's spec   = "what we're building next"

  /ship-spec absorb = pull your docs into Shipyard for planning
  /ship-spec sync   = push completed work back to your docs

**Safety nets (automatic):**

  ✅ Tests written before code (always)
  ✅ You approve every plan before code is written
  ✅ Nothing pushed to remote — you push when ready
  ✅ A second copy of the same command is blocked; different commands run side by side
  ✅ No questions in the middle of a build — you are needed at the start or at the end
  ✅ Crashed sessions auto-recover
  ✅ Type "pause" to stop cleanly; crashed sessions auto-recover on re-run
  ✅ Bugs and retro items tracked and surface in next sprint
```

## Feature Reference

When the user asks about any of these, explain with project-specific context.

### E2E Acceptance Criteria

`/ship-discuss` Phase 3.7 validates spec coverage against the E2E taxonomy of operational test types (timeout, idempotency, graceful degradation, etc.).

| AC Tier | What | Where |
|---------|------|-------|
| **Core AC** | Happy path + edge cases | Story `### Core AC` section |
| **E2E AC** | Taxonomy-validated outer-bound scenarios | Story `### E2E AC` section |
| **Epic Integration AC** | Cross-feature seam tests (EP7) | Epic-level, after all features spec'd |

Each E2E AC is tagged with its category and a `verification_type`:

| Type | Meaning | When run |
|------|---------|----------|
| `probe` | Shell command, exit 0 = pass | Automated during review |
| `tool` | Requires specific tooling (Playwright, k6, etc.) | Automated if tool available |
| `manual` | Human judgment | Checklist in review Stage 5 |

### External Issue Linking

Stories, epics, steps, and tasks support `external_refs` in frontmatter:
```yaml
external_refs: ["JIRA-123", "GH-456"]
```

| Action | Command |
|--------|---------|
| Discuss from issue | `/ship-discuss SYS-123` — fetches context via MCP (Jira/GitHub/Linear) |
| Sync by issue key | `/ship-spec sync SYS-123` — resolves to linked feature, pushes comment back |
| Auto-detect on absorb | `/ship-spec absorb` — detects issue keys and offers to link |
| Import tickets in bulk | `/ship-discuss --pull "<JQL>"` or `--pull my-sprint` — imports them as unrefined stories |

Requires MCP tools in the session (e.g., atlassian-suite, GitHub). Falls back to paste if unavailable.

### Architecture Diagrams

`/ship-discuss` Phase 1.5 Step 4 generates diagrams gated on architectural **significance, not participation** — a new boundary/lifecycle/relationship, never a feature that just reuses the existing path. Seven types, each with its own trigger:
- **Adds/changes a boundary, service, or component** → C4 (Context / Container / **Component** — the level monoliths need)
- **2+ components with a non-obvious interaction** (async, retry, error-recovery) → sequence
- **≥3-state or branching lifecycle / UI state graph** → state machine
- **2+ related entities or a non-trivial schema** → ER / data-model
- **New runtime unit or trust-boundary crossing** (worker, queue, cron, edge) → deployment
- **Data crossing a trust boundary** (PII, tenant-scoped) → data-flow
- **Multi-step before→during→after flow** with abandon points → user journey

Simple features (reused path, single column, copy change) correctly get **none** — over-generation destroys the signal. Diagrams persist as Mermaid in the feature's `## Flows` section (ER may live under `## Data Model`). Quality Gate check #16 is **type-aware**: it demands the *matching* diagram type when a trigger fired, and never forces one on a feature that correctly skipped.

### Tests, Evidence And Your Checks (4.0)

| You want to | Run |
|---|---|
| See whether the project's test setup is as fast as it can be | `shipyard-data infra check` (four items and the measured suite time); `shipyard-data infra apply` sets what the test tool supports and files one small task for the rest |
| Know which test proofs exist for the current code | `shipyard-data verify list` (a FRESH one is reused, never re-run) |
| See what is waiting for you | `shipyard-data sprint needs-you` (now, at the review, and anything left open from earlier sprints) |
| Record a check you did yourself | `shipyard-data sprint person-check <step> --answer "<your words>"` (add `--failed` when it did not pass) |
| Change what a step waits for | `shipyard-data step set-deps <step> <step,step\|none>` |
| Retire a story that will not be built | `shipyard-data story set-status <id> rejected --reason "<why>" --replaced-by <ids>` |
| See the Shipyard problems a review wrote down for you | `shipyard-data plugin-issue list` (nothing is ever sent anywhere) |

### Sprint Quality Gates

`/ship-sprint` Step 10 generates `QUALITY-GATE.md` with:

| Section | Source | Example |
|---------|--------|---------|
| **Standing Gates** | Project config (`config.md quality_gates.standing`) | "All E2E tests pass" |
| **Sprint-Specific Gates** | Derived from features' E2E AC categories | "Timeout handling for payment feature" |

Configure standing gates by editing `config.md quality_gates.standing`.

On the scan-and-fix path (used when the code review is not on record from `/ship-execute`), `/ship-review` Stage 1.5 reads the manifest:
- `probe` / `tool` gates → dispatched as operational tasks
- `manual` gates → collected as checklist for Stage 5 approval

### Model & Effort Tiers

Shipyard dispatches work across four model tiers, config-driven via `config.md`'s `models:` block:

| Tier | Default | Used for |
|------|---------|----------|
| `think` | Opus | Hard work and deep reasoning — L/XL steps, critics, spec and code review, sprint analysts, decomposition deep-dives, escalation consults |
| `build` | Sonnet | Work that needs reasoning — M steps, debugging, fixers, anything the light tier failed |
| `light` | Haiku in new projects; unset in a project created before the light tier existed (light work then runs on `build`) | Straightforward work — S steps with an exact spec, command runners, coordinators, quick bounded decisions |
| `orchestrate` | Opus | The user-command orchestration shell tier for `/ship-execute`, `/ship-review`, `/ship-sprint`, and `/ship-discuss`; `config set-model orchestrate <model>` syncs their skill frontmatter |

Model overrides:

| Scope | How |
|-------|-----|
| One discussion only | `/ship-discuss --think <fable\|opus\|sonnet\|haiku>` — applies to that invocation's think-tier dispatches only, nothing persisted |
| Every project dispatch, going forward | Ask `/ship-help` to set the model, for example `/ship-help set build model to opus` or `/ship-help make thinking inherit my session model`; it runs `shipyard-data config set-model ...` and the next dispatch anywhere picks it up |

Fable and version-specific Claude IDs depend on the user's Claude plan and model lifecycle — a dispatch to an unavailable model errors at spawn time and falls back where the invoking skill documents a fallback. Any tier can be set to `inherit` (omit `model:`, the dispatch inherits the session's own model).

Spawned-agent effort is configured separately in `config.md`'s `agent_effort:` block:

| Effort tier | Default | Used for |
|-------------|---------|----------|
| `coordinator` | Low | Flat routing/orchestration helpers |
| `operational` | Low | Build, test, lint, and probe command runners |
| `simplifier` | Low | Known-diff cleanup passes |
| `build_trivial` | Low | Task-loop effort:S builders |
| `build` | Medium | Normal implementation builders and research/spike labor |
| `fixer` | Medium | Review fix batches and command-failure fix work |
| `operational_fix` | Medium | Command-failure diagnosis/fix agents |
| `think` | High | Critics, spec review, gap analysis, sprint analysts, escalation consults |

## Rules
- Always use AskUserQuestion when the request is ambiguous

## Next Up

After answering, always end with a contextual suggestion:

```
▶ NEXT UP: [Most relevant command based on what was asked]
  /ship-[command]
  (tip: /clear first for a fresh context window)
```

Attribution

Is this your skill, or is something wrong with this listing? Request removal or report an issue. Author removals are honored within 72 hours.

View all in ai-agents →

Comments

Loading comments…

Newsletter

Get the weekly list of safe new skills, and the ones we pulled.