symaira-agent
starsforks
How to install symaira-agent?
danieljustus/symaira-vault/symaira-agent
$npx -y skills add danieljustus/symaira-vault --skill symaira-agentUse Symaira Vault as the credential manager for AI agents through native MCP tools. Prefer this when storing, retrieving, generating, or rotating passwords, tokens, API keys, and TOTP codes.
SKILL.md
| 1 | # Symaira Vault |
| 2 | |
| 3 | Symaira Vault is the credential store. Use native MCP tools when they are available. |
| 4 | Do not use terminal commands for credential reads or writes unless the user |
| 5 | explicitly asks for CLI debugging. |
| 6 | |
| 7 | ## Preferred Tools |
| 8 | |
| 9 | Canonical Symaira Vault MCP tool names: |
| 10 | |
| 11 | - `list_entries` |
| 12 | - `find_entries` |
| 13 | - `get_entry` |
| 14 | - `get_entry_metadata` — Get entry metadata (created, updated, version) without sensitive data |
| 15 | - `set_entry_field` |
| 16 | - `generate_password` |
| 17 | - `generate_totp` |
| 18 | - `delete_entry` |
| 19 | - `symaira_delete` (deprecated alias for `delete_entry`) |
| 20 | - `execute_with_secret` — Run a shell command with a vault secret injected as an |
| 21 | environment variable. The secret value never appears in the command string, |
| 22 | argv, or chat transcript. |
| 23 | - `execute_api_request` — Make an authenticated HTTP request using a stored |
| 24 | secret (API key, PAT, bearer token). The secret is attached by the server and |
| 25 | never revealed to the agent. |
| 26 | |
| 27 | Some MCP clients prepend a namespace (for example `mcp_symaira_list_entries`). |
| 28 | If canonical names are unavailable, inspect the client's MCP tool list and map |
| 29 | to these equivalents. |
| 30 | |
| 31 | ### Safe API Request Example |
| 32 | |
| 33 | To call the GitHub API with a stored PAT, use `execute_api_request`: |
| 34 | |
| 35 | ```json |
| 36 | { |
| 37 | "template": "github", |
| 38 | "endpoint": "/repos/owner/repo/issues", |
| 39 | "method": "GET" |
| 40 | } |
| 41 | ``` |
| 42 | |
| 43 | Do NOT call `get_entry_value` followed by curl — this exposes the token |
| 44 | in the chat transcript. |
| 45 | |
| 46 | ### Anti-pattern: Manual secret exposure |
| 47 | |
| 48 | Never pass a secret as an argv argument or echo it in a shell command. |
| 49 | Use the secret-injecting tools so the value lives only in env vars of |
| 50 | the spawned subprocess. |
| 51 | |
| 52 | ## Cache Validation for Credential Sync |
| 53 | |
| 54 | For agents that cache credentials locally, use `get_entry_metadata` to validate |
| 55 | cache freshness before fetching full entries: |
| 56 | |
| 57 | 1. Cache the entry version when first retrieving a credential |
| 58 | 2. Before using a cached credential, call `get_entry_metadata` to get the current version |
| 59 | 3. If versions differ, the credential was updated — fetch fresh data with `get_entry` |
| 60 | 4. This prevents using stale credentials that may cause HTTP 401 errors |
| 61 | |
| 62 | Example workflow for API key management: |
| 63 | ``` |
| 64 | 1. Get metadata: get_entry_metadata(path="api/kimi-key") |
| 65 | → {version: 5, updated: "2026-04-21T09:45:00Z"} |
| 66 | |
| 67 | 2. Compare with cached version |
| 68 | → If cached version < 5, fetch fresh: get_entry(path="api/kimi-key") |
| 69 | |
| 70 | 3. Use fresh credential for API call |
| 71 | → If 401 error still occurs, credential is truly invalid (not just stale) |
| 72 | ``` |
| 73 | |
| 74 | ## Usage Rules |
| 75 | |
| 76 | - Search or list before reading if the exact path is unknown. |
| 77 | - Read only the entry needed for the task. |
| 78 | - Write credentials with `set_entry_field`; keep paths stable and descriptive. |
| 79 | - Generate passwords with `generate_password` instead of inventing them. |
| 80 | - Generate TOTP codes with `generate_totp`; do not expose the stored TOTP secret. |
| 81 | - Do not echo secrets, tokens, or passphrases in chat unless the user explicitly |
| 82 | asks to reveal them. |
| 83 | - Prefer dedicated agent profiles such as `hermes` or `openclaw` over a shared |
| 84 | human CLI profile. |
| 85 | |
| 86 | ## Missing Credentials |
| 87 | |
| 88 | If a task requires a credential that is not in the vault (e.g. `find_entries` or |
| 89 | `get_entry` returns nothing for an expected path), do NOT ask the user to type |
| 90 | the secret in chat. Call the `request_credential` MCP tool instead: |
| 91 | |
| 92 | - `path`: where the credential should live (e.g. `github/api-token`) |
| 93 | - `field`: which field (`token`, `password`, `api_key`, …) |
| 94 | - `reason`: a one-sentence human-readable reason — this is shown verbatim in |
| 95 | the dialog the user sees |
| 96 | |
| 97 | Symaira Vault opens a native dialog (TTY box on terminal-attached runs, OS-native |
| 98 | popup otherwise). The user types the value; you receive only a confirmation, |
| 99 | never the value itself. Continue the task afterwards using `execute_with_secret`, |
| 100 | `copy_to_clipboard`, or `autotype` — never re-derive or re-print the secret. |
| 101 | |
| 102 | ## Expected Entry Shape |
| 103 | |
| 104 | Entries are JSON-like objects. Common fields: |
| 105 | |
| 106 | - `username` |
| 107 | - `password` |
| 108 | - `url` |
| 109 | - `notes` |
| 110 | - `totp` |
| 111 | |
| 112 | For TOTP setup, `totp` is a JSON object containing the TOTP configuration. For |
| 113 | one-time codes, call `generate_totp` instead of reading the TOTP secret. |
| 114 | |
| 115 | ## Troubleshooting |
| 116 | |
| 117 | - If tools are missing, ask the user to run `hermes mcp test symvault` or the |
| 118 | equivalent MCP discovery command for their agent. |
| 119 | - If writes are denied, check the Symaira Vault agent profile: `canWrite` must be |
| 120 | `true` and `approvalMode` should be `none` for non-interactive agents. |
| 121 | - If terminal commands are blocked by the agent security policy, keep using MCP; |
| 122 | the terminal policy should not be loosened for normal credential work. |
People who liked this also viewed
6 picksType
- entra-app-registrationGuides Microsoft Entra ID app registration, OAuth 2.0 authentication, and MSAL integration. USE FOR: create app registration, register Azure AD app, configure OAuth, set up authentication, add API perSkillsJul 2026
- azure-complianceRun Azure compliance and security audits with azqr plus Key Vault expiration checks. Covers best-practice assessment, resource review, policy/compliance validation, and security posture checks. WHEN: SkillsJul 2026
- azure-rbacOfficial agent plugin providing skills and MCP server configurations for Azure scenarios.SkillsJul 2026
- better-auth-best-practicesAgent skill from better-auth/skillsSkillsJul 2026
- firebase-security-rules-auditorA skill to evaluate how secure Firestore security rules are. Use this when Firestore security rules are updated to ensure that the generated rules are extremely secure and robust.SkillsJul 2026
- audit-websiteAudit a website with the squirrelscan CLI and fix the findings in code. Runs SEO, performance, security, technical, content, accessibility, and 15 other rule categories (260+ rules), returns an LLM-opSkillsJul 2026
