Agent skill

Build Scenario Tests

by tamdogood in tamdogood/builder-essential-skills

Inspect an unfamiliar repository, turn a focused Markdown behavior scenario into a deterministic test in the repository's native test stack, run it, and preserve traceability between intent and code.

MITAuto-check passedTesting & QA

Install Build Scenario Tests

skills CLI
$ npx skills add tamdogood/builder-essential-skills --skill build-scenario-tests -a claude-code

Project install by default; add -g for ~/.claude/skills/.

GitHub CLI
$ gh skill install tamdogood/builder-essential-skills build-scenario-tests --agent claude-code

Project scope by default; add --scope user for a personal install. Needs GitHub CLI 2.90.0 or later (public preview).

Manual copy
$ git clone --depth 1 https://github.com/tamdogood/builder-essential-skills.git skills-src && mkdir -p .claude/skills && cp -r skills-src/skills/build-scenario-tests .claude/skills/build-scenario-tests && rm -rf skills-src

Use ~/.claude/skills/ instead of .claude/skills for a personal install. The folder must contain SKILL.md.

Claude Code skills documentation · loads skills from .claude/skills/

Facts

Skill name
build-scenario-tests
GitHub stars
221
Token cost
~1.7k tokens
SKILL.md length
804 words
Files
8 (incl. references)
Skills in repo
18
Repo updated
First seen
Licence
MIT

At a glance

Inspect an unfamiliar repository, turn a focused Markdown behavior scenario into a deterministic test in the repository's native test stack, run it, and preserve traceability between intent and code.

  • Works in 6 steps: Pass the repository-understanding gate → Normalize the scenario → Map intent to the host test stack → …
  • Asked to add scenario tests
  • SKILL.md covers Operating contract, Workflow, Demonstration examples and Failure handling
  • Runs Python and TypeScript scripts from its folder

What it does

Build Scenario Tests is an agent skill from tamdogood/builder-essential-skills. Inspect an unfamiliar repository, turn a focused Markdown behavior scenario into a deterministic test in the repository's native test stack, run it, and preserve traceability between intent and code. Use when asked to add scenario tests, compile acceptance criteria or Given/When/Then Markdown into executable tests, reproduce a user-visible regression, or convert a narrow workflow specification into stable web, API, CLI, desktop, or mobile interaction coverage. Do not use for broad exploratory journeys or…

Its SKILL.md is about 1.7k tokens, which your agent loads only when the skill is triggered. The skill folder holds 10 other files, including reference files (for example `README.md`, `agents/openai.yaml` and `examples/cli-expired-session.scenario.md`).

It sits in Testing & QA, covering QA and bug reports and User stories. The repository describes itself as: A repository for skills that are essential to my daily work. The licence is MIT.

When your agent uses it

  • Asked to add scenario tests
  • Compile acceptance criteria
  • Given/When/Then Markdown into executable tests
  • Reproduce a user-visible regression

Example prompts

  • “/build-scenario-tests”

Requirements

  • Python 3
  • Node.js

Workflow steps

6 steps, taken from the step headings in SKILL.md.

  1. Pass the repository-understanding gate
  2. Normalize the scenario
  3. Map intent to the host test stack
  4. Compile the deterministic test
  5. Prove the compilation
  6. Hand off the evidence

What it can do on your machine

Read from SKILL.md and the folder at commit 1be9984. It shows what the files ask for, not the result of running them.

  • Tool permissions

    Pre-approves nothing: there is no allowed-tools line, so your agent's usual permission prompts apply.

    From allowed-tools in the SKILL.md frontmatter.

  • Runs code

    Ships script files (Python and TypeScript), which the agent can run.

    From the folder's file list and the shell code blocks in SKILL.md.

  • Network

    No URLs in SKILL.md.

    From URLs in SKILL.md, links to its own repository left out.

  • Credentials

    Names no API keys, tokens, secrets or passwords.

    From names ending in _API_KEY, _TOKEN, _SECRET, _KEY or _PASSWORD in SKILL.md.

Context cost

Build Scenario Tests loads about 1.7k tokens when it runs, and up to ~2.2k if it reads all its reference files. Until then it costs about 139 tokens; SKILL.md has 804 words of instructions outside code blocks.

Always · name and description, kept in context so the agent knows when to use it
~139
When it runs · the whole SKILL.md, loaded when a task matches
~1.7k
With references · SKILL.md plus every file in references/, read only if the agent opens them
~2.2k

Estimates: characters ÷ 4, the usual rule of thumb; real counts depend on the model's tokenizer. Scripts and assets cost tokens only if the agent reads them.

Safety

Auto-check passed

The automated check found no risky patterns in SKILL.md.

Automated static check — not a guarantee. Review scripts before installing. It scans the text of SKILL.md for risky patterns (piping downloads into a shell, reading credential files, hidden Unicode, destructive commands); files beside SKILL.md are not scanned.

SKILL.md

The full file from tamdogood/builder-essential-skills at commit 1be9984, republished under its MIT licence (© tamdogood). 804 words, ~1,689 tokens.

Download SKILL.mdSave it as .claude/skills/build-scenario-tests/SKILL.md (or your agent's skills folder). This skill also uses 7 other files; get the full folder from GitHub.
name
build-scenario-tests
description
Inspect an unfamiliar repository, turn a focused Markdown behavior scenario into a deterministic test in the repository's native test stack, run it, and preserve traceability between intent and code. Use when asked to add scenario tests, compile acceptance criteria or Given/When/Then Markdown into executable tests, reproduce a user-visible regression, or convert a narrow workflow specification into stable web, API, CLI, desktop, or mobile interaction coverage. Do not use for broad exploratory journeys or agent-judged smoke tests.

Build Scenario Tests

Compile one small behavior contract into deterministic, repository-native test code. Understand the host project before choosing a harness, command, fixture, selector, or assertion.

Operating contract

  • Treat repository instructions and existing tests as authoritative.
  • Keep each scenario focused on one behavior and one reason to fail.
  • Compile into the test stack the repository already uses. Add a dependency only when no suitable harness exists and the user accepts the tradeoff.
  • Make setup, inputs, actions, and expected results deterministic.
  • Prefer public behavior over implementation details. Assert what a user or external caller can observe.
  • Keep the Markdown scenario beside the test or in the repository's established specification directory. Record the mapping in both artifacts.
  • Never weaken an assertion merely to make a test pass.

Workflow

1. Pass the repository-understanding gate

Read the nearest AGENTS.md or equivalent instructions, product README, contribution guide, manifests, test configuration, and the smallest relevant product documentation. Use repository search to find the implementation entry point, neighboring tests, fixtures, stable selectors, and validation commands. Trace the relevant action from its public entry point through the state boundary to the observable result. Do not read the entire tree without a reason.

Before editing, be able to state:

text
product surface:
behavior source:
relevant architecture and data flow:
runtime or start command:
existing test runner:
nearest tests to imitate:
fixture and state-isolation strategy:
narrow validation command:
full validation command:
known trust or destructive boundaries:

If a material field is unknown, search again. If the repository does not answer it, expose the gap and ask only for the missing product decision. Do not invent commands, selectors, credentials, or expected behavior.

2. Normalize the scenario

Read references/scenario-format.md. If the user provided prose, rewrite it into that contract without changing its intent.

Reject or split a scenario when it:

  • contains multiple independent behaviors;
  • depends on subjective visual judgment;
  • requires uncontrolled third-party state, real payment, or human authorization;
  • uses vague outcomes such as "works correctly";
  • cannot reset its data, time, randomness, or network dependencies.

Route a broad or agent-judged journey to a smoke-test workflow instead.

3. Map intent to the host test stack

Create a compact mapping before writing code:

Scenario elementRepository implementation
Preconditionsfixture, factory, seed, fake, or setup API
User actionpublic UI, CLI, HTTP, SDK, or native interaction
Oraclevisible state, output, response, durable state, or emitted event
Cleanuptransaction rollback, fixture teardown, or isolated temp state

Choose the narrowest existing harness that reaches the behavior:

  • web or desktop UI: the repository's browser or UI runner;
  • API or service: the native integration-test client;
  • CLI: the existing subprocess or command runner;
  • mobile: the project's native UI-test framework;
  • library: the public API through its current test runner.

Do not force a browser test onto behavior that a stable public API test can prove more directly.

Show full SKILL.md (375 more words)Show less
4. Compile the deterministic test

Write the test in surrounding style. Preserve this traceability:

  • include the scenario ID in the test name or metadata;
  • link the scenario path from a short code comment when local conventions allow;
  • keep every oracle from the Markdown represented by an assertion;
  • use stable roles, labels, test IDs, public outputs, or API contracts;
  • isolate state with existing factories, fakes, temporary directories, or transactions;
  • control time, randomness, retries, and network calls when they affect results;
  • make cleanup run even after a failed assertion.

Do not copy the bundled demonstration code blindly. It contains fictional fixtures to show the mapping, not reusable project infrastructure.

5. Prove the compilation

Run the new test alone. Confirm it fails for the intended reason without the behavior or regression fix when that check is safe and practical. Then run the nearest relevant suite and the repository's required lint, type, build, and test commands.

Inspect failures semantically. Fix the test only when the test is wrong. Do not change product behavior unless the user asked for the implementation or fix.

Check for:

  • every Markdown oracle has a matching assertion;
  • no accidental live service, account, payment, or production dependency;
  • repeated runs use isolated state and stable ordering;
  • failure output identifies the broken behavior;
  • the scenario and compiled test link to each other.
6. Hand off the evidence

Report:

  1. what repository evidence informed the test design;
  2. the scenario path and compiled test path;
  3. the behavior and boundaries covered;
  4. commands run and results;
  5. anything intentionally left to integration or smoke coverage.

Demonstration examples

Use these to explain the Markdown-to-code model. When applying the skill, derive all commands, fixtures, and assertions from the actual repository.

Failure handling

  • No test harness: document the nearest viable seam and ask before adding a dependency.
  • Behavior is undocumented or contradictory: preserve the evidence and ask the product owner which outcome is authoritative.
  • Failure requires subjective or human judgment: keep the deterministic portion as a scenario test and route the rest to smoke coverage.
  • Test is flaky after two focused attempts: stop, preserve logs, and report the uncontrolled input instead of adding retries.

© tamdogood, MIT. Rendered from Markdown: HTML in the file is shown as text, images as links, and headings moved down two levels. Raw file

Files

SKILL.md and 7 other files (references) in skills/build-scenario-tests of tamdogood/builder-essential-skills.

  • SKILL.md
  • README.md
  • agents/openai.yaml
  • examples/cli-expired-session.scenario.md
  • examples/test_cli_expired_session.py
  • examples/web-workspace-invite.scenario.md
  • examples/web-workspace-invite.spec.ts
  • references/scenario-format.md

Open the folder on GitHubat commit 1be9984

Compare with similar skills

Build Scenario Tests next to the 5 skills that share the most tags, products or categories with it. Stars are the repository's; “used in” counts other GitHub owners with a copy.

Build Scenario Tests compared with similar skills
SkillStarsUsed inTokensAuto-checkLicenceRepo updated
Build Scenario Tests this skilltamdogood/builder-essential-skills221—~1.7kAutomated safety check: PassMIT
Dynamo Jira TicketDynamoDS/Dynamo2k—~1.1kAutomated safety check: PassApache-2.0
QAwp-media/wp-rocket767—~552Automated safety check: PassGPL-2.0
Kb Testing StrategyCommunity-Access/accessibility-agents423—~1.4kAutomated safety check: PassMIT
Build Doddanshapiro/kilroy222—~2.5kAutomated safety check: PassMIT
Software Engineering Standardskitchen-engineer42/pdf2skills134—~921Automated safety check: PassNone

Similar skills

  • Dynamo Jira Ticket

    DynamoDS/Dynamo

    Create structured Jira tickets for Dynamo from bug reports, failing tests, or feature requests.

    2k GitHub stars~1.1k tokensUpdated yesterday
    Testing & QAAuto-check passed
  • QA

    wp-media/wp-rocket

    Run QA validation on a pull request — boots the local environment, tests acceptance criteria, and optionally posts the report as a PR comment.

    767 GitHub stars~552 tokensUpdated yesterday
    Product & Project ManagementAuto-check passed
  • Kb Testing Strategy

    Community-Access/accessibility-agents

    Reference data, not a reviewer. An agent skill from Community-Access/accessibility-agents.

    423 GitHub stars~1.4k tokensUpdated 17 days ago
    Testing & QAAuto-check passed
  • Build Dod

    danshapiro/kilroy

    A skill your agent uses when converting a spec, requirements document, or goal statement into a Definition of Done with acceptance criteria and integration test scenarios

    222 GitHub stars~2.5k tokensUpdated 5 mo ago
    Testing & QAAuto-check passed
  • Software Engineering Standards

    kitchen-engineer42/pdf2skills

    Reference and apply IEEE, ISO/IEC, and other software engineering standards for development, quality assurance, and project management.

    134 GitHub stars~921 tokensUpdated 7 mo ago
    Testing & QAAuto-check passed
  • Release

    codewhale-hq/Codewhale

    Prepare a named version: preflight, version consistency, build/package, smoke test, checksums/notes, and release readiness.

    41k GitHub stars~189 tokensUpdated today
    Testing & QAAuto-check passed

More from tamdogood/builder-essential-skills

All 18 skills in this repo
  • Create Marketing Kit

    tamdogood/builder-essential-skills

    Create truthful, human-centered marketing campaigns for an app or product, including positioning, channel copy, original artwork, editable layouts, README banners, and selective website integration.

    221 GitHub stars~1.9k tokensUpdated 1 mo ago
    Auto-check passed
  • Name Your Business

    tamdogood/builder-essential-skills

    Generate, refine, compare, and when needed validate distinctive names for startups, AI products, developer tools, protocols, open-source projects, apps, product families, local businesses, services…

    221 GitHub stars~4.3k tokensUpdated 1 mo ago
    Auto-check passed
  • Session Profiler

    tamdogood/builder-essential-skills

    Profile and debug Hermes sessions from their JSONL transcripts.

    221 GitHub stars~1.5k tokensUpdated 1 mo ago
    Auto-check passed
  • Create Skill

    tamdogood/builder-essential-skills

    Create or update a complete repository skill from a user's idea, including the workflow instructions, references, scripts or assets, agent metadata, skill-card artwork, cinematic banner artwork…

    221 GitHub stars~1.4k tokensUpdated 1 mo ago
    Auto-check passed
  • Paper Opportunity Radar

    tamdogood/builder-essential-skills

    Run a cumulative daily or retrospective sweep of research papers on a chosen topic, audit their claims, methods, integrity signals, and independent support, then identify overlooked but feasible…

    221 GitHub stars~3.1k tokensUpdated 1 mo ago
    Auto-check passed
  • Repo System Map

    tamdogood/builder-essential-skills

    Analyze a software repository at the latest remote main commit and turn its implemented architecture into a citation-backed interactive isometric system map with a legend, selectable infrastructure…

    222 GitHub stars~3k tokensUpdated 1 mo ago
    Auto-check: notes

Questions about Build Scenario Tests

What does Build Scenario Tests do?

Inspect an unfamiliar repository, turn a focused Markdown behavior scenario into a deterministic test in the repository's native test stack, run it, and preserve traceability between intent and code. Build Scenario Tests is an agent skill from tamdogood/builder-essential-skills. Inspect an unfamiliar repository, turn a focused Markdown behavior scenario into a deterministic test in the repository's native test stack, run it, and preserve traceability between intent and code.

When should I use Build Scenario Tests?

Build Scenario Tests fits situations like: asked to add scenario tests; compile acceptance criteria; given/When/Then Markdown into executable tests; reproduce a user-visible regression.

How do I install Build Scenario Tests in Claude Code?

Run `npx skills add tamdogood/builder-essential-skills --skill build-scenario-tests -a claude-code`. Or copy the skill folder (skills/build-scenario-tests in tamdogood/builder-essential-skills) into .claude/skills/build-scenario-tests in your project. Claude Code loads it when a task matches its description.

How do I install Build Scenario Tests in Codex?

Run `npx skills add tamdogood/builder-essential-skills --skill build-scenario-tests -a codex`. Or copy the skill folder (skills/build-scenario-tests in tamdogood/builder-essential-skills) into .agents/skills/build-scenario-tests in your project. Codex loads it when a task matches its description.

Can I use Build Scenario Tests in Cursor, Gemini CLI or GitHub Copilot?

Cursor, Gemini CLI, GitHub Copilot and OpenCode also load SKILL.md folders. With the skills CLI, run `npx skills add tamdogood/builder-essential-skills --skill build-scenario-tests -a cursor` (or -a gemini-cli, github-copilot or opencode for the others). To copy it by hand, put the folder in .cursor/skills/build-scenario-tests, .gemini/skills/build-scenario-tests, .github/skills/build-scenario-tests and .opencode/skills/build-scenario-tests in your project.

What does Build Scenario Tests need to run?

Going by SKILL.md and its folder, Build Scenario Tests needs Python and TypeScript for the scripts in its folder. Our summary lists: Python 3; Node.js.

Does Build Scenario Tests access the network?

SKILL.md contains no URLs. Any network use would come from the scripts or tools the agent runs. This is read from the text; nothing was executed.

Is Build Scenario Tests safe to install?

Our automated static check of SKILL.md found no risky patterns, such as piping downloads into a shell, reading credential files or hidden Unicode. It is not a guarantee. Review the folder before installing.

What licence does Build Scenario Tests use?

Build Scenario Tests is published under the MIT licence (the repository's licence). It allows redistribution, so the full SKILL.md is shown on this page.

How many tokens does Build Scenario Tests use?

About 1.7k tokens (SKILL.md is roughly 6.8k characters). Agents keep only the skill's name and description in context until a task matches; then they load SKILL.md in full. Its references folder adds about 510 tokens, read only when the agent opens those files.

What are the alternatives to Build Scenario Tests?

Skills that share tags, products or a category with Build Scenario Tests: Dynamo Jira Ticket (DynamoDS/Dynamo, 2k stars), QA (wp-media/wp-rocket, 767 stars), Kb Testing Strategy (Community-Access/accessibility-agents, 423 stars) and Build Dod (danshapiro/kilroy, 222 stars). The comparison table on this page puts their stars, adoption, token cost, safety result and licence side by side.

Who maintains Build Scenario Tests?

tamdogood (a GitHub user) maintains it in tamdogood/builder-essential-skills, which has 221 GitHub stars. The repository holds 18 skills in this directory. The repository was last updated on August 16, 2026.

Source: tamdogood/builder-essential-skills on GitHub. Facts on this page come from the repository at the commit we read; the author's words are quoted as theirs.