Skip to main content
This topic explains how to use agent skills to create, manage, and attach reusable agent instructions across AgentControl config variations. Agent skills are reusable, versioned Markdown instruction files that you manage as standalone resources in LaunchDarkly. A skill defines a capability or behavior, such as how to review a pull request or how to extract data from a PDF, that an agent can load into its runtime environment. Unlike a prompt snippet, which is resolved inline into a message at evaluation time, a skill is delivered as a reference. Your application retrieves the skill and loads it into your agent’s runtime environment separately. Use agent skills to:
  • Centralize instruction sets that would otherwise live in source control or a model provider’s upload bucket.
  • Reuse the same skill across multiple agents and configs.
  • Identify which configs and variations use a specific skill.
  • Track updates to skill content by version.
  • Maintain governance and audit history over agent behavior.

​
How agent skills work

You manage agent skills from the Library under Agents. The skills library provides a centralized place to create, view, and update reusable agent instructions across your project. The following skill fields determine how you reference, update, and organize skills:
  • The key identifies the skill and lets you reference it when attaching it to a variation.
  • The version lets you update skill content without affecting existing variations.
  • Metadata, such as tags or maintainers, helps you organize skills across your project.
Skill content size limitLaunchDarkly limits each skill’s Markdown body to 50 KB.

​
Skill key requirements

When you create a skill, its key must meet the following requirements:
  • It contains only lowercase letters, numbers, and hyphens.
  • It starts with a lowercase letter or number.
  • It is 64 characters or fewer.
  • It is not a reserved Windows file name.
The reserved Windows file names are con, prn, aux, nul, com0 through com9, and lpt0 through lpt9. Longer keys that contain these names, such as console or com10, are allowed. These requirements let the AI SDKs load a skill and write it to disk as a directory named after its key. LaunchDarkly enforces them in the “Save skill” dialog and in the REST API. The REST API returns a 400 response for an invalid key. The requirements apply only to new skills. Existing skill keys do not change.

​
View skills

Use the skills list in the library to browse, search, and manage skills across your project. From the skills list, you can:
  • Display all skills in your project in a centralized list.
  • Search for skills by name, key, or content.
  • View skill details, including versions and usage.
Skill details also show all configs and variations that reference the skill, and which version each variation is using. This lets you know where a skill is in use before making changes.

​
Create a skill

Create a skill to define reusable agent instructions that you can attach to config variations. To create a skill from the Skills tab:
  1. From the Agents tab, click Library.
  2. Select the Skills tab. The skills list appears.
  3. Click Create skill. The “Save skill” dialog appears.
  4. Enter a name for the skill. The skill’s key auto-populates based on the name. You can edit the key, but it must meet the skill key requirements.
  5. (Optional) Add a description to help others understand when to use this skill.
  6. Add the skill’s Markdown content, either by importing an existing .md file or by authoring it directly in the editor.
  7. (Optional) Click the Add tag icon to add tags to organize skills across your project.
  8. Click Save.
New skills appear in the Library’s Skill tab.

​
Edit a skill

Edit a skill to update its content or metadata. Editing a skill creates a new version rather than overwriting the existing version. To edit a skill:
  1. Click the skill you want to edit in the Skills tab list. This opens the skill editing side panel.
  2. Update the skill’s Markdown content, tags or maintainer.
  3. Click Save.

​
Manage skill versions

New skills start at version 1. When you edit a skill, LaunchDarkly creates a new version of that skill instead of modifying the existing version. Previous versions remain available. You can refer back to them or use them again if needed. To compare versions of a skill:
  1. From the skills list, find the skill with versions you want to view.
  2. Click the version number in the “Versions” column. The “Version history” panel appears.
  3. Click Compare and select two versions to see a diff of the changes between them.

​
Use skills in config variations

Attach a skill to a variation to make it available to an agent. You can attach multiple skills to a single variation.

​
Attach skills to a variation

To attach skills to a variation:
  1. Click Agents in the left sidebar. The AgentControl menu appears.
  2. Click Configs.
  3. Click the name of an agent config to edit.
  4. Select the Variations tab and open the variation you want to manage.
  5. Click + Attach skills. The skills selection menu opens.
  6. Check or clear the box for each skill you want to attach or remove.
  7. Click Review and save.
Manually update config variations for new skill versionsConfig variations continue to use the version of a skill you assigned until you update them to use a different version.For example, if a config variation uses version 1 of a skill and you update the skill, creating version 2, the config will continue to use version 1 until you specify otherwise.
Attaching a skill makes LaunchDarkly aware of the relationship between the skill and your config. Your application still needs to retrieve the skill’s content and load it into your agent’s runtime. To retrieve skills, your application must use launchdarkly-ai-server 0.3.0 or later for Python, or @launchdarkly/ai-server 0.4.0 or later for Node.js. To learn more, read Agent skills.

​
Behavior for in-use variations

You can use agent skills in variations that are part of active experiments or guarded rollouts. If a variation that uses a skill is part of an active experiment or guarded rollout, LaunchDarkly may block you from updating that variation to reference a different skill version. LaunchDarkly blocks these updates to prevent changes that could affect experiment results or rollout behavior. If LaunchDarkly blocks an update, it provides details about the active usage, including which experiment or rollout is affected. Use this information to determine when to update the variation after it is no longer part of an active experiment or rollout.

​
Audit logs and access control

Agent skills use dedicated actions, separate from other AgentControl resources: createAgentSkill, updateAgentSkill, and deleteAgentSkill. You can scope these actions by tag when writing custom roles. To learn more, read Agent skill actions. LaunchDarkly records changes to skills and their attachments in audit logs. These records show when you create, update, or attach skills to variations. Use audit logs to review changes to skills and their attachments. This helps you track how skill content changes over time and maintain control over changes across AgentControl config variations.

​
Delete a skill

Delete a skill when you no longer need it and it is not used by any config variations.
Remove references to skills before deletingBefore you delete a skill, remove any references to it from config variations. LaunchDarkly prevents you from deleting skills that are still in use.
Here’s how:
  1. From the skills list, click the name of the skill you want to delete. The skill detail page appears.
  2. Click Delete. A delete dialog appears.
  3. Click Delete skill. LaunchDarkly deletes the skill, along with all of its versions.