fix(skills): improve 1password skill — env var prompting, auth docs, broken examples

fix(skills): improve 1password skill — env var prompting, auth docs, broken examples

optional-skills/security/1password/SKILL.md

@@ -2,12 +2,19 @@
 name: 1password
 description: Set up and use 1Password CLI (op). Use when installing the CLI, enabling desktop app integration, signing in, and reading/injecting secrets for commands.
 version: 1.0.0
-author: Hermes Agent
+author: arceus77-7, enhanced by Hermes Agent
 license: MIT
 metadata:
   hermes:
     tags: [security, secrets, 1password, op, cli]
     category: security
+setup:
+  help: "Create a service account at https://my.1password.com → Settings → Service Accounts"
+  collect_secrets:
+    - env_var: OP_SERVICE_ACCOUNT_TOKEN
+      prompt: "1Password Service Account Token"
+      provider_url: "https://developer.1password.com/docs/service-accounts/"
+      secret: true
 ---
 
 # 1Password CLI
@@ -17,9 +24,9 @@ Use this skill when the user wants secrets managed through 1Password instead of
 ## Requirements
 
 - 1Password account
-- 1Password desktop app installed and unlocked
 - 1Password CLI (`op`) installed
-- `tmux` available for stable authenticated sessions during Hermes terminal calls
+- One of: desktop app integration, service account token (`OP_SERVICE_ACCOUNT_TOKEN`), or Connect server
+- `tmux` available for stable authenticated sessions during Hermes terminal calls (desktop app flow only)
 
 ## When to Use
 
@@ -29,6 +36,31 @@ Use this skill when the user wants secrets managed through 1Password instead of
 - Inject secrets into config/templates using `op inject`
 - Run commands with secret env vars via `op run`
 
+## Authentication Methods
+
+### Service Account (recommended for Hermes)
+
+Set `OP_SERVICE_ACCOUNT_TOKEN` in `~/.hermes/.env` (the skill will prompt for this on first load).
+No desktop app needed. Supports `op read`, `op inject`, `op run`.
+
+```bash
+export OP_SERVICE_ACCOUNT_TOKEN="your-token-here"
+op whoami  # verify — should show Type: SERVICE_ACCOUNT
+```
+
+### Desktop App Integration (interactive)
+
+1. Enable in 1Password desktop app: Settings → Developer → Integrate with 1Password CLI
+2. Ensure app is unlocked
+3. Run `op signin` and approve the biometric prompt
+
+### Connect Server (self-hosted)
+
+```bash
+export OP_CONNECT_HOST="http://localhost:8080"
+export OP_CONNECT_TOKEN="your-connect-token"
+```
+
 ## Setup
 
 1. Install CLI:
@@ -50,16 +82,14 @@ winget install AgileBits.1Password.CLI
 op --version
 ```
 
-3. Enable app integration in 1Password desktop app:
-- macOS: Settings -> Developer -> Integrate with 1Password CLI
-- Linux/Windows: Settings -> Developer -> Integrate with 1Password CLI
+3. Choose an auth method above and configure it.
 
-4. Ensure app is unlocked.
-
-## Hermes Execution Pattern (important)
+## Hermes Execution Pattern (desktop app flow)
 
 Hermes terminal commands are non-interactive by default and can lose auth context between calls.
-For reliable `op` use, run sign-in and secret operations inside a dedicated tmux session.
+For reliable `op` use with desktop app integration, run sign-in and secret operations inside a dedicated tmux session.
+
+Note: This is NOT needed when using `OP_SERVICE_ACCOUNT_TOKEN` — the token persists across terminal calls automatically.
 
 ```bash
 SOCKET_DIR="${TMPDIR:-/tmp}/hermes-tmux-sockets"
@@ -108,7 +138,7 @@ echo "db_password: {{ op://app-prod/db/password }}" | op inject
 ### Run a command with secret env var
 
 ```bash
-export OPENAI_API_KEY="op://.../api key"
+export OPENAI_API_KEY="op://app-prod/openai/api key"
 op run -- sh -c '[ -n "$OPENAI_API_KEY" ] && echo "OPENAI_API_KEY is set" || echo "OPENAI_API_KEY missing"'
 ```
 
@@ -122,9 +152,11 @@ op run -- sh -c '[ -n "$OPENAI_API_KEY" ] && echo "OPENAI_API_KEY is set" || ech
 ## CI / Headless note
 
 For non-interactive use, authenticate with `OP_SERVICE_ACCOUNT_TOKEN` and avoid interactive `op signin`.
+Service accounts require CLI v2.18.0+.
 
 ## References
 
 - `references/get-started.md`
 - `references/cli-examples.md`
 - https://developer.1password.com/docs/cli/
+- https://developer.1password.com/docs/service-accounts/

optional-skills/security/1password/references/cli-examples.md

@@ -13,7 +13,7 @@ op account list
 
 ```bash
 op read "op://app-prod/db/password"
-op read "op://app-prod/one-time password?attribute=otp"
+op read "op://app-prod/npm/one-time password?attribute=otp"
 ```
 
 ## Inject secrets

optional-skills/security/DESCRIPTION.md

@@ -0,0 +1,3 @@
+# Security
+
+Skills for secrets management, credential handling, and security tooling integrations.