shellkin

Category: Blockchain & Web3 | Uploader: DannyBen | Downloads: 0 | Version: v1.0（Latest）

Create and maintain Shellkin feature tests for a user's Bash project. Use this skill when the task is to add, update, debug, or review `.feature` files and `step_definitions/*.sh` files that test a shell CLI or shell scripts with Shellkin. This skill is for end-user projects that use Shellkin, not for developing Shellkin itself.

Changelog: Source: GitHub https://github.com/DannyBen/shellkin

Directory Structure

Current level: skills/shellkin/

📁 agents/
- 📄 openai.yaml 236 B
📁 references/
- 📄 patterns.md 2.2 KB
📄 SKILL.md 5.3 KB

SKILL.md

---
name: shellkin
description: Create and maintain Shellkin feature tests for a user's Bash project. Use this skill when the task is to add, update, debug, or review `.feature` files and `step_definitions/*.sh` files that test a shell CLI or shell scripts with Shellkin. This skill is for end-user projects that use Shellkin, not for developing Shellkin itself.
---

# Shellkin Feature Tests

Use this skill when working in a project that uses Shellkin to test shell behavior with Gherkin-style feature files.

This skill is for authoring tests in the user's project. Do not switch into Shellkin-maintainer mode unless the request is explicitly about Shellkin internals.

## Source Of Truth

When Shellkin is installed in the target environment, prefer the local man pages as the primary reference for current behavior and supported syntax.

Check these first when you need Shellkin-specific facts:

- `man shellkin`
- `man shellkin-test`
- `man shellkin-validate`
- `man 5 shellkin-feature`
- `man 5 shellkin-stepdefs`

Use the man pages to confirm command usage, environment variables, supported feature-file syntax, step definition rules, and helper behavior before making assumptions.

If external reference is useful, Shellkin source code and documentation are available at `https://github.com/DannyBen/shellkin`, but prefer installed man pages for user-facing behavior.

## Workflow

1. Inspect the target project before writing tests.
   Check for `features/`, existing `.feature` files, and `step_definitions/`.
   If the repo uses custom roots, respect `SHELLKIN_FEATURES_ROOT` and `SHELLKIN_STEPDEFS_ROOT`.
   Consult the relevant Shellkin man pages before relying on memory.
2. Model tests around observable behavior.
   Prefer CLI behavior, file effects, stdout, stderr, and exit status over implementation details.
3. Reuse and extend existing step definitions before adding new ones.
   Keep new steps generic enough to be reused across scenarios.
4. Write feature files in Shellkin's supported Gherkin subset only.
   Use `Feature`, optional description text, `Background`, `Scenario`, and steps with `Given`/`When`/`Then` plus `And`/`But`/`*`.
5. Validate before concluding.
   Run `shellkin validate` first when changing step matching or feature structure.
   Run `shellkin test` for execution checks when the environment allows it.

## Directory Model

Shellkin expects feature files under the selected features root, with step definitions in a sibling `step_definitions/` directory under that same root.

Typical layout:

```text
features/
├── step_definitions/
│   └── core.sh
└── example.feature
```

When a task targets a single feature area, prefer placing the feature in the existing features tree rather than inventing a parallel layout.

## Feature Authoring Rules

- Start each file with `Feature:`.
- Free text under `Feature:` is allowed before the first section.
- Use `Background:` only for setup shared by every scenario in that file.
- Use `Scenario:` for each executable example.
- Keep scenarios small and concrete.
- `And`, `But`, and `*` inherit the semantic type of the previous step, so they cannot be the first step in a scenario or background.
- Use doc strings with `"""` for multiline expectations or input.

Do not use unsupported constructs:

- `Rule`
- `Scenario Outline`
- `Examples`
- data tables
- tags such as `@slow`

## Step Definition Rules

Step definitions live in shell files under `step_definitions/` and use headers like:

```bash
@When I run '{command}'
run "$command"
```

Follow these rules:

- Headers must begin with `@Given`, `@When`, or `@Then`.
- The body continues until the next header or end of file.
- Use named `{tokens}` for variable parts.
- Token names must start with a letter or underscore, then use letters, numbers, or underscores.
- When a step matches, token values are exposed as shell variables in the body.
- Prefer a small set of reusable steps over many one-off phrases.

## Built-in Helpers And State

Prefer Shellkin's built-ins instead of hand-rolled wrappers:

- `run "$command"` captures command results and still returns success.
- `fail "message"` fails the current step with a clearer assertion message.
- `defer ...` registers scenario-scoped cleanup in reverse order.

Useful environment variables in step bodies:

- `LAST_EXIT_CODE`
- `LAST_STDOUT`
- `LAST_STDERR`
- `DOC_STRING`
- `FAIL_MESSAGE`

## Authoring Heuristics

- If the project already has a "run command" step, reuse it.
- Prefer steps phrased in user language, not internal function names.
- Keep shell bodies straightforward and readable.
- Put setup in `Given`, actions in `When`, and assertions in `Then`.
- Use doc strings for exact multiline matches instead of brittle escaped strings.
- If a command is expected to fail, remember that `run` still succeeds; assert on `LAST_EXIT_CODE` or captured output.
- When creating temp directories or changing directories, clean up with `defer`.

## Validation Pattern

After edits:

1. Run `shellkin validate` on the feature root or changed feature file.
2. Run `shellkin test` on the narrowed target when practical.
3. If a step does not match, check the step text, header text, token names, and the active features/stepdefs roots.

## References

- Prefer local man pages for live Shellkin reference.
- For concrete feature and stepdef patterns, read [references/patterns.md](references/patterns.md).

Comments 0

Latest | Hot

Please login before commenting.

No comments yet. Be the first one!

shellkin

Directory Structure

SKILL.md

Report

Notice