Create Shiplight Tests

• Create a new local Shiplight test project
• Add YAML tests for a web application
• Update or fix existing Shiplight YAML tests
• Set up or repair environments, accounts, or auth fixtures
• Plan what product behavior should be tested

Daily Skill Update Check

1. Check the timestamp file at

   .shiplight-agent-skills-last-update

   in the current project.
2. If the timestamp file is missing or older than 24 hours, run

   npx -y skills@latest update -y

   , then create/update the timestamp file even if the command fails. Treat

   .shiplight-agent-skills-last-update

   as local cache and do not commit it.
3. If the update command fails, continue with the currently installed skill and mention the failure briefly.

Test Project Root

Canonical Project Layout

specs/context.md       project-level app, risk, data, and environment context
specs/tests/           Markdown specs, each covering a feature or journey group
tests/                 executable Shiplight YAML tests
environments/          environment files, one per target deployment
auth/                  auth login modules, if needed
templates/             reusable YAML statement groups, if any
functions/             TypeScript helper functions, if any
files/                 fixture files, if any
knowledge/             durable notes discovered by agents
test-results/          generated runtime artifacts; do not edit
shiplight-report/      generated reports; do not edit
.shiplight/            local Shiplight state; do not edit

references/project-layout.md

Ground Truth

1. Explicit user instruction
2. Feature or journey spec in

   specs/tests/

3. Existing YAML test

   goal

   , step

   intent

   , and

   VERIFY

   assertions
4. Current app behavior
5. Project context in

   specs/context.md

   and

   knowledge/

6. Agent docs in this skill
7. Agent inference

Required Startup

1. Identify the Shiplight test project root.
2. Read

   references/project-layout.md

   .
3. Read

   references/knowledge.md

   .
4. Check

   knowledge/

   under the test project root for notes relevant to the task.
5. Load the task-specific guides below.
6. Tell the user which guides you loaded, then proceed.

Task-Specific Guides

references/workflow.md

references/project-layout.md

references/test-design-guide.md

references/new-tests.md

references/test-design-guide.md

references/test-implementation-guide.md

references/updating-tests.md

references/test-design-guide.md

references/test-implementation-guide.md

references/auth.md

references/test-implementation-guide.md

shiplight://yaml-test-spec

shiplight://schemas/action-entity

Core Rules

• Always produce durable artifacts unless the user explicitly asks to skip them.
• Specs describe feature or journey-group confidence. A spec may map to many smaller YAML tests.
• Keep YAML tests focused. One YAML test should verify one logical journey or variant.
• Do not write YAML from imagination. Walk the app in a browser first and capture real locators.
• Validate YAML with

  validate_yaml_test

  after writing it.
• Reflect before finishing. Capture durable knowledge learned from the user or the work, and update stale knowledge instead of leaving contradictions.
• Keep context current. Durable project knowledge belongs in

  specs/context.md

  or

  knowledge/

  , not in chat history.
• Never store raw secrets. Commit only variable names, roles, access patterns, and setup instructions.

User Checkpoints

Do these outcomes match the confidence you need from this test project? Any business-critical outcome missing or incorrectly out of scope?

Final Report

• Files created or changed
• Behavior covered or repaired
• Commands run and pass/fail result
• Knowledge or context updated, including stale notes corrected
• Any product/spec mismatch or unresolved blocker