Skip to main content
A skill is a folder containing a SKILL.md file with metadata and instructions that tell an agent how to perform a specific task. If you add a skill to an access bundle, the CLI installs the skill any time you run infisical agent-vault run with that access bundle. You can also give a session skills from the project one by one, or send skills with the session.
Skills follow the Agent Skills format, so the same folder works in Claude Code, Codex, and any other agents that support it.

Prerequisites

  • The Admin role in your Agent Vault project, 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 (you can’t use infisical-agent-vault, the name of Agent Vault’s built-in skill)
  • 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.
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

An agent can run a script directly only if the script is executable. Infisical keeps a script executable in these cases:
  • If you push the skill with the CLI, even after you edit the skill or upload a new version in Infisical
  • If you upload a zipped folder in which the script is executable
  • If you make the script executable in the editor: right-click the file or select its three-dot button, then select Make Executable
Windows doesn’t mark files as executable, so if you work on Windows, push from WSL or CI instead. Otherwise, have SKILL.md tell the agent to run each script with an interpreter, such as bash scripts/check.sh.

Limits

  • Up to 50 files in a skill
  • Up to 256 KB for each file
  • Up to 1 MB for all the files in a skill
  • Up to 250 skills in an Agent Vault project
  • Up to 25 skills in an access bundle
If you self-host Infisical behind a reverse proxy or load balancer, set its request body limit to at least 2 MB so that skill uploads go through.

Manage skills

Add a skill

Log in to the CLI as an admin of the Agent Vault project, then run infisical agent-vault skills push on the host that has the skill folder, replacing <project-id> with the project’s ID:
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.

View a skill

To open a skill, go to Skills in your Agent Vault project 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 a member of the project rather than an admin, open the skill from an access bundle that’s granted to you. The Skills page is only for admins. With the CLI, run infisical agent-vault skills get to list the skills you can see, or pass a skill’s name to see its files. 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. To download the files to a folder with the CLI instead, run infisical agent-vault skills pull.
The review-guidelines skill in a side panel, with its files on the left and a preview of SKILL.md on the right

Edit a skill

To change a skill’s files in Infisical:
1
In your Agent Vault project, go to Skills and select the skill. To edit a Markdown file, select Code.
The review-guidelines skill with SKILL.md open in the code editor, and Discard and Save Version buttons at the bottom
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

If you don’t have the skill folder on this host, download it with infisical agent-vault skills pull:
pull and push skip hidden files, so a skill’s hidden files are lost if you pull it and push it again.Change the files in the skill folder, then push the folder again:
The name in SKILL.md must stay the same, or the CLI creates a new skill instead. If the files match the skill’s latest version, the CLI prints unchanged and doesn’t save a version.

Rename a skill

To rename a skill, change the name in its SKILL.md, then save the change or upload the new SKILL.md. Agents that start after the rename get the skill under its new name.

Restore a previous version

To roll a skill back:
1
In your Agent Vault project, 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.
The Version History dialog of the review-guidelines skill, listing versions v3 (Latest), v2, and v1 with a Roll Back button for each older version
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:
Run infisical agent-vault skills delete with the skill’s name and the project’s ID, then type the name when the CLI asks. The command needs --project-id on the command line, even if you’ve set the project in an environment variable:
To delete the skill from a script or an agent, pass --yes to skip the question.
Infisical removes the skill from every access bundle and every session that has it.
The CLI doesn’t delete copies of the skill that were already installed. To stop agents from using the skill, delete the installed copies from each device.

Access bundles

To install skills for agents, add them to an access bundle.

Add a skill to an access bundle

1
In your Agent Vault project, 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 Add Skill, or Add 2 Skills if you picked two. To create a skill instead, select Create New Skill at the end of the list. Infisical adds the new skill to the access bundle when you create it.
The Add Skills dialog of the code-review access bundle, with a list of the incident-triage and release-notes-writer skills and Create New Skill at the end
To add skills through the API, call the Add skills to access bundle endpoint.

Remove a skill from an access bundle

In the access bundle’s Skills section, open the skill’s actions menu 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.

Sessions

Instead of an access bundle, or alongside it, you can give a session skills from the project and send skills with the session. An agent that you start with the session gets these skills along with the access bundle’s. Infisical shows skills sent with a session as inline skills, both in the sessions table and under Inline Skills in the session’s details.

Pick skills from the project

When you create a session, pick skills under Skills, or list their names in skills through the API. Admins of the project can pick any of its skills. Anyone else can pick only the skills in the access bundles granted to them, directly or through a group. Each time an agent starts with the session, it gets the latest version of each skill you picked. If the user or machine identity that created the session loses access to a skill, or someone deletes the skill, agents that start afterwards don’t get it.

Send skills with a session

To give one session a skill that you don’t keep in the project, send the skill’s files in skills when you call the Create session endpoint. Each skill takes the same files as the Create skill endpoint, and Infisical reads the skill’s name and description from its SKILL.md:
Anyone who can create a session can send skills with it, within these limits:
  • A session can have up to 20 skills from the project and up to 5 skills sent with it
  • The files of all the skills you send share the request’s 2 MB limit
  • Each name can appear only once in skills (if a name repeats, the request fails with a 422 error that includes the name)
  • A skill you send can’t have the same name as a skill in the session’s access bundle (if it does, the request fails with a 400 error that names the skill and the access bundle)
If someone later adds a skill to the access bundle with the same name as a skill you sent, or renames a skill in the access bundle to that name, agents that start with the session afterwards get the access bundle’s skill instead of yours. The skills you send belong to that session only, and nobody can edit them. Infisical deletes their files when the session is revoked, or within an hour after it expires.

Skill installation

When you start an agent with infisical agent-vault run, the CLI gets the session’s skills through the proxy and installs them before the agent starts: the latest version of each skill in the session’s access bundle and of each skill picked from the project, and the skills sent with the session. It also installs Agent Vault’s built-in skill:
If the CLI can’t download or install the skills, it still starts the agent and prints the reason.
If you publish a new version or add a skill to the access bundle, restart the agent to pick up the change. If you start another agent on the same host, the CLI also updates the skills there, including for agents that are already running.

Skill folders

The CLI installs the skills in these folders: In the Claude Code and Hermes folders, the CLI links each skill to its copy in ~/.agents/skills. If the CLI can’t create links, it copies the skill’s folder instead. This can happen on Windows, where creating links requires extra permissions.
To install the skills in a different folder, pass --skills-dir with the folder’s path.

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 from one
  • Opens a version of a skill
When the CLI gets a session’s skills, Infisical writes one event for the session that lists the version and SHA-256 checksum of each skill, and the access bundle each one came from (none for a skill picked from the project or sent with the session), so you can see which version each agent got. If the CLI got the skills through the proxy, the event shows the proxy’s IP address. To review these events, open Audit Logs in your Agent Vault project, or scope an audit log stream to the Agent Vault product.

Limitations

  • Installed skills stay on the host: The CLI doesn’t delete the skills it installs, so agents on the host can keep using a skill after the agent exits, or after you remove the skill from the access bundle, delete it, or rename it
  • Folders the CLI didn’t install: If a folder with the same name as a skill already exists and the CLI didn’t install it, the CLI leaves the folder alone and warns you
  • Proxies on an older Infisical CLI: If the proxy can’t pass skills on, the CLI downloads them from Infisical directly, so the agent’s host needs to reach your Infisical instance until you update the CLI that runs the proxy (if you use EU Cloud or self-host Infisical, also pass your instance’s URL with --domain when you start the agent with a session token)