doc/user/duo_agent_platform/customize/agent_skills.md
{{< details >}}
{{< /details >}}
{{< history >}}
{{< /history >}}
GitLab Duo supports the Agent Skills specification, an emerging standard for giving agents new capabilities and expertise.
Use Agent Skills to give agents specialized knowledge and workflows for specific tasks, like writing tests in a specific framework. Agents load the related skills automatically as they encounter tasks and use the information as they work.
When you specify a SKILL.md file, the skills are available for GitLab Duo Agent Platform and any
other AI tool that supports the specification.
Specify Agent Skills for GitLab Duo to use with:
User-level skills are only available for use with the GitLab Duo CLI.
When an agent starts working, GitLab Duo adds metadata for all available skills to the agent's context. When the agent encounters a task that matches a skill's description, it automatically loads the skill and uses it to complete the task.
You can also manually direct GitLab Duo to use a skill by name, file path, or slash command.
GitLab Duo supports the following types of skills:
| Level | GitLab UI | Editor extensions | GitLab Duo CLI |
|---|---|---|---|
| User-level: Apply to all of your projects | {{< no >}} | {{< no >}} | {{< yes >}} |
| Project-level: Apply only to a specific project | {{< yes >}} <sup>1</sup> | {{< yes >}} | {{< yes >}} |
Footnotes:
[!note] Existing conversations and flows do not have access to new or updated skills automatically. Start a new conversation, or ask GitLab Duo to load a skill by name or relative path.
Meet the Agent Platform prerequisites.
For GitLab Duo Chat in your local environment, install and configure one of the following:
For project-level skills with custom flows, update the flow's configuration file to access the
workspace_agent_skills context passed from the executor:
components:
- name: "my_agent"
type: AgentComponent
prompt_id: "my_prompt"
inputs:
- from: "context:inputs.workspace_agent_skills"
as: "workspace_agent_skills"
optional: true
By setting optional: true, the flow gracefully handles cases where no agent skills exist.
The agent works with or without additional context.
You can create skills at the project level or user level.
If you use a multi-root workspace in your IDE, you can create project-level skills for each project in the workspace.
If a user-level skill and a project-level skill share the same name, the project-level skill takes precedence. This allows you to override a user-level skill with a project-specific version.
In a multi-root workspace, if multiple projects define skills with the same name, GitLab Duo loads the first one it encounters.
Project-level skills apply to a specific project. You define them in a SKILL.md
file in a skills/<skill-name>/ directory of your project.
To create a project-level skill:
In the root of your project, create a skills directory.
In the new directory, create another directory for the specific skill. Use the skill name as the directory name.
Create a SKILL.md file and include instructions using the following format.
The name and description YAML front matter fields are required.
---
name: <skill_name>
description: <skill_description>
---
<your_instructions_and_context_for_the_skill>
For example, a skill to sign artifacts using cosign in
skills/cosign-blob/SKILL.md:
---
name: cosign-blob
description: Sign artifacts using cosign with local keypairs and Sigstore v3 bundles. Integrate with 1Password for secure key management.
---
## Cosign Blob Signing
Sign artifacts locally using cosign with Sigstore v3 bundles for artifact verification and integrity.
### Generate a Local Keypair
Generate a new cosign keypair:
```shell
cosign generate-key-pair
```
This creates two files:
- `cosign.key` - Private key (encrypted)
- `cosign.pub` - Public key
Store the private key securely, preferably in a password manager like 1Password.
### Store Private Key in 1Password
1. Create a new login item in 1Password with:
- Title: "Duo Skills cosign"
- Username: (optional)
- Password: Your cosign private key password
2. Save the secret reference path (for example, `op://Employee/Duo Skills cosign/password`)
### Sign Artifacts with Cosign
Sign a file and generate a Sigstore v3 bundle:
```shell
COSIGN_PASSWORD=$(op read "op://Employee/Duo Skills cosign/password") \
timeout -v 4 cosign sign-blob \
--key ~/.gitlab/duo/cosign.key \
--bundle <filename>.bundle \
--new-bundle-format \
--yes \
<filename>
```
Replace:
- `<filename>` with the file to sign (for example, `SKILL.md`)
- The bundle output will be saved as `<filename>.bundle`
### Key Points
- Use timeout to fail-fast and report the error back to the user.
- Use `--bundle` with `$file.bundle` format for Sigstore v3 bundles
- Use `--yes` to skip interactive prompts
- Use `--new-bundle-format` to output a v3 Sigstore bundle rather than the legacy format
- Set `COSIGN_PASSWORD` environment variable to avoid password prompts
- Integrate with 1Password CLI for secure credential management
- The bundle file contains the signature and can be verified later
Save the file.
Start a new conversation or flow. You should do this every time you change or add a SKILL.md
file to avoid context confusion for the agent.
{{< details >}}
{{< /details >}}
User-level skills apply across all of your projects. You define them in a SKILL.md file in a
skills/<skill-name>/ directory within your home directory.
User-level skills are only available for use with the GitLab Duo CLI.
You can create a skills directory in one of the following locations:
~/.gitlab/duo/skills/.%APPDATA%\GitLab\duo\skills\.GLAB_CONFIG_DIR or XDG_CONFIG_HOME, use $GLAB_CONFIG_DIR/skills/ or $XDG_CONFIG_HOME/gitlab/duo/skills/. If both are set, GLAB_CONFIG_DIR takes priority.~/.agents/skills/.%USERPROFILE%\.agents\skills\.To create a user-level skill:
Enable global skills when starting the GitLab Duo CLI:
{{< tabs >}}
{{< tab title="glab" >}}
glab duo cli --enable-global-skills
{{< /tab >}}
{{< tab title="duo" >}}
duo --enable-global-skills
{{< /tab >}}
{{< /tabs >}}
Alternatively, set the environment variable:
export GITLAB_ENABLE_GLOBAL_SKILLS=true
In your skills directory, create another directory for the specific skill.
Use the skill name as the directory name. For example, ~/.gitlab/duo/skills/<skill_name>/.
Create a SKILL.md file and include instructions using the following format.
The name and description YAML front matter fields are required.
---
name: <skill_name>
description: <skill_description>
---
<your_instructions_and_context_for_the_skill>
Start a new conversation. The skill is available in any project.
To enable a skill as a custom slash command, add slash-command: enabled to the metadata in the
YAML front matter of your SKILL.md file:
---
name: <skill_name>
description: <skill_description>
metadata:
slash-command: enabled
---
After you add the metadata, you can use /<skill_name> in new sessions to instruct GitLab Duo to use the
skill. For example, /fix-bugs.
To direct GitLab Duo to use a specific skill, use one of the following methods:
To list all available skills in the current session's context, use /skills.