Skip to main content
A skill is a folder of instructions that an AI agent loads when a task needs it, such as how your team reviews pull requests or how to cut a release. Skills follow the Agent Skills format, so the same folder works in Claude Code, Codex, and other agents that support it. An access bundle defines the services, such as external APIs or MCP servers, that an agent can access during a session. If you add a skill to an access bundle, the CLI installs the skill for each agent that you start with that access bundle through infisical agent-vault run. Agents that use the proxy without infisical agent-vault run, such as the Hermes gateway and OpenClaw gateway setups, don’t get skills.
Agent Vault members can view the latest version of each skill in the access bundles granted to them.

​
Prerequisites

  • The Admin role in Agent Vault, to add, change, and delete skills, and to add them to access bundles
  • The Infisical CLI on each host where you start agents

​
Skill format

A skill is a folder with a SKILL.md file at its root. SKILL.md starts with a header that names and describes the skill, followed by the instructions in Markdown:
  • name: the name agents know the skill by, with up to 64 lowercase letters, numbers, and single hyphens, not starting or ending with a hyphen
  • description: the text an agent reads to decide when to use the skill (up to 1,024 characters)
The folder can also hold other files that the instructions refer to, such as scripts, templates, or reference documents. Each skill can hold:
  • Up to 50 files
  • Up to 256 KB per file
  • Up to 1 MB in total
If you self-host Infisical behind your own proxy, allow request bodies of at least 2 MB. Each organization can have up to 250 skills.
Don’t put API keys, tokens, or other secrets in a skill. Anyone with a session token can download the session’s skills, and the CLI saves them as plain files on each agent’s host. To let an agent use a credential, add the credential to a service instead.

​
Scripts in a skill

If you push a skill with the CLI, its scripts stay executable, even after you edit the skill or upload a new version in Infisical. A zipped folder that you upload also keeps its executable files. To make a file executable in the editor, right-click it or select its three-dot button, then select Make Executable. From Windows, push from WSL or CI, or have SKILL.md tell the agent to run each script with an interpreter, such as bash scripts/check.sh.

​
Add a skill

You can push a skill folder with the CLI, or create the skill in Infisical.
Log in to the CLI as an Agent Vault admin, then run the following command on the host that has the skill folder:
The CLI finds the skill by the name in SKILL.md. It creates the skill if it doesn’t exist yet, and adds a new version if it does.In a script or CI, authenticate as a machine identity with the Admin role in Agent Vault, in one of these ways:
  • Pass --client-id and --client-secret
  • Set INFISICAL_UNIVERSAL_AUTH_CLIENT_ID and INFISICAL_UNIVERSAL_AUTH_CLIENT_SECRET
  • Set INFISICAL_TOKEN to the identity’s access token
For the flags, see infisical agent-vault skills push.

​
Add a skill to an access bundle

To install skills for agents, add them to an access bundle:
1
In Agent Vault, go to Access Bundles and select the access bundle.
2
In the Skills section, select Add Skills.
3
Pick one or more skills from the list, then select the Add button. You can also create a skill from here with Create New Skill at the end of the list, and it’s added to the access bundle.
An access bundle can have up to 25 skills. To remove a skill from an access bundle, open its actions menu in the Skills section and select Remove From Bundle, then type the skill’s name and select Remove. The CLI doesn’t delete copies of the skill that it already installed, so to stop agents from using the skill, delete the installed copies.

​
How agents get skills

When you start an agent with infisical agent-vault run, the CLI downloads the latest version of each skill in the session’s access bundle, and installs the skills before the agent starts. If you publish a new version or add a skill to the access bundle, restart the agent to pick up the change. Starting another agent on the same host also updates the skills there, including for agents already running.

​
Reaching Infisical from the agent’s host

The CLI downloads the skills from Infisical with the session’s token, so the agent’s host needs to reach your Infisical instance:
  • If the host can’t reach Infisical, or you don’t want skills, pass --no-skills to start the agent without them
  • If you start the agent with a session token and you use EU Cloud or self-host Infisical, pass your instance’s URL to the CLI with --domain

​
Where the CLI installs skills

The CLI installs each skill in ~/.agents/skills/<skill-name>, where Codex, OpenCode, and OpenClaw look for skills. The CLI also links each skill into the skills folder of Claude Code and of Hermes, if that agent’s folder exists on the host. If the agent’s command is claude, the CLI links the skills for Claude Code even if its folder doesn’t exist yet:
  • Claude Code: $CLAUDE_CONFIG_DIR, or ~/.claude if CLAUDE_CONFIG_DIR isn’t set
  • Hermes: $HERMES_HOME, or ~/.hermes if HERMES_HOME isn’t set
If the CLI can’t create links on the host, such as on Windows without permission to create symbolic links, it copies the skill’s folder instead. To install the skills in a different folder, pass --skills-dir with the folder’s path. The CLI then installs the skills only in that folder.

​
Hermes and OpenClaw profiles

In some setups, Hermes and OpenClaw don’t read the folders that the CLI installs skills in:
  • If you run Hermes with a profile, or on Windows, Hermes doesn’t read ~/.hermes/skills, so add ~/.agents/skills to skills.external_dirs in the config.yaml that Hermes uses
  • If you run OpenClaw with OPENCLAW_PROFILE or OPENCLAW_STATE_DIR set, OpenClaw doesn’t read ~/.agents/skills, so pass --skills-dir with the skills folder in OpenClaw’s state folder
For Hermes, the setting in config.yaml looks like this:

​
Installed skills stay on the host

The CLI doesn’t delete the skills it installs when the agent exits, so later runs of any agent on the host can still use them.
The CLI only replaces skill folders it installed. If a folder with the same name as a skill in the access bundle already exists and the CLI didn’t install it, the CLI leaves it alone and warns you.

​
Remove installed skills

If you remove a skill from an access bundle, delete it, or rename it, the CLI doesn’t delete the copies it already installed. On each host that ran an agent with the skill, delete the skill’s folder from ~/.agents/skills, or from the folder you passed to --skills-dir. Also delete the skill’s link or copy from the Claude Code and Hermes skills folders, if the CLI created one there. If you renamed the skill, the installed folder has the skill’s old name.

​
If an agent starts without skills

The CLI always starts the agent, even if it can’t install the skills. If it can’t download or install them, it prints why the agent started without them.

​
Manage skills

​
View a skill

To open a skill, go to Skills in Agent Vault and select the skill. You can also open it from an access bundle: in the Skills section, open the skill’s actions menu and select View Skill. If you’re an Agent Vault member, open the skill from an access bundle that’s granted to you. The Skills page is only for admins. The skill opens in a side panel that shows the latest version of its files. To get a copy of the files, select Options in the panel, then select Download. Infisical downloads the files as a zip file, and scripts that are executable in Infisical stay executable.

​
Edit a skill

To change a skill’s files in Infisical:
1
In Agent Vault, go to Skills and select the skill. To edit a Markdown file, select Code.
2
Change the files in the editor, as described in Change the files.
3
Select Save Version at the bottom, check the changes to each file, and select Save Version again. To throw your changes away instead, select Discard.
Each time you save, push, or upload a skill with different files, Infisical saves the files as a new version. Infisical keeps the last 20 versions of each skill.

​
Change the files

The editor lists the skill’s files on the left and shows the selected file on the right:
  • To change a file, select the file and edit its content (for Markdown files, select Code first)
  • To add a file or a folder, select New File or New Folder, or right-click an empty part of the file list, then type the name and press Enter
  • To add a file or a folder inside a folder, right-click the folder or select its three-dot button, then select New File or New Folder
  • To rename or remove a file or a folder, right-click it or select its three-dot button, then select Rename, Delete File, or Delete Folder
You can’t rename or delete SKILL.md. The editor doesn’t show binary files, such as images, and keeps them as they are.

​
Upload a new version

To replace a skill’s files with a zipped folder or a Markdown file:
1
In Agent Vault, go to Skills and select the skill.
2
Select Options, then select Upload New Version, and drop the zipped folder or the Markdown file into the dialog.
3
Select Save Version.
A zipped folder replaces every file in the skill. A Markdown file replaces only SKILL.md and keeps the skill’s other files. You can also publish a new version from the CLI with infisical agent-vault skills push.

​
Rename a skill

To rename a skill, change the name in its SKILL.md, then save the change or upload the new SKILL.md. You can’t rename a skill with the CLI. If you push a folder whose SKILL.md has a new name, the CLI creates a new skill with that name. Agents that start after the rename get the skill under its new name. The CLI doesn’t delete the copy it installed under the old name, so delete the installed copies on each host.

​
Restore a previous version

To roll a skill back:
1
In Agent Vault, go to Skills and select the skill.
2
Select Options, then select Version History.
3
Select the version you want, check its files, and select Roll Back. Select Roll Back again to confirm.
Infisical publishes a copy of that version as the new latest version. Agents that start after the rollback get that version. If the version you roll back to has the same files as the latest version, Infisical doesn’t create a new version. A rollback keeps the skill’s current name. If the older version has a different name, Infisical changes the name in that version’s SKILL.md to the current name.

​
Delete a skill

To delete a skill and every version of it:
1
In Agent Vault, go to Skills and select the skill.
2
Select Options, then select Delete Skill. The dialog lists the access bundles the skill is in.
3
Type the skill’s name and select Delete.
Infisical removes the skill from every access bundle. The CLI doesn’t delete copies of the skill that it already installed, so to stop agents from using the skill, delete the installed copies.

​
Audit trail

Infisical writes an audit event when someone creates, edits, renames, rolls back, or deletes a skill, adds a skill to an access bundle or removes it, or opens a version of a skill. When the CLI downloads a session’s skills, Infisical also writes one event for the session that lists each skill’s version and the version’s SHA-256 checksum, so you can see which version each agent got. To review these events, open Audit Logs in Agent Vault, or scope an audit log stream to the Agent Vault product.