From e6ce1797a1539a1330b1ded38f409fb7e919897b Mon Sep 17 00:00:00 2001
From: sriki <insriki@gmail.com>
Date: Sat, 21 Mar 2026 09:59:44 +0530
Subject: [PATCH] fix: accurate directory mode behavior and scan side-effect
 warning
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- Directory mode note: replace overpromising 'scans for first file
  containing a callable' with accurate behavior — picks first .py in
  scripts/ alphabetically, fails if that file lacks a recognized
  entry-point, does not fall back to other files
- Scan section: add warning that the injection check fires 47
  adversarial prompts at the agent; agents with side effects (messages,
  DB writes, paid APIs) will trigger those effects up to 47 times
---
 skills/operon-guard/SKILL.md | 17 +++++++++++++----
 1 file changed, 13 insertions(+), 4 deletions(-)

diff --git a/skills/operon-guard/SKILL.md b/skills/operon-guard/SKILL.md
index f0ed0090c53..39f40980ece 100644
--- a/skills/operon-guard/SKILL.md
+++ b/skills/operon-guard/SKILL.md
@@ -40,10 +40,12 @@ pip install operon-guard
 operon-guard test path/to/skill/
 ```
 
-> **Note:** When pointing at a skill directory, `operon-guard` scans for the first
-> Python file containing a recognized callable (`agent`, `run`, `main`, `execute`).
-> Only that file is tested. To test a specific file in a multi-file skill directory,
-> pass the file path explicitly: `operon-guard test path/to/skill/my_agent.py:run`
+> **Note:** When pointing at a skill directory, `operon-guard` picks the **first
+> `.py` file in `scripts/` sorted alphabetically** and passes it to the loader. If
+> that file does not export a recognized entry-point callable (`agent`, `run`, `main`,
+> `execute`, `process`, `handle`), the command fails — it does **not** fall back to
+> other files in the directory. To target a specific file, pass the path explicitly:
+> `operon-guard test path/to/skill/my_agent.py:run`
 
 ### Quick safety scan (injection + PII only)
 
@@ -51,6 +53,13 @@ operon-guard test path/to/skill/
 > gate in scripts or CI (`operon-guard scan && install` will always continue, even when
 > injection or PII problems are detected). Use `operon-guard test` for gating — it
 > exits 1 when the trust score fails.
+>
+> **Warning:** The injection check fires **47 adversarial prompts** at the agent. If
+> your agent has side effects — sending messages, writing to a database, calling paid
+> APIs — those side effects will be triggered up to 47 times during the scan. Either
+> run in a sandboxed environment, or skip injection probes by setting
+> `safety.check_injection: false` in a guardfile and using `operon-guard test --spec`
+> instead.
 
 ```bash
 operon-guard scan path/to/agent.py