Secret's Safe

Secure API key and secrets management for agent skills. Use this skill whenever a task requires authenticating with an external service, reading or writing A...

Security Scan

The skill is an instruction-only guidance document for safe secret handling and its requirements and instructions are consistent with that purpose.

Purpose & Capability

Name and description match the content: the skill is an instructional guide for secure secret handling. It declares no env requirements, no installs, and provides patterns for other skills to adopt. There are no unrelated credentials, binaries, or install steps requested.

Instruction Scope

SKILL.md stays within its stated scope (environment injection, secrets manager wrappers, and audit checklists). It explicitly warns against pasting secrets into chat, logging secrets, or dumping env files. One small inconsistency: the 'safe curl' example uses shell variable expansion inside a header argument (MY_SERVICE_API_KEY="$MY_SERVICE_API_KEY" curl -H "Authorization: Bearer $MY_SERVICE_API_KEY" ...). Expanding secrets into command arguments can expose them via process listings on some systems (ps). The skill does elsewhere warn about positional args and set -x; overall the guidance is good but the example could be tightened to avoid potential process-argv exposure.

Install Mechanism

No install spec and no code files — instruction-only. This minimizes install risk; nothing is downloaded or written to disk by the skill itself.

Credentials

The skill requests no environment variables or credentials itself (it is a template/guide). Where it suggests requires.env entries for other skills, those are appropriate and proportional to the described integrations (OpenAI, GitHub, AWS, etc.). There are no unexplained secret or config path requests.

Persistence & Privilege

always is false and the skill does not request persistent system-wide privileges or modify other skills. It only provides guidance and recommended patterns; no privileged behavior is requested.

Assessment

This is a documentation-only skill that teaches reasonable secret-handling patterns; it's coherent and low-risk. Before relying on its examples, consider a small tweak: avoid expanding secrets into command-line arguments (they can appear in process listings). Prefer injecting values into the subprocess environment (exported env) or use tools/CLI options that read secrets from stdin or environment rather than placing them in argv. If you embed these patterns in a real skill, ensure you add explicit requires.env frontmatter and avoid echoing or printing secrets anywhere.

Secret-Safe: Secure Credential Handling for Agent Skills

Why this skill exists: Snyk researchers found that 7.1% of all ClawHub skills instruct agents to handle API keys through the LLM context — making every secret an active exfiltration channel. This skill teaches the correct pattern.

---

The Core Rule

A secret must never appear in:

• The LLM prompt or system context
• Claude's response or reasoning
• Logs, session exports, or .jsonl history files
• File artifacts created by the agent
• Error messages echoed back to the user

A secret must only flow through:

• process.env (injected by OpenClaw before the agent turn)
• The shell environment of a subprocess the agent spawns
• A secrets manager CLI (read at subprocess level, not piped back into context)

---

Pattern 1: Environment Injection (Preferred)

This is OpenClaw's native, secure path. Use it for any skill that needs an API key.

In SKILL.md frontmatter

---
name: my-service-skill
description: Interact with MyService API.
metadata: {"openclaw": {"requires": {"env": ["MY_SERVICE_API_KEY"]}, "primaryEnv": "MY_SERVICE_API_KEY"}}
---

The requires.env gate ensures the skill will not load if the key isn't present — no silent failures, no prompting the user to paste a key mid-conversation.

The primaryEnv field links to skills.entries.<n>.apiKey in openclaw.json, so the user configures it once in their config file, never in chat.

In skill instructions

## Authentication
The API key is available as `$MY_SERVICE_API_KEY` in the shell environment.
Pass it to CLI tools or curl as an environment variable — never echo it or
include it in any output returned to the user.

Example safe curl invocation (instruct the agent to do this)

# CORRECT — key stays in environment, never in command string visible to LLM
MY_SERVICE_API_KEY="$MY_SERVICE_API_KEY" curl -s \
  -H "Authorization: Bearer $MY_SERVICE_API_KEY" \
  https://api.myservice.com/v1/data

Never instruct the agent to do this:

# WRONG — key is visible in LLM context, command history, and logs
curl -H "Authorization: Bearer sk-abc123realkeyhere" https://api.myservice.com/

---

Pattern 2: Secrets Manager Integration

For production setups or team environments, read secrets from a manager at subprocess level.

Supported managers

Manager	CLI	Env var pattern
macOS Keychain	security find-generic-password -w	N/A
1Password CLI	op read op://vault/item/field	OP_SERVICE_ACCOUNT_TOKEN
Doppler	doppler run --	DOPPLER_TOKEN
HashiCorp Vault	vault kv get -field=value	VAULT_TOKEN
Bitwarden CLI	bw get password item-name	BW_SESSION

Safe shell wrapper pattern

Create a scripts/run-with-secret.sh in your skill:

#!/usr/bin/env bash
# Fetches the secret at subprocess level — never echoes to stdout
SECRET=$(security find-generic-password -s "my-service-api-key" -w 2>/dev/null)
if [ -z "$SECRET" ]; then
  echo "ERROR: Secret 'my-service-api-key' not found in keychain." >&2
  exit 1
fi
export MY_SERVICE_API_KEY="$SECRET"
exec "$@"

The agent runs bash {baseDir}/scripts/run-with-secret.sh <actual-command> — the secret is fetched and injected entirely outside the LLM's view.

---

Pattern 3: User Setup Flow (first-run)

If the user hasn't configured a key yet, guide them through setup without asking for the key in chat.

Correct setup prompt to give the user:

To use this skill, add your API key to ~/.openclaw/openclaw.json:

  skills:
    entries:
      my-service:
        apiKey: "your-key-here"

Or set it as an environment variable before starting OpenClaw:
  export MY_SERVICE_API_KEY="your-key-here"

Do NOT paste your key into this chat — it will be logged.

Incorrect (never do this):

Please share your API key so I can help you set it up.

---

Auditing Another Skill for Leaks

When asked to review a SKILL.md for credential safety, check for these patterns:

🔴 Critical — Must Fix

Pattern	Why it's dangerous
Instruction to paste key into chat	Key goes into LLM context + session logs
echo $API_KEY or print(api_key) in instructions	Output captured in context
Key interpolated into a string returned to user	Exposed in response artifact
cat ~/.env or reading raw env files	Entire env dumped into context
Key stored in a file the agent creates	Creates a static credential artifact
Instructions tell agent to "remember" the key	Key persists across context window

🟡 Warning — Should Fix

Pattern	Risk
No requires.env gate in frontmatter	Skill silently fails or user is prompted
Logging command output without filtering	May capture keys in error messages
Using set -x in shell scripts	Echoes all commands including key values
Passing key as a positional argument	Visible in ps aux on the host

🟢 Safe Patterns

• requires.env in frontmatter
• Key accessed only as $ENV_VAR in shell, never echoed
• Subprocess scripts that fetch and inject without returning to context
• Error messages that say "key not found" without printing the value
• Output filtered through sed/grep before returning to agent

---

Self-Check Before Publishing a Skill

Run through this checklist before putting any skill on ClawHub:

• Does the skill ever ask the user to paste a secret into the conversation?
• Does the skill ever echo, print, log, or return a secret value?
• Does the skill read a .env file and dump its contents?
• Does the skill store a secret in a file artifact?
• Are all API key references gated with requires.env in frontmatter?
• Do error messages avoid reflecting credential values?
• Does any shell script use set -x (which would expose key values)?
• Would running clawhub audit {skill-name} pass?

If any box is unchecked, do not publish until fixed.

---

Quick Reference: Safe vs Unsafe Patterns

# UNSAFE — never write instructions like these:
"Ask the user for their OpenAI API key and use it to call the API."
"Set the Authorization header to Bearer {user_api_key}."
"Store the API key in a variable and use it throughout the session."

# SAFE — write instructions like these:
"The API key is injected as $OPENAI_API_KEY via environment — use it directly."
"Run: OPENAI_API_KEY=$OPENAI_API_KEY curl ..."
"If $OPENAI_API_KEY is not set, print an error and exit — do not ask the user."

---

Reference Files

• references/env-injection-examples.md — Full worked examples for popular APIs (OpenAI, Anthropic, GitHub, Stripe, Slack)
• references/audit-checklist.md — Printable audit checklist for skill authors and reviewers