diff --git a/agents/shellgaide-gnu-bash.agent.md b/agents/shellgaide-gnu-bash.agent.md
new file mode 100644
index 00000000..2267a033
--- /dev/null
+++ b/agents/shellgaide-gnu-bash.agent.md
@@ -0,0 +1,83 @@
+---
+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-4.1
+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
+
+Repository: https://github.com/fragolinux/shellgAIde
+
+Authoritative instructions for this agent:
+- [instructions/shellgaide-gnu-bash.instructions.md](../instructions/shellgaide-gnu-bash.instructions.md)
+
+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/docs/README.agents.md b/docs/README.agents.md
index 19beea7a..367bcca0 100644
--- a/docs/README.agents.md
+++ b/docs/README.agents.md
@@ -129,6 +129,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.instructions.md b/docs/README.instructions.md
index f1c19203..8c77c0df 100644
--- a/docs/README.instructions.md
+++ b/docs/README.instructions.md
@@ -148,6 +148,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/docs/README.prompts.md b/docs/README.prompts.md
index 55f4e215..29e740c2 100644
--- a/docs/README.prompts.md
+++ b/docs/README.prompts.md
@@ -123,6 +123,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 7c371a6e..d888eb9d 100644
--- a/docs/README.skills.md
+++ b/docs/README.skills.md
@@ -26,6 +26,7 @@ Skills differ from other primitives by supporting bundled assets (scripts, code
| [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` |
| [github-issues](../skills/github-issues/SKILL.md) | Create, update, and manage GitHub issues using MCP tools. Use this skill when users want to create bug reports, feature requests, or task issues, update existing issues, add labels/assignees/milestones, or manage issue workflows. Triggers on requests like "create an issue", "file a bug", "request a feature", "update issue X", or any GitHub issue management task. | `references/templates.md` |
| [nuget-manager](../skills/nuget-manager/SKILL.md) | Manage NuGet packages in .NET projects/solutions. Use this skill when adding, removing, or updating NuGet package versions. It enforces using `dotnet` CLI for package management and provides strict procedures for direct file edits only when updating versions. | None |
+| [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 |
| [snowflake-semanticview](../skills/snowflake-semanticview/SKILL.md) | Create, alter, and validate Snowflake semantic views using Snowflake CLI (snow). Use when asked to build or troubleshoot semantic views/semantic layer definitions with CREATE/ALTER SEMANTIC VIEW, to validate semantic-view DDL against Snowflake via CLI, or to guide Snowflake CLI installation and connection setup. | None |
| [web-design-reviewer](../skills/web-design-reviewer/SKILL.md) | This skill enables visual inspection of websites running locally or remotely to identify and fix design issues. Triggers on requests like "review website design", "check the UI", "fix the layout", "find design problems". Detects issues with responsive design, accessibility, visual consistency, and layout breakage, then performs fixes at the source code level. | `references/framework-fixes.md`
`references/visual-checklist.md` |
| [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/instructions/shellgaide-gnu-bash.instructions.md b/instructions/shellgaide-gnu-bash.instructions.md
new file mode 100644
index 00000000..18017b27
--- /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 (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
+ - **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
new file mode 100644
index 00000000..45479881
--- /dev/null
+++ b/prompts/shellgaide-gnu-bash-script.prompt.md
@@ -0,0 +1,101 @@
+---
+mode: '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']
+---
+
+# shellgAIde — GNU-first Bash Script Prompt
+
+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)
+
+## 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
diff --git a/skills/shellgaide-gnu-bash/SKILL.md b/skills/shellgaide-gnu-bash/SKILL.md
new file mode 100644
index 00000000..8eaf6b0e
--- /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 (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)
+
+### 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