How to use the Infisical Sync Expert agent skill

What the Infisical Sync Expert skill makes the agent do

An agent skill is a folder of instructions that an AI agent loads when a task matches it. This one holds expert knowledge for the Infisical Sync Hand, a dedicated sync agent in the OpenFang project. The skill covers the Infisical API, the local encrypted vault, and the steps to follow when something fails.

With the skill installed, the agent knows how to log in with machine credentials using Universal Auth, list secrets in a project and environment, create or update and delete secrets, and read HTTP error codes. It also describes how to keep a local vault in step with an Infisical project, detect changes by hashing key and value pairs, and run a security checklist before each sync cycle.

• Authenticate with a Machine Identity using Universal Auth
• List, create, update and delete secrets through the Infisical API
• Pull secrets into the local vault and optionally remove keys that no longer exist upstream
• Detect changes with SHA-256 hashes instead of storing values
• Follow a pre-sync security checklist and a table of HTTP error responses

Install the skill from the ZIP or the Claude apps

Download the ZIP of the skill from this page. The item contains two files, HAND.toml and SKILL.md. Choose one of the install routes below.

For a personal setup, unzip the download into ~/.claude/skills/ so the skill is available across your projects. For a single project, unzip it into that project's .claude/skills/ folder so it applies only there. In the Claude apps, you can instead upload the ZIP under Settings → Capabilities → Skills.

• Personal install: unzip into ~/.claude/skills/
• Project install: unzip into the project's .claude/skills/ folder
• Claude apps: upload the ZIP under Settings → Capabilities → Skills

What you need before the skill can work

The skill is useless without a working Infisical account, so set these up first. You need a self-hosted Infisical instance, with its base URL stored in INFISICAL_URL, for example an address of the form https://infisical.example.com in the source. You also need a Machine Identity with Universal Auth, which provides INFISICAL_CLIENT_ID and INFISICAL_CLIENT_SECRET, plus the project ID and the environment slug such as prod, staging or dev.

On the machine running the agent, the source expects curl, python3 and sha256sum in the shell. OpenFang's local vault tools (vault_set, vault_get, vault_list, vault_delete) and shell_exec must also be available, because the skill's operations depend on them.

• INFISICAL_URL pointing at your self-hosted instance
• INFISICAL_CLIENT_ID and INFISICAL_CLIENT_SECRET from a Universal Auth Machine Identity
• Project ID and environment slug
• curl, python3 and sha256sum in the shell
• OpenFang vault tools and shell_exec

Run a first login and list secrets

The skill logs in with a POST to the Universal Auth login endpoint, reads the accessToken from the response, and sends it as a Bearer token on later requests. The source says tokens last expiresIn seconds, usually 7200 (two hours), so the agent should re-authenticate when a token expires. Listing secrets uses GET on the secrets endpoint with projectId and environment as required query parameters.

Ask the agent for a read-only task first, such as listing the keys in one environment. This confirms that the URL, credentials and permissions are correct before you try any writes.

How to trigger the skill with natural requests

The skill does not define fixed trigger phrases. Describe the job in ordinary words and name the project and environment, and the agent can match the request to the expert notes. Good requests say what you want, where it lives, and where it should end up.

Keep requests narrow. Asking for one environment's secrets to be pulled into the vault is easier to check than asking for everything at once. Ask for a summary of what changed, not for the values themselves.

• Pull all secrets from the prod environment of project ID X into the local vault and report how many keys changed.
• List the keys in the staging environment, without values, and tell me which ones are missing from the vault.
• Check whether DATABASE_URL in dev has changed since the last sync, using the stored hashes.
• Create or update the secret API_TIMEOUT in staging with the value I give you in the next message.
• Remove vault keys that no longer exist in the prod environment in Infisical.

Safety notes before you run a sync

Read this section before you enable the skill. The skill runs scripts and uses the network. Its examples place secret values into shell commands, and they write API responses to a temporary file at /tmp/infisical_response.json. Those routes can expose values through shell history, process lists or files on disk, so do not use the skill where that exposure is unacceptable.

The source's own checklist asks the agent to confirm the three environment variables are set, to get a fresh token on every cycle, to avoid echoing values inline, and to strip secretValue fields before logging any response. Do not ask the agent to print or paste secrets into chat or logs.

• Use a Machine Identity with the least access needed, such as viewer for read-only work
• Do not paste secret values into chat, and do not ask for them to be printed
• Treat /tmp/infisical_response.json as sensitive and remove it when finished
• Run the checklist before every sync cycle

Fix common errors

The skill maps HTTP codes to actions. A 401 means the token may have expired, so re-authenticate. A 403 means the Machine Identity lacks permission on the project. A 404 means the secret or project does not exist. A 429 means you are rate limited, so wait 60 seconds and retry once. A 500 or 503 means a server problem, so retry once after 30 seconds.

The source's common failure modes include a 403 Forbidden error, which it fixes by opening Access Control, then Machine Identities, then assigning the identity the member role, or viewer for read-only. For a connection refused error, the source suggests checking the instance's status endpoint at $INFISICAL_URL/api/status. Secret names must match [A-Z0-9_].

• 401: re-authenticate and retry
• 403: assign the Machine Identity the member or viewer role on the project
• 404: confirm the secret name, project ID and environment
• 429: wait 60 seconds and retry once
• 500 or 503: retry once after 30 seconds, then report