From 07967103b31a577d8937c9702b0cbea999e17bc5 Mon Sep 17 00:00:00 2001
From: Steve Nims <sjnims@gmail.com>
Date: Sat, 13 Dec 2025 08:48:37 -0500
Subject: [PATCH] docs: add prerequisites section for utility script
 dependencies
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- README.md: Add "For Utility Scripts" section documenting jq, grep, sed requirements
- hook-development/SKILL.md: Add prerequisites note referencing main README

Verified that scripts use bash 3.2+ features only (regex matching), not bash 4.0+.

Fixes #152

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>
---
 README.md                                     | 24 ++++++++++++++++++-
 .../skills/hook-development/SKILL.md          |  2 ++
 2 files changed, 25 insertions(+), 1 deletion(-)

diff --git a/README.md b/README.md
index d6498c3..4abdd15 100644
--- a/README.md
+++ b/README.md
@@ -42,10 +42,32 @@ Each component follows progressive disclosure: lean core documentation with deta
 
 ## Prerequisites
 
+### Required
+
 - [Claude Code CLI](https://docs.anthropic.com/en/docs/claude-code) installed and configured
-- Bash shell (for utility scripts)
 - Git (for version control and marketplace publishing)
 
+### For Utility Scripts
+
+The plugin includes utility scripts for validation and testing. These require:
+
+| Tool | Version | Purpose |
+|------|---------|---------|
+| bash | 3.2+ | Shell scripting (macOS default works) |
+| jq | 1.6+ | JSON parsing and validation |
+| grep | - | Pattern matching (with `-E` support) |
+| sed | - | Stream editing (GNU or BSD) |
+
+**Check your environment:**
+
+```bash
+bash --version | head -1
+jq --version
+grep --version 2>&1 | head -1
+```
+
+> **Note**: `jq` may need to be installed. macOS: `brew install jq`, Linux: `apt install jq`
+
 ## Installation
 
 Add this marketplace and install the plugin:
diff --git a/plugins/plugin-dev/skills/hook-development/SKILL.md b/plugins/plugin-dev/skills/hook-development/SKILL.md
index d9973d9..42bada5 100644
--- a/plugins/plugin-dev/skills/hook-development/SKILL.md
+++ b/plugins/plugin-dev/skills/hook-development/SKILL.md
@@ -695,6 +695,8 @@ Working examples in `examples/`:
 
 ### Utility Scripts
 
+> **Prerequisites**: These scripts require `jq` for JSON validation. See the [main README](../../../../README.md#for-utility-scripts) for setup.
+
 Development tools in `scripts/`:
 
 - **`validate-hook-schema.sh`** - Validate hooks.json structure and syntax