Initial skills documentation — 25 categories, all SKILL.md + references + scripts

2026-07-15 17:42:20 -04:00
commit 1b4fcd4427
976 changed files with 188344 additions and 0 deletions
@@ -0,0 +1,57 @@
+# Agent Discipline: Config Verification
+
+This reference captures hard lessons about agent behavior with configuration.
+
+## Rule
+
+**Never set a configuration key unless you have verified it exists in the application's documentation, schema, or known-good examples.**
+
+If you *assume* a config key exists and write it to a production config file:
+
+1. The application silently ignores it (at best) or crashes (at worst)
+2. The user's intent is not met
+3. The agent appears to have fixed the problem when nothing actually changed
+4. The bad key pollutes the config file and wastes debugging time later
+
+## Examples of past violations
+
+- `fallback_providers` — invented, does not exist in Hermes Agent config schema. The real behavior (manual provider switch) was never configured.
+
+## Config file corruption during Python editing
+
+Python scripts that read, search/replace, and write YAML config files can **corrupt the file structure** if the replacement logic is wrong (wrong old_string, partial match, or mismatched indentation). This causes Hermes to fail silently or crash on restart.
+
+**This session's example:** Replacing `api_key: sk-lbh...bWPA` in the anita profile config (literally the string `sk-lbh...bWPA` with the dots) overwrote the real key value with the literal characters `sk-lbh...bWPA`, causing `HTTP 401: Authentication Error` every time Anita's gateway tried to authenticate against admin-ai.
+
+**Rule:** Never use the *displayed/redacted* version of a credential in a search-and-replace operation. The redacted value shown in a `read_file` response (e.g. `sk-lbh...bWPA`) is NOT the real value — the dots are literal characters in the edit buffer but represent truncated content on disk. Always extract the raw value from a hex dump, raw bytes, or the original source file.
+
+**Preferred workflow for credential fixing:**
+
+```bash
+# Step 1: Get the exact raw key bytes from the source
+python3 -c "
+with open('/root/.hermes/config.yaml', 'rb') as f:
+    for line in f:
+        if b'api_key:' in line and b'vision' not in line:
+            print(line.hex())
+"
+# Step 2: Decode hex to verify the real string
+echo '736b2d6c626868...' | xxd -r -p
+# Step 3: Write the raw string to the target file
+python3 -c "
+with open('/root/.hermes/profiles/anita/config.yaml') as f:
+    content = f.read()
+content = content.replace('api_key: VERIFIED_BAD_VALUE', 'api_key: REAL_VALUE')
+with open('/root/.hermes/profiles/anita/config.yaml', 'w') as f:
+    f.write(content)
+"
+```
+
+**Alternative:** Write the entire file fresh using `write_file` instead of search/replace — less error-prone for small config files.
+
+## When a mistake happens
+
+- Acknowledge it immediately
+- Remove the bad config key
+- Document what the actual approach should be
+- Do not repeat the same assumption in the same session or on the same application