Add agent skills

.agents/skills/cli-declaring-new-command/SKILL.md

@@ -0,0 +1,19 @@
+---
+name: cli-declaring-new-command
+description: Use this skill when creating a new CLI command script in the commands directory and register it with cli.sh. Use this skill when adding subcommands that should be discovered automatically by the wrapper.
+compatibility: Requires Bash and local repository access.
+---
+
+Refer to `docs/CLI.md` under "Declaring a new command" for authoritative guidance.
+
+Steps:
+1. Create a new `commands/<command>.sh` file where `<command>` is the command name.
+2. Ensure the file ends in `.sh` and does not need to be executable.
+3. Keep the implementation procedural: the file will be sourced directly by `cli.sh`.
+4. Do not add help or usage logic inside the script; use a `.help.txt` file instead.
+5. Use the `cli-writing-command-script` skill to implement the command logic and the `cli-providing-description-help` skill to add help text.
+
+Verification:
+1. Verify the new command is discovered by `cli.sh` and `cli.sh list`.
+2. Run ShellCheck on any changed shell scripts.
+3. Run `./tests/run-tests.sh` from the repository root.

.agents/skills/cli-providing-description-help/SKILL.md

@@ -0,0 +1,19 @@
+---
+name: cli-providing-description-help
+description: Use this skill when providing command descriptions and help content using `.help.txt` files so cli.sh can display listings and help output.
+compatibility: Requires Bash and local repository access.
+---
+
+Refer to `docs/CLI.md` under "Providing a description and help information" for authoritative guidance.
+
+Instructions:
+1. Create `commands/<command>.help.txt` alongside the command script.
+2. Keep the first line concise and descriptive; it will be used as the command description in `cli.sh list` output.
+3. The complete contents of the `.help.txt` file are displayed by `cli.sh help <command>`.
+4. Keep help content separate from the command script itself.
+
+Verification:
+1. Verify that the first line of the `.help.txt` file is displayed in `cli.sh list` output.
+2. Verify that the complete contents of the `.help.txt` file are displayed in `cli.sh help <command>` output.
+3. Run ShellCheck on any changed shell scripts.
+4. Run `./tests/run-tests.sh` from the repository root.

.agents/skills/cli-writing-command-script/SKILL.md

@@ -0,0 +1,21 @@
+---
+name: cli-writing-command-script
+description: Use this skill when writing a command script, while following repository conventions for shell scripts and helper function usage.
+compatibility: Requires Bash and local repository access.
+---
+
+Refer to `docs/CLI.md` under "Writing the command script" for authoritative guidance.
+
+Key expectations:
+- Start each command script with `#!/usr/bin/env bash`.
+- Command scripts do not need to be executable; they will be sourced by `cli.sh`.
+- Avoid placing usage or help text inside the command script.
+- Use `$CLIROOT` for the CLI script directory and `$CMDROOT` for the command script directory.
+- Use `$CMD` to identify the current command name.
+- Use `command_exists` to check whether another command exists, when needed.
+- Use the helper functions `error`, `warning`, and `success` for consistent output.
+- Keep command scripts procedural, exiting early when errors occur.
+
+Verification:
+1. Run ShellCheck on any changed shell scripts.
+2. Run `./tests/run-tests.sh` from the repository root.

.agents/skills/tests-running-tests/SKILL.md

@@ -0,0 +1,18 @@
+---
+name: tests-running-tests
+description: Use this skill when running the repository test suite using the test runner to verify changes and catch regressions.
+compatibility: Requires Bash and local repository access.
+---
+
+Refer to `docs/Tests.md` under "Running tests" for authoritative guidance.
+
+Instructions:
+- Run the test runner from the repository root using `./tests/run-tests.sh`.
+- The runner finds shell scripts in `./tests` beginning with `test-` and ending in `.sh`.
+- Each test file is sourced in a subshell and functions beginning with `test_` are executed.
+- Verify proposed changes by running the tests locally before finalizing them.
+
+Verification:
+1. Run shellcheck on any changed shell scripts.
+2. Ensure that all test pass.
+3. Fix any failures before considering the change complete.

.agents/skills/tests-writing-test-functions/SKILL.md

@@ -0,0 +1,48 @@
+---
+name: tests-writing-test-functions
+description: Use this skill when writing Bash test functions that are automatically discovered by the repository test runner and follow the required return conventions.
+compatibility: Requires Bash and local repository access.
+---
+
+Refer to `docs/Tests.md` under "Writing test functions" for authoritative guidance.
+
+Instructions:
+- Always create test functions in files beginning with `test-` and ending in `.sh` inside the `./tests` directory.
+- Test file do not need to be executable; they will be sourced by the test runner.
+- Name test functions starting with `test_`.
+- Do not call `setup` or `teardown` directly from test functions.
+- Use `setup` to create files and folders required for tests and for any variables which should be used by multiple test functions.
+- Use `return 0` for success and `return 1` for failure.
+- Write code procedurally inside test functions and always return early when errors occur; do not use subshells or pipelines that would prevent returning the correct exit code.
+- Do not use `exit` inside test functions.
+- Use the `$TEST_DIR` variable when referencing paths in tests.
+- Ensure cleanup is performed in `teardown` function when necessary.
+
+Example test file:
+```Bash
+# Example setup function
+setup() {
+  echo 'echo "Test command executed"' > "$TEST_DIR/../commands/test-cmd.sh"
+}
+
+# Example test function
+test_cli_output_for_test_cmd() {
+  echo "Testing cli.sh output for our test command"
+  cd ..
+  if [[ "$(./cli.sh)" != *"test-cmd"* ]]; then
+    echo "FAIL: Test command test-cmd not found in cli.sh output."
+    return 1
+  fi
+  cd "$TEST_DIR" || { echo "Failed to cd back to tests directory"; return 1; }
+}
+
+# Example teardown function
+teardown() {
+  rm "$TEST_DIR/../commands/test-cmd.sh" || true
+}
+```
+
+Verification:
+1. Run shellcheck on any changed shell scripts.
+2. Run `./tests/run-tests.sh` from the repository root, ensure that the test functions are shown in the output and the tests pass.
+3. Fix any failures before considering the change complete.

AGENTS.md

@@ -0,0 +1,23 @@
+# AGENTS
+
+This repository exposes its agent skills under `.agents/skills/`.
+Agents should use those skill definitions instead of relying on local heuristics or separate guidance.
+
+## Use these skills
+
+- `.agents/skills/cli-declaring-new-command`
+- `.agents/skills/cli-writing-command-script`
+- `.agents/skills/cli-providing-description-help`
+- `.agents/skills/tests-running-tests`
+- `.agents/skills/tests-structure-of-a-test-file`
+- `.agents/skills/tests-writing-test-functions`
+- `.agents/skills/tests-examples`
+
+## Required workflow
+
+After any code or documentation change, run:
+
+1. ShellCheck on the changed shell scripts.
+2. `./tests/run-tests.sh`
+
+If either check fails, fix the issues before considering the change complete.

CLAUDE.md

@@ -0,0 +1 @@
+@AGENTS.md

GEMINI.md

@@ -0,0 +1 @@
+@AGENTS.md