diff --git a/README.md b/README.md index dd457d8..76f7737 100644 --- a/README.md +++ b/README.md @@ -131,6 +131,7 @@ Add skills to project knowledge or paste SKILL.md contents into the conversation | ๐Ÿ‘” Professional | [difficult-workplace-conversations](skills/difficult-workplace-conversations/README.md) | Navigate difficult conversations | | ๐Ÿ‘” Professional | [feedback-mastery](skills/feedback-mastery/README.md) | Deliver constructive feedback | | ๐Ÿ‘” Professional | [professional-communication](skills/professional-communication/README.md) | Technical communication guide | +| ๐Ÿงช Testing | [agent-safety-preflight](skills/agent-safety-preflight/README.md) | Repo safety receipt before AI coding agents get tool access | | ๐Ÿงช Testing | [qa-test-planner](skills/qa-test-planner/README.md) | Comprehensive QA test planning | | ๐Ÿ“ฆ Git | [commit-work](skills/commit-work/README.md) | High-quality git commits | | ๐Ÿ”ง Utilities | [datadog-cli](skills/datadog-cli/README.md) | Debug with Datadog logs & metrics | diff --git a/skills/agent-safety-preflight/README.md b/skills/agent-safety-preflight/README.md new file mode 100644 index 0000000..3f01c2b --- /dev/null +++ b/skills/agent-safety-preflight/README.md @@ -0,0 +1,55 @@ +# Agent Safety Preflight + +A lightweight Agent Skills package for teams that let Claude Code, Codex, Cursor, MCP tools, PR bots, hooks, or other AI coding agents work inside real repositories. + +Run it before the agent gets shell, package-script, workflow, MCP/API, or secret-adjacent scope. It produces a Green / Yellow / Red repo handoff receipt that can be pasted into a PR, issue, runbook, or agent session log. + +## When to Use This Skill + +Use `agent-safety-preflight` when you need to: + +- Check a repo before an AI coding agent starts editing or running commands. +- Review `AGENTS.md`, `CLAUDE.md`, `.cursor/rules/*`, MCP config, Claude plugin files, or Copilot instructions. +- Spot package scripts, GitHub Actions, Dev Container lifecycle commands, or plugin/skill manifests before an agent inherits them. +- Write a concise handoff receipt for allowed commands, must-ask commands, and excluded files. + +## Quick Start + +```bash +/agent-safety-preflight +``` + +Then ask the agent to run the bundled script: + +```bash +bash /mnt/skills/user/agent-safety-preflight/scripts/run-preflight-lite.sh . +``` + +The script clones the public lite scanner from: + +```text +https://github.com/el-zachariah/ai-agent-safety-starter-pack +``` + +and runs it locally against the repo path you provide. + +## Example Receipt + +```markdown +Agent preflight receipt +- Repo checked: ./my-app +- Agent/tool about to run: Claude Code with MCP tools +- Decision: Yellow +- Risk buckets found: agent instructions, package scripts, GitHub Actions, secret-adjacent files +- Commands allowed without asking: tests, lint, read-only inspection +- Commands that must ask first: deploy, database migration, credential access, destructive cleanup +- Files/tools excluded before agent access: .env, production deploy workflow, npm publish script +``` + +## Why It Helps + +AI coding agents often inherit repo-local instructions, hooks, workflow files, package scripts, and MCP/tool config. This skill gives the user a visible pre-run checkpoint before an agent is trusted with broad tool access. + +## Limits + +This is not a sandbox, malware scanner, secret scanner, compliance audit, or security guarantee. It is a quick local preflight and receipt generator for safer agent handoffs. diff --git a/skills/agent-safety-preflight/SKILL.md b/skills/agent-safety-preflight/SKILL.md new file mode 100644 index 0000000..b9d999f --- /dev/null +++ b/skills/agent-safety-preflight/SKILL.md @@ -0,0 +1,68 @@ +--- +name: agent-safety-preflight +description: Run a local repo safety preflight before Claude Code, Codex, Cursor, MCP tools, hooks, or other AI coding agents get shell, package-script, or secret-adjacent scope. +trigger: explicit +--- + +# Agent Safety Preflight + +Use this skill before handing a repository to an autonomous coding agent, Claude Code hook, Codex/Cursor workflow, MCP-backed toolchain, plugin marketplace package, or long-running TDD/agent loop. + +It gives the user a quick Green / Yellow / Red receipt so they can decide what the agent may read or run before tool access starts. + +## Quick Start + +Run the free local scanner against the current repository: + +```bash +bash /mnt/skills/user/agent-safety-preflight/scripts/run-preflight-lite.sh . +``` + +Or run the scanner source directly: + +```bash +git clone https://github.com/el-zachariah/ai-agent-safety-starter-pack.git /tmp/agent-preflight +python3 /tmp/agent-preflight/agent_preflight_lite.py . --json +python3 /tmp/agent-preflight/agent_preflight_lite.py . +``` + +## What It Checks + +- Agent instruction files such as `AGENTS.md`, `CLAUDE.md`, `.cursorrules`, and `.cursor/rules/*`. +- Claude, Cursor, MCP, Copilot, Dev Container, and plugin/skill marketplace config. +- GitHub Actions workflows and package scripts an agent might execute. +- Secret-adjacent files such as `.env`, `.npmrc`, `.pypirc`, SSH keys, and token-looking config. +- Risky shell patterns such as `rm -rf`, `curl | sh`, `chmod 777`, `docker.sock`, and force-push commands. + +## Workflow + +1. Ask what agent or workflow is about to run: Claude Code, Codex, Cursor, MCP server, hook loop, PR bot, or another coding agent. +2. Run the local scanner against the target repo. +3. Read the decision level and risk buckets. +4. Produce a short receipt with allowed commands, must-ask commands, excluded files, and follow-up checks. +5. If the result is Yellow or Red, tighten the run rules before giving the agent shell/package-script/MCP/API scope. + +## Receipt Template + +```markdown +Agent preflight receipt +- Repo checked: +- Agent/tool about to run: +- Decision: Green / Yellow / Red +- Risk buckets found: +- Commands allowed without asking: +- Commands that must ask first: +- Files/tools excluded before agent access: +``` + +## Output Guidance + +Present the result as a practical go/no-go note, not as a security audit. + +- **Green**: low signal. Normal code review discipline is likely enough. +- **Yellow**: agent can proceed only with written run rules and must-ask boundaries. +- **Red**: stop before broad tool access; remove secrets, review workflows/scripts, and define command restrictions first. + +## Limits + +This is a lightweight preflight, not a sandbox, malware scanner, secret scanner, vulnerability audit, or guarantee that an agent run is safe. diff --git a/skills/agent-safety-preflight/scripts/run-preflight-lite.sh b/skills/agent-safety-preflight/scripts/run-preflight-lite.sh new file mode 100755 index 0000000..9af624a --- /dev/null +++ b/skills/agent-safety-preflight/scripts/run-preflight-lite.sh @@ -0,0 +1,16 @@ +#!/bin/bash +set -euo pipefail + +repo_path="${1:-.}" +scanner_repo="https://github.com/el-zachariah/ai-agent-safety-starter-pack.git" +tmp_dir="$(mktemp -d)" +cleanup() { + rm -rf "$tmp_dir" +} +trap cleanup EXIT + +echo "Cloning free agent preflight scanner..." >&2 +git clone --depth 1 "$scanner_repo" "$tmp_dir/agent-preflight" >/dev/null 2>&1 + +echo "Running local preflight against: $repo_path" >&2 +python3 "$tmp_dir/agent-preflight/agent_preflight_lite.py" "$repo_path" --json