From 51a10f3aa1387e8255be7bb6fc2e63baccfd648d Mon Sep 17 00:00:00 2001 From: Aaron McHale Date: Sun, 9 Aug 2026 15:29:46 +0100 Subject: [PATCH] Add agent skills --- .../skills/cli-declaring-new-command/SKILL.md | 19 ++++++++ .../cli-providing-description-help/SKILL.md | 19 ++++++++ .../cli-writing-command-script/SKILL.md | 21 ++++++++ .agents/skills/tests-running-tests/SKILL.md | 18 +++++++ .../tests-writing-test-functions/SKILL.md | 48 +++++++++++++++++++ AGENTS.md | 23 +++++++++ CLAUDE.md | 1 + GEMINI.md | 1 + 8 files changed, 150 insertions(+) create mode 100644 .agents/skills/cli-declaring-new-command/SKILL.md create mode 100644 .agents/skills/cli-providing-description-help/SKILL.md create mode 100644 .agents/skills/cli-writing-command-script/SKILL.md create mode 100644 .agents/skills/tests-running-tests/SKILL.md create mode 100644 .agents/skills/tests-writing-test-functions/SKILL.md create mode 100644 AGENTS.md create mode 100644 CLAUDE.md create mode 100644 GEMINI.md diff --git a/.agents/skills/cli-declaring-new-command/SKILL.md b/.agents/skills/cli-declaring-new-command/SKILL.md new file mode 100644 index 0000000..a377b06 --- /dev/null +++ b/.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/.sh` file where `` 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. diff --git a/.agents/skills/cli-providing-description-help/SKILL.md b/.agents/skills/cli-providing-description-help/SKILL.md new file mode 100644 index 0000000..2ad0a1c --- /dev/null +++ b/.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/.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 `. +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 ` output. +3. Run ShellCheck on any changed shell scripts. +4. Run `./tests/run-tests.sh` from the repository root. diff --git a/.agents/skills/cli-writing-command-script/SKILL.md b/.agents/skills/cli-writing-command-script/SKILL.md new file mode 100644 index 0000000..19db0ac --- /dev/null +++ b/.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. diff --git a/.agents/skills/tests-running-tests/SKILL.md b/.agents/skills/tests-running-tests/SKILL.md new file mode 100644 index 0000000..02919c0 --- /dev/null +++ b/.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. diff --git a/.agents/skills/tests-writing-test-functions/SKILL.md b/.agents/skills/tests-writing-test-functions/SKILL.md new file mode 100644 index 0000000..0cc9768 --- /dev/null +++ b/.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. diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..da441d0 --- /dev/null +++ b/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. diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 0000000..43c994c --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1 @@ +@AGENTS.md diff --git a/GEMINI.md b/GEMINI.md new file mode 100644 index 0000000..43c994c --- /dev/null +++ b/GEMINI.md @@ -0,0 +1 @@ +@AGENTS.md