Agent Secret - Secure Secret Management
This skill enables you to manage secrets securely using the OS keychain. Values are never exposed in terminal output.
Supported Files
Works with files containing .env in the name (e.g., .env, .env.local, .env.prod).
Core Concepts
1. Secret Name vs. File Key
Understanding this distinction is critical:
- Stored Secret: How it's saved in the keychain (e.g.,
PROJECTX_STRIPE_KEY) - File Key: How it appears in the.env file (e.g.,
STRIPE_KEY) - Mapping: Use
STORED_NAME:FILE_KEYto bridge them.
- agent-secret inject PROJECTX_STRIPE_KEY:STRIPE_KEY
2. Intelligent Secret Matching
CRITICAL: Be smart about matching user requests to stored secrets.
Prefix Handling: Secret names often have project prefixes: TRAVELER_GOOGLE_MAPS_KEY. When checking or injecting, usually remove the prefix for the file key: GOOGLE_MAPS_KEY.
Service Matching: Match user mentions to secret names (fuzzy):
| User says | Look for secrets containing |
|---|---|
| "google", "maps" | GOOGLE_MAPS |
| "stripe" | STRIPE |
| "supabase" | SUPABASE |
| "aws" | AWS |
| "db", "database" | DATABASE, DB |
| "openai" | OPENAI |
Command Reference
Store & Manage
agent-secret set <NAME>: Prompts for secret value (hidden input).agent-secret list: Lists names of all stored secrets.agent-secret delete <NAME>: Removes a secret.
Check & Verify
agent-secret check <KEY> [-f file] [-q]: Verifies if a key exists in the file.
- -q (quiet): Returns exit code only (0=found, 1=missing). Useful for logic checks.
agent-secret check --list [-f file]: Lists all keys present in the target.env file.
Inject (Write)
agent-secret inject <SPEC>... [-f file]: Injects secrets into a file.
- Simple: inject API_KEY (Stored name == File key) - Mapped: inject PROJECT_API_KEY:API_KEY (Stored name!= File key) - Multiple: inject KEY1 KEY2 PROJECT_KEY3:KEY3
Operating Workflows
1. Smart Discovery (User mentions service)
User: "Add google maps to.env"
- List first: Run
agent-secret listto see what's available. - Match: Find
TRAVELER_GOOGLE_MAPS_KEY. - Inject: Remove prefix and inject.
agent-secret inject TRAVELER_GOOGLE_MAPS_KEY:GOOGLE_MAPS_KEY -f.env
2. Checking Prerequisites
Before running commands that need secrets, verify they exist silently.
agent-secret check DATABASE_URL -q || echo "Missing DATABASE_URL"3. Setting Up New Projects
- Store: Ask user to set secrets first.
agent-secret set PROJECT_API_KEY - Inject: Write to the project file.
agent-secret inject PROJECT_API_KEY:API_KEY -f.env
4. Missing Secrets
If a secret is missing (check fails):
- Inform user: "Secret
XYZis not stored." - Provide command: "Run
agent-secret set XYZ." - Wait for user action.
Rules of Engagement
- Never expose values: Do not read or print secret values.
- Always List First: Don't guess secret names; check
listoutput. - Use Mappings: Standardize.env keys by stripping project prefixes.
- Feedback: Report "Configured" or "Missing", not the content.