cucumber-sentences (Claude Code skill)

A Claude Code skill that documents the Ruby gem cucumber-sentences — the Gherkin DSL on top of page-object + watir used to write browser-driven Cucumber scenarios in plain English.

When this skill is loaded, Claude knows the full catalogue of 39 registered phrases, the page-class contract (get_field / get_button / get_element_by_name / get_ckeditor / get_js_selector), how to wire helpers (Domain, typed of <type> "<id>"), and how to share state between steps. It can read or write .feature files, page objects, and step definitions without re-deriving the conventions every time.

Install

Via the skills CLI (recommended)

npx skills add donkeycode/skills-cucumber-sentences

The CLI drops the skill into .claude/skills/cucumber-sentences/ of the current project. Restart Claude Code (or run /skills to refresh) and the skill triggers automatically when you edit .feature files, page-object classes, or step definitions.

Manual install

# Project-scoped (committed with the project)
mkdir -p .claude/skills
git clone https://github.com/donkeycode/skills-cucumber-sentences.git .claude/skills/cucumber-sentences

# OR user-scoped (available in every project on this machine)
mkdir -p ~/.claude/skills
git clone https://github.com/donkeycode/skills-cucumber-sentences.git ~/.claude/skills/cucumber-sentences

Verify

After install you should have a SKILL.md reachable at one of:

• <project>/.claude/skills/cucumber-sentences/SKILL.md
• ~/.claude/skills/cucumber-sentences/SKILL.md

Inside Claude Code, asking "how do I add a button to a feature in this project" (when the project has Cucumber + page-object + cucumber-sentences) should now route through this skill.

When does it trigger?

Automatically, when:

• A .feature file is being created or edited.
• A page-object class is being created or has its locators / get_X resolvers edited.
• A Cucumber::Undefined or "undefined step" error is being investigated.
• You want to add a kind of object resolvable by name (I am on the "OrderEditPage" of order "ABC-123") — needs a typed helper.
• You need to share state across steps in the same scenario (e.g. extract a link from an email, follow it later).

What's inside

SKILL.md                              Entry point — frontmatter, decision tree, mapping mechanics, fast templates
references/
  sentences-catalogue.md              All 39 registered phrases with regex, retry semantics, examples
  page-class-contract.md              Page-object contract, `is_on_page`, naming conventions, pitfalls
  helpers-and-state.md                Domain helper, typed `<type>` helpers, session-scoped state holders
templates/
  step_definitions_imports.rb         Entry point that requires the gem
  page.rb                             Full page-class skeleton with all `get_X` resolvers stubbed
  helper_domain.rb                    `Domain.get(name)` → base URL
  helper_typed.rb                     Typed `Order.get(id)` → params hash
  state_holder.rb                     `@@`-class-var holder with optional reset

Compatibility

The skill targets:

• cucumber-sentences ~> 0.0.18 (single-file gem, ~500 LOC; analysis based on commit 9661eb1)
• Ruby + Cucumber 10.x + page-object 2.x + watir 7.x + selenium-webdriver 4.x
• Chrome via selenium/standalone-chrome Docker image, or local Chrome with chromedriver

If a future release of the gem adds or renames phrases, regenerate references/sentences-catalogue.md from the updated lib/cucumber-sentences.rb.

Source

• Upstream gem: https://github.com/donkeycode/cucumber-sentences
• This skill: https://github.com/donkeycode/skills-cucumber-sentences

License

MIT — same as the upstream gem. See LICENSE.

Contributing

Found an inaccuracy or want to add a missing pattern (a new helper recipe, a project-side step extension worth sharing, …) ? Open a PR.

When updating the sentence catalogue, always re-run grep -n -E '^(Given|When|Then)\(' lib/cucumber-sentences.rb against the upstream gem to confirm the count and regex of every phrase. The catalogue must stay in sync with the gem version it claims to document.