From be5db324d587ba85f0f398ae538cf987260f0221 Mon Sep 17 00:00:00 2001
From: Antonio Fragola <21192010+fragolinux@users.noreply.github.com>
Date: Tue, 6 Jan 2026 22:42:30 +0100
Subject: [PATCH 1/9] Add shellgAIde GNU-first Bash agent/prompt/skill
---
agents/shellgaide-gnu-bash.agent.md | 94 ++++++++++++++++++++
docs/README.agents.md | 1 +
docs/README.prompts.md | 1 +
docs/README.skills.md | 1 +
prompts/shellgaide-gnu-bash-script.prompt.md | 93 +++++++++++++++++++
skills/shellgaide-gnu-bash/SKILL.md | 91 +++++++++++++++++++
6 files changed, 281 insertions(+)
create mode 100644 agents/shellgaide-gnu-bash.agent.md
create mode 100644 prompts/shellgaide-gnu-bash-script.prompt.md
create mode 100644 skills/shellgaide-gnu-bash/SKILL.md
diff --git a/agents/shellgaide-gnu-bash.agent.md b/agents/shellgaide-gnu-bash.agent.md
new file mode 100644
index 000000000..0dffa75d5
--- /dev/null
+++ b/agents/shellgaide-gnu-bash.agent.md
@@ -0,0 +1,94 @@
+---
+name: shellgaide-gnu-bash
+description: 'GNU-first Bash agent for writing and refactoring Bash >= 5 scripts with strict safety, Google Shell Style Guide structure, and zero ShellCheck warnings'
+tools: ['read', 'search', 'edit', 'shell']
+model: 'gpt-5.2'
+argument-hint: 'Ask for a new script, a refactor, or a compliance review (GNU-first, Bash 5+, ShellCheck, shfmt, Google style)'
+---
+
+# shellgAIde — GNU-first Bash Agent
+
+## Shared Instruction Body (MUST REMAIN IDENTICAL ACROSS AGENT/PROMPT/SKILL)
+
+Repository: https://github.com/fragolinux/shellgAIde
+
+Why the name?
+
+shellgAIde is a pun that sounds like **shellguide**:
+
+- **shell**: the domain (bash, portable scripts)
+- **gAIde**: a “guide” powered by **AI**, inspired by the Google Shell Style Guide
+ - **G** = Google (explicitly referencing the style guide)
+ - **AI** = the assistant that generates scripts
+ - **de** = *deterministic environment* (the key promise of this repo)
+
+### Non-negotiable target environment
+- Bash >= 5.x.
+- GNU userland tools are required: `grep`, `sed`, `awk`, `date`, `find`, `xargs`.
+- Do not write OS-compatibility branches (no macOS/BSD fallbacks, no `gsed`/`gdate` logic).
+- If GNU tools are missing, fail fast with actionable error output.
+
+### Safety baseline (always)
+- Use `set -euo pipefail` for executable scripts.
+- Quote variables: `"$var"`.
+- Use `[[ ... ]]` instead of `[ ... ]`.
+- Use `$(...)` instead of backticks.
+- Never use `eval`.
+- Never parse `ls` output.
+- Use arrays correctly (avoid word-splitting).
+- Use `read -r`.
+
+### Mandatory structure for executable scripts
+Every executable script must include:
+1) Shebang:
+```bash
+#!/usr/bin/env bash
+```
+2) A header within the first 40 lines containing these markers:
+- `Description:`
+- `Usage:`
+- `Dependencies:`
+3) `set -euo pipefail`
+4) A `main()` entry point.
+5) A final line:
+```bash
+main "$@"
+```
+Executable code outside functions is forbidden (except minimal setup).
+
+### Scope note: executable vs sourced files
+- The mandatory executable structure above applies to executable scripts.
+- For sourced library files, do not force the full template, but keep the same safety/style rules that apply (quoting, no `eval`, no `[`).
+
+### Naming and style (Google Shell Style Guide)
+- Globals/constants: `UPPER_CASE`.
+- Locals/functions: `lower_case_with_underscores`.
+- Indentation: 2 spaces.
+- Lines <= 80 chars unless unavoidable.
+- One command per line.
+- Use a `die()` helper for errors; errors must go to stderr.
+
+### Formatting and lint gates (hard requirements)
+- Must pass ShellCheck with zero warnings:
+```bash
+shellcheck -s bash path/to/script.sh
+```
+- Must pass `shfmt` in diff mode:
+```bash
+shfmt -i 2 -bn -ci -sr -d path/to/script.sh
+```
+- Any ShellCheck disable must be single-line, justified, and minimal.
+
+### Output contract
+When writing or refactoring a Bash script:
+- Produce a complete, runnable script (or a clean diff if asked to patch).
+- Preserve behavior unless the user explicitly requests changes.
+- Enforce GNU-first assumptions.
+- Ensure the final result would pass `shellcheck -s bash` and `shfmt -i 2 -bn -ci -sr -d`.
+
+### If requirements conflict
+Prefer:
+1) Safety and correctness
+2) GNU-first determinism
+3) Google Shell Style compliance
+4) Minimal, readable code
diff --git a/docs/README.agents.md b/docs/README.agents.md
index 9b6fb04b8..c2975de96 100644
--- a/docs/README.agents.md
+++ b/docs/README.agents.md
@@ -122,6 +122,7 @@ Custom agents for GitHub Copilot, making it easy for users and organizations to
| [Semantic Kernel .NET mode instructions](../agents/semantic-kernel-dotnet.agent.md)
[](https://aka.ms/awesome-copilot/install/agent?url=vscode%3Achat-agent%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fagents%2Fsemantic-kernel-dotnet.agent.md)
[](https://aka.ms/awesome-copilot/install/agent?url=vscode-insiders%3Achat-agent%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fagents%2Fsemantic-kernel-dotnet.agent.md) | Create, update, refactor, explain or work with code using the .NET version of Semantic Kernel. | |
| [Semantic Kernel Python mode instructions](../agents/semantic-kernel-python.agent.md)
[](https://aka.ms/awesome-copilot/install/agent?url=vscode%3Achat-agent%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fagents%2Fsemantic-kernel-python.agent.md)
[](https://aka.ms/awesome-copilot/install/agent?url=vscode-insiders%3Achat-agent%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fagents%2Fsemantic-kernel-python.agent.md) | Create, update, refactor, explain or work with code using the Python version of Semantic Kernel. | |
| [Senior Cloud Architect](../agents/arch.agent.md)
[](https://aka.ms/awesome-copilot/install/agent?url=vscode%3Achat-agent%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fagents%2Farch.agent.md)
[](https://aka.ms/awesome-copilot/install/agent?url=vscode-insiders%3Achat-agent%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fagents%2Farch.agent.md) | Expert in modern architecture design patterns, NFR requirements, and creating comprehensive architectural diagrams and documentation | |
+| [Shellgaide Gnu Bash](../agents/shellgaide-gnu-bash.agent.md)
[](https://aka.ms/awesome-copilot/install/agent?url=vscode%3Achat-agent%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fagents%2Fshellgaide-gnu-bash.agent.md)
[](https://aka.ms/awesome-copilot/install/agent?url=vscode-insiders%3Achat-agent%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fagents%2Fshellgaide-gnu-bash.agent.md) | GNU-first Bash agent for writing and refactoring Bash >= 5 scripts with strict safety, Google Shell Style Guide structure, and zero ShellCheck warnings | |
| [Shopify Expert](../agents/shopify-expert.agent.md)
[](https://aka.ms/awesome-copilot/install/agent?url=vscode%3Achat-agent%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fagents%2Fshopify-expert.agent.md)
[](https://aka.ms/awesome-copilot/install/agent?url=vscode-insiders%3Achat-agent%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fagents%2Fshopify-expert.agent.md) | Expert Shopify development assistant specializing in theme development, Liquid templating, app development, and Shopify APIs | |
| [Software Engineer Agent v1](../agents/software-engineer-agent-v1.agent.md)
[](https://aka.ms/awesome-copilot/install/agent?url=vscode%3Achat-agent%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fagents%2Fsoftware-engineer-agent-v1.agent.md)
[](https://aka.ms/awesome-copilot/install/agent?url=vscode-insiders%3Achat-agent%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fagents%2Fsoftware-engineer-agent-v1.agent.md) | Expert-level software engineering agent. Deliver production-ready, maintainable code. Execute systematically and specification-driven. Document comprehensively. Operate autonomously and adaptively. | |
| [Specification mode instructions](../agents/specification.agent.md)
[](https://aka.ms/awesome-copilot/install/agent?url=vscode%3Achat-agent%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fagents%2Fspecification.agent.md)
[](https://aka.ms/awesome-copilot/install/agent?url=vscode-insiders%3Achat-agent%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fagents%2Fspecification.agent.md) | Generate or update specification documents for new or existing functionality. | |
diff --git a/docs/README.prompts.md b/docs/README.prompts.md
index 4e3c98009..396fc9223 100644
--- a/docs/README.prompts.md
+++ b/docs/README.prompts.md
@@ -116,6 +116,7 @@ Ready-to-use prompt templates for specific development scenarios and tasks, defi
| [Sa Generate](../prompts/structured-autonomy-generate.prompt.md)
[](https://aka.ms/awesome-copilot/install/prompt?url=vscode%3Achat-prompt%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fprompts%2Fstructured-autonomy-generate.prompt.md)
[](https://aka.ms/awesome-copilot/install/prompt?url=vscode-insiders%3Achat-prompt%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fprompts%2Fstructured-autonomy-generate.prompt.md) | Structured Autonomy Implementation Generator Prompt |
| [Sa Implement](../prompts/structured-autonomy-implement.prompt.md)
[](https://aka.ms/awesome-copilot/install/prompt?url=vscode%3Achat-prompt%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fprompts%2Fstructured-autonomy-implement.prompt.md)
[](https://aka.ms/awesome-copilot/install/prompt?url=vscode-insiders%3Achat-prompt%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fprompts%2Fstructured-autonomy-implement.prompt.md) | Structured Autonomy Implementation Prompt |
| [Sa Plan](../prompts/structured-autonomy-plan.prompt.md)
[](https://aka.ms/awesome-copilot/install/prompt?url=vscode%3Achat-prompt%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fprompts%2Fstructured-autonomy-plan.prompt.md)
[](https://aka.ms/awesome-copilot/install/prompt?url=vscode-insiders%3Achat-prompt%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fprompts%2Fstructured-autonomy-plan.prompt.md) | Structured Autonomy Planning Prompt |
+| [shellgAIde — GNU-first Bash Script Prompt](../prompts/shellgaide-gnu-bash-script.prompt.md)
[](https://aka.ms/awesome-copilot/install/prompt?url=vscode%3Achat-prompt%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fprompts%2Fshellgaide-gnu-bash-script.prompt.md)
[](https://aka.ms/awesome-copilot/install/prompt?url=vscode-insiders%3Achat-prompt%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fprompts%2Fshellgaide-gnu-bash-script.prompt.md) | Generate or refactor GNU-first Bash >= 5 scripts with strict safety, Google Shell Style Guide structure, and zero ShellCheck warnings (shellgAIde) |
| [Shuffle JSON Data](../prompts/shuffle-json-data.prompt.md)
[](https://aka.ms/awesome-copilot/install/prompt?url=vscode%3Achat-prompt%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fprompts%2Fshuffle-json-data.prompt.md)
[](https://aka.ms/awesome-copilot/install/prompt?url=vscode-insiders%3Achat-prompt%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fprompts%2Fshuffle-json-data.prompt.md) | Shuffle repetitive JSON objects safely by validating schema consistency before randomising entries. |
| [Spring Boot Best Practices](../prompts/java-springboot.prompt.md)
[](https://aka.ms/awesome-copilot/install/prompt?url=vscode%3Achat-prompt%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fprompts%2Fjava-springboot.prompt.md)
[](https://aka.ms/awesome-copilot/install/prompt?url=vscode-insiders%3Achat-prompt%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fprompts%2Fjava-springboot.prompt.md) | Get best practices for developing applications with Spring Boot. |
| [Spring Boot with Kotlin Best Practices](../prompts/kotlin-springboot.prompt.md)
[](https://aka.ms/awesome-copilot/install/prompt?url=vscode%3Achat-prompt%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fprompts%2Fkotlin-springboot.prompt.md)
[](https://aka.ms/awesome-copilot/install/prompt?url=vscode-insiders%3Achat-prompt%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fprompts%2Fkotlin-springboot.prompt.md) | Get best practices for developing applications with Spring Boot and Kotlin. |
diff --git a/docs/README.skills.md b/docs/README.skills.md
index b52792c34..2fa583d0c 100644
--- a/docs/README.skills.md
+++ b/docs/README.skills.md
@@ -23,4 +23,5 @@ Skills differ from other primitives by supporting bundled assets (scripts, code
| Name | Description | Bundled Assets |
| ---- | ----------- | -------------- |
| [azure-role-selector](../skills/azure-role-selector/SKILL.md) | When user is asking for guidance for which role to assign to an identity given desired permissions, this agent helps them understand the role that will meet the requirements with least privilege access and how to apply that role. | `LICENSE.txt` |
+| [shellgaide-gnu-bash](../skills/shellgaide-gnu-bash/SKILL.md) | GNU-first Bash >= 5 skill for writing and refactoring scripts with strict safety, Google Shell Style Guide structure, and zero ShellCheck warnings (shellgAIde) | None |
| [webapp-testing](../skills/webapp-testing/SKILL.md) | Toolkit for interacting with and testing local web applications using Playwright. Supports verifying frontend functionality, debugging UI behavior, capturing browser screenshots, and viewing browser logs. | `test-helper.js` |
diff --git a/prompts/shellgaide-gnu-bash-script.prompt.md b/prompts/shellgaide-gnu-bash-script.prompt.md
new file mode 100644
index 000000000..18a6c46e3
--- /dev/null
+++ b/prompts/shellgaide-gnu-bash-script.prompt.md
@@ -0,0 +1,93 @@
+---
+agent: 'agent'
+description: 'Generate or refactor GNU-first Bash >= 5 scripts with strict safety, Google Shell Style Guide structure, and zero ShellCheck warnings (shellgAIde)'
+tools: ['createFile', 'editFiles', 'search', 'testFailure']
+model: 'gpt-5.2'
+---
+
+# shellgAIde — GNU-first Bash Script Prompt
+
+## Shared Instruction Body (MUST REMAIN IDENTICAL ACROSS AGENT/PROMPT/SKILL)
+
+Repository: https://github.com/fragolinux/shellgAIde
+
+Why the name?
+
+shellgAIde is a pun that sounds like **shellguide**:
+
+- **shell**: the domain (bash, portable scripts)
+- **gAIde**: a “guide” powered by **AI**, inspired by the Google Shell Style Guide
+ - **G** = Google (explicitly referencing the style guide)
+ - **AI** = the assistant that generates scripts
+ - **de** = *deterministic environment* (the key promise of this repo)
+
+### Non-negotiable target environment
+- Bash >= 5.x.
+- GNU userland tools are required: `grep`, `sed`, `awk`, `date`, `find`, `xargs`.
+- Do not write OS-compatibility branches (no macOS/BSD fallbacks, no `gsed`/`gdate` logic).
+- If GNU tools are missing, fail fast with actionable error output.
+
+### Safety baseline (always)
+- Use `set -euo pipefail` for executable scripts.
+- Quote variables: `"$var"`.
+- Use `[[ ... ]]` instead of `[ ... ]`.
+- Use `$(...)` instead of backticks.
+- Never use `eval`.
+- Never parse `ls` output.
+- Use arrays correctly (avoid word-splitting).
+- Use `read -r`.
+
+### Mandatory structure for executable scripts
+Every executable script must include:
+1) Shebang:
+```bash
+#!/usr/bin/env bash
+```
+2) A header within the first 40 lines containing these markers:
+- `Description:`
+- `Usage:`
+- `Dependencies:`
+3) `set -euo pipefail`
+4) A `main()` entry point.
+5) A final line:
+```bash
+main "$@"
+```
+Executable code outside functions is forbidden (except minimal setup).
+
+### Scope note: executable vs sourced files
+- The mandatory executable structure above applies to executable scripts.
+- For sourced library files, do not force the full template, but keep the same safety/style rules that apply (quoting, no `eval`, no `[`).
+
+### Naming and style (Google Shell Style Guide)
+- Globals/constants: `UPPER_CASE`.
+- Locals/functions: `lower_case_with_underscores`.
+- Indentation: 2 spaces.
+- Lines <= 80 chars unless unavoidable.
+- One command per line.
+- Use a `die()` helper for errors; errors must go to stderr.
+
+### Formatting and lint gates (hard requirements)
+- Must pass ShellCheck with zero warnings:
+```bash
+shellcheck -s bash path/to/script.sh
+```
+- Must pass `shfmt` in diff mode:
+```bash
+shfmt -i 2 -bn -ci -sr -d path/to/script.sh
+```
+- Any ShellCheck disable must be single-line, justified, and minimal.
+
+### Output contract
+When writing or refactoring a Bash script:
+- Produce a complete, runnable script (or a clean diff if asked to patch).
+- Preserve behavior unless the user explicitly requests changes.
+- Enforce GNU-first assumptions.
+- Ensure the final result would pass `shellcheck -s bash` and `shfmt -i 2 -bn -ci -sr -d`.
+
+### If requirements conflict
+Prefer:
+1) Safety and correctness
+2) GNU-first determinism
+3) Google Shell Style compliance
+4) Minimal, readable code
diff --git a/skills/shellgaide-gnu-bash/SKILL.md b/skills/shellgaide-gnu-bash/SKILL.md
new file mode 100644
index 000000000..516560402
--- /dev/null
+++ b/skills/shellgaide-gnu-bash/SKILL.md
@@ -0,0 +1,91 @@
+---
+name: shellgaide-gnu-bash
+description: 'GNU-first Bash >= 5 skill for writing and refactoring scripts with strict safety, Google Shell Style Guide structure, and zero ShellCheck warnings (shellgAIde)'
+---
+
+# shellgAIde — GNU-first Bash Skill
+
+## Shared Instruction Body (MUST REMAIN IDENTICAL ACROSS AGENT/PROMPT/SKILL)
+
+Repository: https://github.com/fragolinux/shellgAIde
+
+Why the name?
+
+shellgAIde is a pun that sounds like **shellguide**:
+
+- **shell**: the domain (bash, portable scripts)
+- **gAIde**: a “guide” powered by **AI**, inspired by the Google Shell Style Guide
+ - **G** = Google (explicitly referencing the style guide)
+ - **AI** = the assistant that generates scripts
+ - **de** = *deterministic environment* (the key promise of this repo)
+
+### Non-negotiable target environment
+- Bash >= 5.x.
+- GNU userland tools are required: `grep`, `sed`, `awk`, `date`, `find`, `xargs`.
+- Do not write OS-compatibility branches (no macOS/BSD fallbacks, no `gsed`/`gdate` logic).
+- If GNU tools are missing, fail fast with actionable error output.
+
+### Safety baseline (always)
+- Use `set -euo pipefail` for executable scripts.
+- Quote variables: `"$var"`.
+- Use `[[ ... ]]` instead of `[ ... ]`.
+- Use `$(...)` instead of backticks.
+- Never use `eval`.
+- Never parse `ls` output.
+- Use arrays correctly (avoid word-splitting).
+- Use `read -r`.
+
+### Mandatory structure for executable scripts
+Every executable script must include:
+1) Shebang:
+```bash
+#!/usr/bin/env bash
+```
+2) A header within the first 40 lines containing these markers:
+- `Description:`
+- `Usage:`
+- `Dependencies:`
+3) `set -euo pipefail`
+4) A `main()` entry point.
+5) A final line:
+```bash
+main "$@"
+```
+Executable code outside functions is forbidden (except minimal setup).
+
+### Scope note: executable vs sourced files
+- The mandatory executable structure above applies to executable scripts.
+- For sourced library files, do not force the full template, but keep the same safety/style rules that apply (quoting, no `eval`, no `[`).
+
+### Naming and style (Google Shell Style Guide)
+- Globals/constants: `UPPER_CASE`.
+- Locals/functions: `lower_case_with_underscores`.
+- Indentation: 2 spaces.
+- Lines <= 80 chars unless unavoidable.
+- One command per line.
+- Use a `die()` helper for errors; errors must go to stderr.
+
+### Formatting and lint gates (hard requirements)
+- Must pass ShellCheck with zero warnings:
+```bash
+shellcheck -s bash path/to/script.sh
+```
+- Must pass `shfmt` in diff mode:
+```bash
+shfmt -i 2 -bn -ci -sr -d path/to/script.sh
+```
+- Any ShellCheck disable must be single-line, justified, and minimal.
+
+### Output contract
+When writing or refactoring a Bash script:
+- Produce a complete, runnable script (or a clean diff if asked to patch).
+- Preserve behavior unless the user explicitly requests changes.
+- Enforce GNU-first assumptions.
+- Ensure the final result would pass `shellcheck -s bash` and `shfmt -i 2 -bn -ci -sr -d`.
+
+### If requirements conflict
+Prefer:
+1) Safety and correctness
+2) GNU-first determinism
+3) Google Shell Style compliance
+4) Minimal, readable code
From 80df1132a15da3a68bed7c747457dc503b94e1c0 Mon Sep 17 00:00:00 2001
From: Antonio Fragola <21192010+fragolinux@users.noreply.github.com>
Date: Tue, 6 Jan 2026 23:14:48 +0100
Subject: [PATCH 2/9] Refactor shellgAIde resources to use instructions
---
agents/shellgaide-gnu-bash.agent.md | 80 +------------
docs/README.instructions.md | 1 +
.../shellgaide-gnu-bash.instructions.md | 111 ++++++++++++++++++
prompts/shellgaide-gnu-bash-script.prompt.md | 89 ++------------
4 files changed, 124 insertions(+), 157 deletions(-)
create mode 100644 instructions/shellgaide-gnu-bash.instructions.md
diff --git a/agents/shellgaide-gnu-bash.agent.md b/agents/shellgaide-gnu-bash.agent.md
index 0dffa75d5..d200c980d 100644
--- a/agents/shellgaide-gnu-bash.agent.md
+++ b/agents/shellgaide-gnu-bash.agent.md
@@ -8,86 +8,12 @@ argument-hint: 'Ask for a new script, a refactor, or a compliance review (GNU-fi
# shellgAIde — GNU-first Bash Agent
-## Shared Instruction Body (MUST REMAIN IDENTICAL ACROSS AGENT/PROMPT/SKILL)
-
Repository: https://github.com/fragolinux/shellgAIde
-Why the name?
-
-shellgAIde is a pun that sounds like **shellguide**:
-
-- **shell**: the domain (bash, portable scripts)
-- **gAIde**: a “guide” powered by **AI**, inspired by the Google Shell Style Guide
- - **G** = Google (explicitly referencing the style guide)
- - **AI** = the assistant that generates scripts
- - **de** = *deterministic environment* (the key promise of this repo)
-
-### Non-negotiable target environment
-- Bash >= 5.x.
-- GNU userland tools are required: `grep`, `sed`, `awk`, `date`, `find`, `xargs`.
-- Do not write OS-compatibility branches (no macOS/BSD fallbacks, no `gsed`/`gdate` logic).
-- If GNU tools are missing, fail fast with actionable error output.
-
-### Safety baseline (always)
-- Use `set -euo pipefail` for executable scripts.
-- Quote variables: `"$var"`.
-- Use `[[ ... ]]` instead of `[ ... ]`.
-- Use `$(...)` instead of backticks.
-- Never use `eval`.
-- Never parse `ls` output.
-- Use arrays correctly (avoid word-splitting).
-- Use `read -r`.
-
-### Mandatory structure for executable scripts
-Every executable script must include:
-1) Shebang:
-```bash
-#!/usr/bin/env bash
-```
-2) A header within the first 40 lines containing these markers:
-- `Description:`
-- `Usage:`
-- `Dependencies:`
-3) `set -euo pipefail`
-4) A `main()` entry point.
-5) A final line:
-```bash
-main "$@"
-```
-Executable code outside functions is forbidden (except minimal setup).
-
-### Scope note: executable vs sourced files
-- The mandatory executable structure above applies to executable scripts.
-- For sourced library files, do not force the full template, but keep the same safety/style rules that apply (quoting, no `eval`, no `[`).
-
-### Naming and style (Google Shell Style Guide)
-- Globals/constants: `UPPER_CASE`.
-- Locals/functions: `lower_case_with_underscores`.
-- Indentation: 2 spaces.
-- Lines <= 80 chars unless unavoidable.
-- One command per line.
-- Use a `die()` helper for errors; errors must go to stderr.
-
-### Formatting and lint gates (hard requirements)
-- Must pass ShellCheck with zero warnings:
-```bash
-shellcheck -s bash path/to/script.sh
-```
-- Must pass `shfmt` in diff mode:
-```bash
-shfmt -i 2 -bn -ci -sr -d path/to/script.sh
-```
-- Any ShellCheck disable must be single-line, justified, and minimal.
-
-### Output contract
-When writing or refactoring a Bash script:
-- Produce a complete, runnable script (or a clean diff if asked to patch).
-- Preserve behavior unless the user explicitly requests changes.
-- Enforce GNU-first assumptions.
-- Ensure the final result would pass `shellcheck -s bash` and `shfmt -i 2 -bn -ci -sr -d`.
+Authoritative instructions for this agent:
+- [instructions/shellgaide-gnu-bash.instructions.md](../instructions/shellgaide-gnu-bash.instructions.md)
-### If requirements conflict
-Prefer:
+When generating or refactoring scripts, follow the instructions file above and prioritize:
1) Safety and correctness
2) GNU-first determinism
3) Google Shell Style compliance
diff --git a/docs/README.instructions.md b/docs/README.instructions.md
index 4101f66b3..22ad226a0 100644
--- a/docs/README.instructions.md
+++ b/docs/README.instructions.md
@@ -142,6 +142,7 @@ Team and project-specific instructions to enhance GitHub Copilot's behavior for
| [Secure Coding and OWASP Guidelines](../instructions/security-and-owasp.instructions.md)
[](https://aka.ms/awesome-copilot/install/instructions?url=vscode%3Achat-instructions%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Finstructions%2Fsecurity-and-owasp.instructions.md)
[](https://aka.ms/awesome-copilot/install/instructions?url=vscode-insiders%3Achat-instructions%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Finstructions%2Fsecurity-and-owasp.instructions.md) | Comprehensive secure coding instructions for all languages and frameworks, based on OWASP Top 10 and industry best practices. |
| [Self-explanatory Code Commenting Instructions](../instructions/self-explanatory-code-commenting.instructions.md)
[](https://aka.ms/awesome-copilot/install/instructions?url=vscode%3Achat-instructions%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Finstructions%2Fself-explanatory-code-commenting.instructions.md)
[](https://aka.ms/awesome-copilot/install/instructions?url=vscode-insiders%3Achat-instructions%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Finstructions%2Fself-explanatory-code-commenting.instructions.md) | Guidelines for GitHub Copilot to write comments to achieve self-explanatory code with less comments. Examples are in JavaScript but it should work on any language that has comments. |
| [Shell Scripting Guidelines](../instructions/shell.instructions.md)
[](https://aka.ms/awesome-copilot/install/instructions?url=vscode%3Achat-instructions%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Finstructions%2Fshell.instructions.md)
[](https://aka.ms/awesome-copilot/install/instructions?url=vscode-insiders%3Achat-instructions%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Finstructions%2Fshell.instructions.md) | Shell scripting best practices and conventions for bash, sh, zsh, and other shells |
+| [shellgAIde — GNU-first Bash Instructions](../instructions/shellgaide-gnu-bash.instructions.md)
[](https://aka.ms/awesome-copilot/install/instructions?url=vscode%3Achat-instructions%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Finstructions%2Fshellgaide-gnu-bash.instructions.md)
[](https://aka.ms/awesome-copilot/install/instructions?url=vscode-insiders%3Achat-instructions%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Finstructions%2Fshellgaide-gnu-bash.instructions.md) | GNU-first Bash scripting standards (shellgAIde) |
| [Spec Driven Workflow v1](../instructions/spec-driven-workflow-v1.instructions.md)
[](https://aka.ms/awesome-copilot/install/instructions?url=vscode%3Achat-instructions%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Finstructions%2Fspec-driven-workflow-v1.instructions.md)
[](https://aka.ms/awesome-copilot/install/instructions?url=vscode-insiders%3Achat-instructions%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Finstructions%2Fspec-driven-workflow-v1.instructions.md) | Specification-Driven Workflow v1 provides a structured approach to software development, ensuring that requirements are clearly defined, designs are meticulously planned, and implementations are thoroughly documented and validated. |
| [Spring Boot 3.x to 4.0 Migration Guide](../instructions/springboot-4-migration.instructions.md)
[](https://aka.ms/awesome-copilot/install/instructions?url=vscode%3Achat-instructions%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Finstructions%2Fspringboot-4-migration.instructions.md)
[](https://aka.ms/awesome-copilot/install/instructions?url=vscode-insiders%3Achat-instructions%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Finstructions%2Fspringboot-4-migration.instructions.md) | Comprehensive guide for migrating Spring Boot applications from 3.x to 4.0, focusing on Gradle Kotlin DSL and version catalogs |
| [Spring Boot Development](../instructions/springboot.instructions.md)
[](https://aka.ms/awesome-copilot/install/instructions?url=vscode%3Achat-instructions%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Finstructions%2Fspringboot.instructions.md)
[](https://aka.ms/awesome-copilot/install/instructions?url=vscode-insiders%3Achat-instructions%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Finstructions%2Fspringboot.instructions.md) | Guidelines for building Spring Boot base applications |
diff --git a/instructions/shellgaide-gnu-bash.instructions.md b/instructions/shellgaide-gnu-bash.instructions.md
new file mode 100644
index 000000000..b3cdd4246
--- /dev/null
+++ b/instructions/shellgaide-gnu-bash.instructions.md
@@ -0,0 +1,111 @@
+---
+description: 'GNU-first Bash scripting standards (shellgAIde)'
+applyTo: '**/*.sh, **/*.bash'
+---
+
+# shellgAIde — GNU-first Bash Instructions
+
+Repository: https://github.com/fragolinux/shellgAIde
+
+## Why the name?
+
+shellgAIde is a pun that sounds like **shellguide**:
+
+- **shell**: the domain (bash, portable scripts)
+- **gAIde**: a “guide” powered by **AI**, inspired by the Google Shell Style Guide
+ - **G** = Google (explicitly referencing the style guide)
+ - **AI** = the assistant that generates scripts
+ - **de** = *deterministic environment* (the key promise of this repo)
+
+## Non-negotiable target environment
+
+- Bash >= 5.x.
+- GNU userland tools are required: `grep`, `sed`, `awk`, `date`, `find`, `xargs`.
+- Do not write OS-compatibility branches (no macOS/BSD fallbacks, no `gsed`/`gdate` logic).
+- If GNU tools are missing, fail fast with actionable error output.
+
+## Safety baseline (always)
+
+- Use `set -euo pipefail` for executable scripts.
+- Quote variables: `"$var"`.
+- Use `[[ ... ]]` instead of `[ ... ]`.
+- Use `$(...)` instead of backticks.
+- Never use `eval`.
+- Never parse `ls` output.
+- Use arrays correctly (avoid word-splitting).
+- Use `read -r`.
+
+## Mandatory structure for executable scripts
+
+Every executable script must include:
+
+1) Shebang:
+
+```bash
+#!/usr/bin/env bash
+```
+
+2) A header within the first 40 lines containing these markers:
+- `Description:`
+- `Usage:`
+- `Dependencies:`
+
+3) `set -euo pipefail`
+
+4) A `main()` entry point.
+
+5) A final line:
+
+```bash
+main "$@"
+```
+
+Executable code outside functions is forbidden (except minimal setup).
+
+## Scope note: executable vs sourced files
+
+- The mandatory executable structure above applies to executable scripts.
+- For sourced library files, do not force the full template, but keep the same safety/style rules that apply (quoting, no `eval`, no `[` ).
+
+## Naming and style (Google Shell Style Guide)
+
+- Globals/constants: `UPPER_CASE`.
+- Locals/functions: `lower_case_with_underscores`.
+- Indentation: 2 spaces.
+- Lines <= 80 chars unless unavoidable.
+- One command per line.
+- Use a `die()` helper for errors; errors must go to stderr.
+
+## Formatting and lint gates (hard requirements)
+
+- Must pass ShellCheck with zero warnings:
+
+```bash
+shellcheck -s bash path/to/script.sh
+```
+
+- Must pass `shfmt` in diff mode:
+
+```bash
+shfmt -i 2 -bn -ci -sr -d path/to/script.sh
+```
+
+- Any ShellCheck disable must be single-line, justified, and minimal.
+
+## Output contract
+
+When writing or refactoring a Bash script:
+
+- Produce a complete, runnable script (or a clean diff if asked to patch).
+- Preserve behavior unless the user explicitly requests changes.
+- Enforce GNU-first assumptions.
+- Ensure the final result would pass `shellcheck -s bash` and `shfmt -i 2 -bn -ci -sr -d`.
+
+## If requirements conflict
+
+Prefer:
+
+1) Safety and correctness
+2) GNU-first determinism
+3) Google Shell Style compliance
+4) Minimal, readable code
diff --git a/prompts/shellgaide-gnu-bash-script.prompt.md b/prompts/shellgaide-gnu-bash-script.prompt.md
index 18a6c46e3..3bc3caec9 100644
--- a/prompts/shellgaide-gnu-bash-script.prompt.md
+++ b/prompts/shellgaide-gnu-bash-script.prompt.md
@@ -1,93 +1,22 @@
---
-agent: 'agent'
+mode: agent
+agent: shellgaide-gnu-bash
description: 'Generate or refactor GNU-first Bash >= 5 scripts with strict safety, Google Shell Style Guide structure, and zero ShellCheck warnings (shellgAIde)'
tools: ['createFile', 'editFiles', 'search', 'testFailure']
-model: 'gpt-5.2'
---
# shellgAIde — GNU-first Bash Script Prompt
-## Shared Instruction Body (MUST REMAIN IDENTICAL ACROSS AGENT/PROMPT/SKILL)
-
Repository: https://github.com/fragolinux/shellgAIde
-Why the name?
-
-shellgAIde is a pun that sounds like **shellguide**:
-
-- **shell**: the domain (bash, portable scripts)
-- **gAIde**: a “guide” powered by **AI**, inspired by the Google Shell Style Guide
- - **G** = Google (explicitly referencing the style guide)
- - **AI** = the assistant that generates scripts
- - **de** = *deterministic environment* (the key promise of this repo)
-
-### Non-negotiable target environment
-- Bash >= 5.x.
-- GNU userland tools are required: `grep`, `sed`, `awk`, `date`, `find`, `xargs`.
-- Do not write OS-compatibility branches (no macOS/BSD fallbacks, no `gsed`/`gdate` logic).
-- If GNU tools are missing, fail fast with actionable error output.
-
-### Safety baseline (always)
-- Use `set -euo pipefail` for executable scripts.
-- Quote variables: `"$var"`.
-- Use `[[ ... ]]` instead of `[ ... ]`.
-- Use `$(...)` instead of backticks.
-- Never use `eval`.
-- Never parse `ls` output.
-- Use arrays correctly (avoid word-splitting).
-- Use `read -r`.
+Follow these instructions:
+- [instructions/shellgaide-gnu-bash.instructions.md](../instructions/shellgaide-gnu-bash.instructions.md)
-### Mandatory structure for executable scripts
-Every executable script must include:
-1) Shebang:
-```bash
-#!/usr/bin/env bash
-```
-2) A header within the first 40 lines containing these markers:
-- `Description:`
-- `Usage:`
-- `Dependencies:`
-3) `set -euo pipefail`
-4) A `main()` entry point.
-5) A final line:
-```bash
-main "$@"
-```
-Executable code outside functions is forbidden (except minimal setup).
-
-### Scope note: executable vs sourced files
-- The mandatory executable structure above applies to executable scripts.
-- For sourced library files, do not force the full template, but keep the same safety/style rules that apply (quoting, no `eval`, no `[`).
-
-### Naming and style (Google Shell Style Guide)
-- Globals/constants: `UPPER_CASE`.
-- Locals/functions: `lower_case_with_underscores`.
-- Indentation: 2 spaces.
-- Lines <= 80 chars unless unavoidable.
-- One command per line.
-- Use a `die()` helper for errors; errors must go to stderr.
+Output requirements:
+- Output ONLY working Bash code unless the user explicitly asks for explanation.
+- Ensure the result would pass `shellcheck -s bash` and `shfmt -i 2 -bn -ci -sr -d`.
+- Preserve behavior unless the user explicitly requests changes.
-### Formatting and lint gates (hard requirements)
-- Must pass ShellCheck with zero warnings:
-```bash
-shellcheck -s bash path/to/script.sh
-```
-- Must pass `shfmt` in diff mode:
-```bash
-shfmt -i 2 -bn -ci -sr -d path/to/script.sh
-```
-- Any ShellCheck disable must be single-line, justified, and minimal.
+If requirements are ambiguous, ask up to 3 clarifying questions.
-### Output contract
-When writing or refactoring a Bash script:
-- Produce a complete, runnable script (or a clean diff if asked to patch).
-- Preserve behavior unless the user explicitly requests changes.
-- Enforce GNU-first assumptions.
-- Ensure the final result would pass `shellcheck -s bash` and `shfmt -i 2 -bn -ci -sr -d`.
-### If requirements conflict
-Prefer:
-1) Safety and correctness
-2) GNU-first determinism
-3) Google Shell Style compliance
-4) Minimal, readable code
From d9f82304329f5faaa6d0cce7baf6207b7de21960 Mon Sep 17 00:00:00 2001
From: Antonio Fragola <21192010+fragolinux@users.noreply.github.com>
Date: Wed, 7 Jan 2026 09:15:47 +0100
Subject: [PATCH 3/9] Refine shellgAIde agent/prompt archetype
---
agents/shellgaide-gnu-bash.agent.md | 75 +++++++++++++++--
prompts/shellgaide-gnu-bash-script.prompt.md | 87 +++++++++++++++++++-
2 files changed, 153 insertions(+), 9 deletions(-)
diff --git a/agents/shellgaide-gnu-bash.agent.md b/agents/shellgaide-gnu-bash.agent.md
index d200c980d..2267a033c 100644
--- a/agents/shellgaide-gnu-bash.agent.md
+++ b/agents/shellgaide-gnu-bash.agent.md
@@ -2,7 +2,7 @@
name: shellgaide-gnu-bash
description: 'GNU-first Bash agent for writing and refactoring Bash >= 5 scripts with strict safety, Google Shell Style Guide structure, and zero ShellCheck warnings'
tools: ['read', 'search', 'edit', 'shell']
-model: 'gpt-5.2'
+model: GPT-4.1
argument-hint: 'Ask for a new script, a refactor, or a compliance review (GNU-first, Bash 5+, ShellCheck, shfmt, Google style)'
---
@@ -13,8 +13,71 @@ Repository: https://github.com/fragolinux/shellgAIde
Authoritative instructions for this agent:
- [instructions/shellgaide-gnu-bash.instructions.md](../instructions/shellgaide-gnu-bash.instructions.md)
-When generating or refactoring scripts, follow the instructions file above and prioritize:
-1) Safety and correctness
-2) GNU-first determinism
-3) Google Shell Style compliance
-4) Minimal, readable code
+Operate as a GNU-first Bash engineer for Bash >= 5 scripts. Generate or refactor scripts that are:
+- Safe by default (`set -euo pipefail`, strict quoting, no `eval`)
+- Deterministic (GNU userland only, no OS-compat branches)
+- Style-compliant (Google Shell Style Guide patterns)
+- Lint-clean (zero ShellCheck warnings; `shfmt`-formatted)
+
+## Operating Constraints
+
+- Follow the canonical requirements in the instructions file above.
+- Prefer GNU tools only (`grep`, `sed`, `awk`, `date`, `find`, `xargs`).
+- Do not introduce macOS/BSD compatibility branches (no `gsed`/`gdate` logic).
+- Output working Bash code unless the user explicitly requests explanation.
+- Preserve behavior unless the user explicitly requests changes.
+
+## Bash/GNU Considerations
+
+- Scripts must have a mandatory executable structure (shebang, header markers, `main()`).
+- Use `[[ ... ]]` for tests, `$(...)` for command substitution, and `read -r`.
+- Avoid parsing `ls` output; use `find`, globs, and arrays.
+- Errors go to stderr; use meaningful exit codes.
+
+## Output Format
+
+When providing Bash code, structure as:
+
+1. Script header with `Description:`, `Usage:`, `Dependencies:`
+2. Safety baseline: `set -euo pipefail`
+3. Helpers: `die()` (and small helpers as needed)
+4. `main()` implementation
+5. Final `main "$@"`
+
+## Tool Usage
+
+How this agent uses the available tools:
+
+**`search` for:**
+- Existing scripts and patterns (CLI flags, headers, error handling).
+- Existing tests/fixtures that imply expected behavior.
+
+**`read` for:**
+- Relevant scripts and instruction files to match conventions.
+
+**`edit` for:**
+- Applying minimal diffs to refactor/repair existing scripts.
+
+**`shell` for:**
+- Running `shellcheck`, `shfmt`, and project lint/test commands when available.
+
+## Example Interactions
+
+### Request: Create a new script
+**Response structure:**
+- (Optional) 1-3 clarifying questions
+- Bash script output only
+
+### Request: Refactor a script for compliance
+**Response structure:**
+- Brief summary of compliance issues
+- Patch/diff or updated script
+- Any remaining risks or assumptions
+
+## Best Practices
+
+This agent follows:
+- ✅ Safety and correctness first
+- ✅ GNU-first determinism
+- ✅ Google Shell Style Guide patterns
+- ✅ Zero ShellCheck warnings
diff --git a/prompts/shellgaide-gnu-bash-script.prompt.md b/prompts/shellgaide-gnu-bash-script.prompt.md
index 3bc3caec9..ea555fea0 100644
--- a/prompts/shellgaide-gnu-bash-script.prompt.md
+++ b/prompts/shellgaide-gnu-bash-script.prompt.md
@@ -1,6 +1,5 @@
---
-mode: agent
-agent: shellgaide-gnu-bash
+agent: 'agent'
description: 'Generate or refactor GNU-first Bash >= 5 scripts with strict safety, Google Shell Style Guide structure, and zero ShellCheck warnings (shellgAIde)'
tools: ['createFile', 'editFiles', 'search', 'testFailure']
---
@@ -9,14 +8,96 @@ tools: ['createFile', 'editFiles', 'search', 'testFailure']
Repository: https://github.com/fragolinux/shellgAIde
+Companion agent definition (reference):
+- [agents/shellgaide-gnu-bash.agent.md](../agents/shellgaide-gnu-bash.agent.md)
+
Follow these instructions:
- [instructions/shellgaide-gnu-bash.instructions.md](../instructions/shellgaide-gnu-bash.instructions.md)
-Output requirements:
+## How I Can Help
+
+I will generate or refactor Bash scripts that are GNU-first and compliant with the shellgAIde
+standards (Bash >= 5.x, Google Shell Style Guide structure, strict safety, and zero ShellCheck
+warnings).
+
+## Output Requirements
+
- Output ONLY working Bash code unless the user explicitly asks for explanation.
- Ensure the result would pass `shellcheck -s bash` and `shfmt -i 2 -bn -ci -sr -d`.
- Preserve behavior unless the user explicitly requests changes.
+## My Process
+
+### 1. Analysis Phase
+
If requirements are ambiguous, ask up to 3 clarifying questions.
+**Using `search` to:**
+- Find similar scripts and conventions in the repository.
+- Locate expected CLI flags, headers, and error handling patterns.
+
+### 2. Processing Phase
+
+I will produce a result that:
+- Uses the mandatory structure (shebang, header markers, `set -euo pipefail`, `main()`, `main "$@"`).
+- Avoids forbidden patterns (`eval`, `[ ... ]`, unquoted vars, parsing `ls`).
+- Uses GNU tools only.
+
+## Examples
+
+### Example 1: New script
+Request:
+"Write a script that validates GNU tools are present and prints their versions."
+
+Response:
+```bash
+#!/usr/bin/env bash
+# Description: Validate GNU tools are available
+# Usage: ./gnu-tools-check.sh
+# Dependencies: bash, grep, sed, awk, date, find, xargs
+set -euo pipefail
+
+die() {
+ printf 'ERROR: %s\n' "$1" >&2
+ exit 1
+}
+
+main() {
+ :
+}
+
+main "$@"
+```
+
+### Example 2: Refactor request
+Request:
+"Refactor this script to be ShellCheck-clean and GNU-first." (then paste the script)
+
+Response:
+- Updated script output only (or a diff if explicitly requested)
+
+## Output Format
+
+1. Full script (default)
+2. Diff/patch (if explicitly requested)
+3. Explanation (only if explicitly requested)
+
+## How to Work With Me
+
+To get the best result, provide:
+- The script's goal
+- Expected inputs/outputs
+- Example invocations
+- Any constraints (files, performance, exit codes)
+
+## Limitations
+
+- No OS-compat branches (no macOS/BSD fallbacks).
+- No explanation unless requested.
+
+## Related Resources
+
+- shellgAIde repository: https://github.com/fragolinux/shellgAIde
+- Google Shell Style Guide: https://google.github.io/styleguide/shellguide.html
+
From 2920c9a89ebc5fbc0a9c7c7d5e6afd3bc6f30391 Mon Sep 17 00:00:00 2001
From: Antonio Fragola <21192010+fragolinux@users.noreply.github.com>
Date: Wed, 7 Jan 2026 09:37:55 +0100
Subject: [PATCH 4/9] Fix shellgAIde prompt front matter
---
prompts/shellgaide-gnu-bash-script.prompt.md | 1 +
1 file changed, 1 insertion(+)
diff --git a/prompts/shellgaide-gnu-bash-script.prompt.md b/prompts/shellgaide-gnu-bash-script.prompt.md
index ea555fea0..5db538920 100644
--- a/prompts/shellgaide-gnu-bash-script.prompt.md
+++ b/prompts/shellgaide-gnu-bash-script.prompt.md
@@ -1,4 +1,5 @@
---
+mode: 'agent'
agent: 'agent'
description: 'Generate or refactor GNU-first Bash >= 5 scripts with strict safety, Google Shell Style Guide structure, and zero ShellCheck warnings (shellgAIde)'
tools: ['createFile', 'editFiles', 'search', 'testFailure']
From dddc3b30edee2ab6cf1798d9b061288c0daabdf2 Mon Sep 17 00:00:00 2001
From: Antonio Fragola <21192010+fragolinux@users.noreply.github.com>
Date: Wed, 7 Jan 2026 09:43:23 +0100
Subject: [PATCH 5/9] Fix shellgAIde docs nits
---
instructions/shellgaide-gnu-bash.instructions.md | 4 ++--
prompts/shellgaide-gnu-bash-script.prompt.md | 3 +--
skills/shellgaide-gnu-bash/SKILL.md | 2 +-
3 files changed, 4 insertions(+), 5 deletions(-)
diff --git a/instructions/shellgaide-gnu-bash.instructions.md b/instructions/shellgaide-gnu-bash.instructions.md
index b3cdd4246..18017b27f 100644
--- a/instructions/shellgaide-gnu-bash.instructions.md
+++ b/instructions/shellgaide-gnu-bash.instructions.md
@@ -11,7 +11,7 @@ Repository: https://github.com/fragolinux/shellgAIde
shellgAIde is a pun that sounds like **shellguide**:
-- **shell**: the domain (bash, portable scripts)
+- **shell**: the domain (GNU-first Bash / shell scripting)
- **gAIde**: a “guide” powered by **AI**, inspired by the Google Shell Style Guide
- **G** = Google (explicitly referencing the style guide)
- **AI** = the assistant that generates scripts
@@ -65,7 +65,7 @@ Executable code outside functions is forbidden (except minimal setup).
## Scope note: executable vs sourced files
- The mandatory executable structure above applies to executable scripts.
-- For sourced library files, do not force the full template, but keep the same safety/style rules that apply (quoting, no `eval`, no `[` ).
+- For sourced library files, do not force the full template, but keep the same safety/style rules that apply (quoting, no `eval`, no `[`).
## Naming and style (Google Shell Style Guide)
diff --git a/prompts/shellgaide-gnu-bash-script.prompt.md b/prompts/shellgaide-gnu-bash-script.prompt.md
index 5db538920..8b7b5919f 100644
--- a/prompts/shellgaide-gnu-bash-script.prompt.md
+++ b/prompts/shellgaide-gnu-bash-script.prompt.md
@@ -1,6 +1,5 @@
---
mode: 'agent'
-agent: 'agent'
description: 'Generate or refactor GNU-first Bash >= 5 scripts with strict safety, Google Shell Style Guide structure, and zero ShellCheck warnings (shellgAIde)'
tools: ['createFile', 'editFiles', 'search', 'testFailure']
---
@@ -10,7 +9,7 @@ tools: ['createFile', 'editFiles', 'search', 'testFailure']
Repository: https://github.com/fragolinux/shellgAIde
Companion agent definition (reference):
-- [agents/shellgaide-gnu-bash.agent.md](../agents/shellgaide-gnu-bash.agent.md)
+- [../agents/shellgaide-gnu-bash.agent.md](../agents/shellgaide-gnu-bash.agent.md)
Follow these instructions:
- [instructions/shellgaide-gnu-bash.instructions.md](../instructions/shellgaide-gnu-bash.instructions.md)
diff --git a/skills/shellgaide-gnu-bash/SKILL.md b/skills/shellgaide-gnu-bash/SKILL.md
index 516560402..e5ef32b28 100644
--- a/skills/shellgaide-gnu-bash/SKILL.md
+++ b/skills/shellgaide-gnu-bash/SKILL.md
@@ -13,7 +13,7 @@ Why the name?
shellgAIde is a pun that sounds like **shellguide**:
-- **shell**: the domain (bash, portable scripts)
+- **shell**: the domain (GNU-first Bash scripts)
- **gAIde**: a “guide” powered by **AI**, inspired by the Google Shell Style Guide
- **G** = Google (explicitly referencing the style guide)
- **AI** = the assistant that generates scripts
From 0e1c3911fe7d36c3f55d59d5e6b6e5a15ae5eacf Mon Sep 17 00:00:00 2001
From: fragolinux <21192010+fragolinux@users.noreply.github.com>
Date: Wed, 7 Jan 2026 10:05:35 +0100
Subject: [PATCH 6/9] Update docs/README.agents.md
Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>
---
docs/README.agents.md | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
diff --git a/docs/README.agents.md b/docs/README.agents.md
index c2975de96..b880ce5fa 100644
--- a/docs/README.agents.md
+++ b/docs/README.agents.md
@@ -122,7 +122,7 @@ Custom agents for GitHub Copilot, making it easy for users and organizations to
| [Semantic Kernel .NET mode instructions](../agents/semantic-kernel-dotnet.agent.md)
[](https://aka.ms/awesome-copilot/install/agent?url=vscode%3Achat-agent%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fagents%2Fsemantic-kernel-dotnet.agent.md)
[](https://aka.ms/awesome-copilot/install/agent?url=vscode-insiders%3Achat-agent%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fagents%2Fsemantic-kernel-dotnet.agent.md) | Create, update, refactor, explain or work with code using the .NET version of Semantic Kernel. | |
| [Semantic Kernel Python mode instructions](../agents/semantic-kernel-python.agent.md)
[](https://aka.ms/awesome-copilot/install/agent?url=vscode%3Achat-agent%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fagents%2Fsemantic-kernel-python.agent.md)
[](https://aka.ms/awesome-copilot/install/agent?url=vscode-insiders%3Achat-agent%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fagents%2Fsemantic-kernel-python.agent.md) | Create, update, refactor, explain or work with code using the Python version of Semantic Kernel. | |
| [Senior Cloud Architect](../agents/arch.agent.md)
[](https://aka.ms/awesome-copilot/install/agent?url=vscode%3Achat-agent%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fagents%2Farch.agent.md)
[](https://aka.ms/awesome-copilot/install/agent?url=vscode-insiders%3Achat-agent%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fagents%2Farch.agent.md) | Expert in modern architecture design patterns, NFR requirements, and creating comprehensive architectural diagrams and documentation | |
-| [Shellgaide Gnu Bash](../agents/shellgaide-gnu-bash.agent.md)
[](https://aka.ms/awesome-copilot/install/agent?url=vscode%3Achat-agent%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fagents%2Fshellgaide-gnu-bash.agent.md)
[](https://aka.ms/awesome-copilot/install/agent?url=vscode-insiders%3Achat-agent%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fagents%2Fshellgaide-gnu-bash.agent.md) | GNU-first Bash agent for writing and refactoring Bash >= 5 scripts with strict safety, Google Shell Style Guide structure, and zero ShellCheck warnings | |
+| [shellgAIde GNU Bash](../agents/shellgaide-gnu-bash.agent.md)
[](https://aka.ms/awesome-copilot/install/agent?url=vscode%3Achat-agent%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fagents%2Fshellgaide-gnu-bash.agent.md)
[](https://aka.ms/awesome-copilot/install/agent?url=vscode-insiders%3Achat-agent%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fagents%2Fshellgaide-gnu-bash.agent.md) | GNU-first Bash agent for writing and refactoring Bash >= 5 scripts with strict safety, Google Shell Style Guide structure, and zero ShellCheck warnings | |
| [Shopify Expert](../agents/shopify-expert.agent.md)
[](https://aka.ms/awesome-copilot/install/agent?url=vscode%3Achat-agent%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fagents%2Fshopify-expert.agent.md)
[](https://aka.ms/awesome-copilot/install/agent?url=vscode-insiders%3Achat-agent%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fagents%2Fshopify-expert.agent.md) | Expert Shopify development assistant specializing in theme development, Liquid templating, app development, and Shopify APIs | |
| [Software Engineer Agent v1](../agents/software-engineer-agent-v1.agent.md)
[](https://aka.ms/awesome-copilot/install/agent?url=vscode%3Achat-agent%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fagents%2Fsoftware-engineer-agent-v1.agent.md)
[](https://aka.ms/awesome-copilot/install/agent?url=vscode-insiders%3Achat-agent%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fagents%2Fsoftware-engineer-agent-v1.agent.md) | Expert-level software engineering agent. Deliver production-ready, maintainable code. Execute systematically and specification-driven. Document comprehensively. Operate autonomously and adaptively. | |
| [Specification mode instructions](../agents/specification.agent.md)
[](https://aka.ms/awesome-copilot/install/agent?url=vscode%3Achat-agent%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fagents%2Fspecification.agent.md)
[](https://aka.ms/awesome-copilot/install/agent?url=vscode-insiders%3Achat-agent%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fagents%2Fspecification.agent.md) | Generate or update specification documents for new or existing functionality. | |
From 35f63a12d09a44d77fa5af7c3ebd387c99aed07e Mon Sep 17 00:00:00 2001
From: fragolinux <21192010+fragolinux@users.noreply.github.com>
Date: Wed, 7 Jan 2026 10:05:51 +0100
Subject: [PATCH 7/9] Update skills/shellgaide-gnu-bash/SKILL.md
Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>
---
skills/shellgaide-gnu-bash/SKILL.md | 6 +++---
1 file changed, 3 insertions(+), 3 deletions(-)
diff --git a/skills/shellgaide-gnu-bash/SKILL.md b/skills/shellgaide-gnu-bash/SKILL.md
index e5ef32b28..8eaf6b0ee 100644
--- a/skills/shellgaide-gnu-bash/SKILL.md
+++ b/skills/shellgaide-gnu-bash/SKILL.md
@@ -15,9 +15,9 @@ shellgAIde is a pun that sounds like **shellguide**:
- **shell**: the domain (GNU-first Bash scripts)
- **gAIde**: a “guide” powered by **AI**, inspired by the Google Shell Style Guide
- - **G** = Google (explicitly referencing the style guide)
- - **AI** = the assistant that generates scripts
- - **de** = *deterministic environment* (the key promise of this repo)
+ - **G** = Google (explicitly referencing the style guide)
+ - **AI** = the assistant that generates scripts
+ - **de** = *deterministic environment* (the key promise of this repo)
### Non-negotiable target environment
- Bash >= 5.x.
From 9cf2bdcf7eeb205bc184661cc03e3950b461cff7 Mon Sep 17 00:00:00 2001
From: fragolinux <21192010+fragolinux@users.noreply.github.com>
Date: Wed, 7 Jan 2026 10:06:02 +0100
Subject: [PATCH 8/9] Update prompts/shellgaide-gnu-bash-script.prompt.md
Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>
---
prompts/shellgaide-gnu-bash-script.prompt.md | 2 --
1 file changed, 2 deletions(-)
diff --git a/prompts/shellgaide-gnu-bash-script.prompt.md b/prompts/shellgaide-gnu-bash-script.prompt.md
index 8b7b5919f..454798810 100644
--- a/prompts/shellgaide-gnu-bash-script.prompt.md
+++ b/prompts/shellgaide-gnu-bash-script.prompt.md
@@ -99,5 +99,3 @@ To get the best result, provide:
- shellgAIde repository: https://github.com/fragolinux/shellgAIde
- Google Shell Style Guide: https://google.github.io/styleguide/shellguide.html
-
-
From 1aeed62a60212ec0fbbd15f82a76507ff54f10b8 Mon Sep 17 00:00:00 2001
From: Antonio Fragola <21192010+fragolinux@users.noreply.github.com>
Date: Wed, 7 Jan 2026 10:23:47 +0100
Subject: [PATCH 9/9] chore(docs): regenerate README.agents
---
docs/README.agents.md | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
diff --git a/docs/README.agents.md b/docs/README.agents.md
index b880ce5fa..c2975de96 100644
--- a/docs/README.agents.md
+++ b/docs/README.agents.md
@@ -122,7 +122,7 @@ Custom agents for GitHub Copilot, making it easy for users and organizations to
| [Semantic Kernel .NET mode instructions](../agents/semantic-kernel-dotnet.agent.md)
[](https://aka.ms/awesome-copilot/install/agent?url=vscode%3Achat-agent%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fagents%2Fsemantic-kernel-dotnet.agent.md)
[](https://aka.ms/awesome-copilot/install/agent?url=vscode-insiders%3Achat-agent%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fagents%2Fsemantic-kernel-dotnet.agent.md) | Create, update, refactor, explain or work with code using the .NET version of Semantic Kernel. | |
| [Semantic Kernel Python mode instructions](../agents/semantic-kernel-python.agent.md)
[](https://aka.ms/awesome-copilot/install/agent?url=vscode%3Achat-agent%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fagents%2Fsemantic-kernel-python.agent.md)
[](https://aka.ms/awesome-copilot/install/agent?url=vscode-insiders%3Achat-agent%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fagents%2Fsemantic-kernel-python.agent.md) | Create, update, refactor, explain or work with code using the Python version of Semantic Kernel. | |
| [Senior Cloud Architect](../agents/arch.agent.md)
[](https://aka.ms/awesome-copilot/install/agent?url=vscode%3Achat-agent%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fagents%2Farch.agent.md)
[](https://aka.ms/awesome-copilot/install/agent?url=vscode-insiders%3Achat-agent%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fagents%2Farch.agent.md) | Expert in modern architecture design patterns, NFR requirements, and creating comprehensive architectural diagrams and documentation | |
-| [shellgAIde GNU Bash](../agents/shellgaide-gnu-bash.agent.md)
[](https://aka.ms/awesome-copilot/install/agent?url=vscode%3Achat-agent%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fagents%2Fshellgaide-gnu-bash.agent.md)
[](https://aka.ms/awesome-copilot/install/agent?url=vscode-insiders%3Achat-agent%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fagents%2Fshellgaide-gnu-bash.agent.md) | GNU-first Bash agent for writing and refactoring Bash >= 5 scripts with strict safety, Google Shell Style Guide structure, and zero ShellCheck warnings | |
+| [Shellgaide Gnu Bash](../agents/shellgaide-gnu-bash.agent.md)
[](https://aka.ms/awesome-copilot/install/agent?url=vscode%3Achat-agent%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fagents%2Fshellgaide-gnu-bash.agent.md)
[](https://aka.ms/awesome-copilot/install/agent?url=vscode-insiders%3Achat-agent%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fagents%2Fshellgaide-gnu-bash.agent.md) | GNU-first Bash agent for writing and refactoring Bash >= 5 scripts with strict safety, Google Shell Style Guide structure, and zero ShellCheck warnings | |
| [Shopify Expert](../agents/shopify-expert.agent.md)
[](https://aka.ms/awesome-copilot/install/agent?url=vscode%3Achat-agent%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fagents%2Fshopify-expert.agent.md)
[](https://aka.ms/awesome-copilot/install/agent?url=vscode-insiders%3Achat-agent%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fagents%2Fshopify-expert.agent.md) | Expert Shopify development assistant specializing in theme development, Liquid templating, app development, and Shopify APIs | |
| [Software Engineer Agent v1](../agents/software-engineer-agent-v1.agent.md)
[](https://aka.ms/awesome-copilot/install/agent?url=vscode%3Achat-agent%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fagents%2Fsoftware-engineer-agent-v1.agent.md)
[](https://aka.ms/awesome-copilot/install/agent?url=vscode-insiders%3Achat-agent%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fagents%2Fsoftware-engineer-agent-v1.agent.md) | Expert-level software engineering agent. Deliver production-ready, maintainable code. Execute systematically and specification-driven. Document comprehensively. Operate autonomously and adaptively. | |
| [Specification mode instructions](../agents/specification.agent.md)
[](https://aka.ms/awesome-copilot/install/agent?url=vscode%3Achat-agent%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fagents%2Fspecification.agent.md)
[](https://aka.ms/awesome-copilot/install/agent?url=vscode-insiders%3Achat-agent%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fagents%2Fspecification.agent.md) | Generate or update specification documents for new or existing functionality. | |