Manage Agent0 Skills as Code

Custom skills can be versioned and managed as code. Keep a skill's SKILL.md and its supporting files in Git, review changes in pull requests, and apply them with the Dash0 Terraform provider or the Dash0 CLI.

Custom skills are organization-scoped. A skill is not tied to a dataset, so no --dataset flag or dataset attribute is needed.

The Skill Definition

Every skill is a YAML document with kind: Dash0Skill. The Terraform provider and the CLI accept the same document:

kind: Dash0Skill
metadata:
  labels:
    dash0.com/origin: dash0-cli_incident-triage
spec:
  files:
    - relativePath: SKILL.md
      content: |
        ---
        name: incident-triage
        description: Triage a production incident from its failed checks.
        ---

        Start from the failed check, then follow the trace to the failing service.
    - relativePath: references/runbook.md
      content: |
        # Runbook

        Check the deploy log first.
  permissions:
    - role: basic_member
      actions:
        - custom_skill:read

• spec.files: The files of the skill, each with a relativePath and its content. One of them must be SKILL.md. The files you send replace the stored files.
• Skill name: Dash0 reads the name from the name field of the SKILL.md frontmatter. The name is unique in your organization. metadata.name is set by Dash0, and any value you send is ignored.
• metadata.labels["dash0.com/origin"]: The identifier of a skill managed as code. Dash0 creates the skill when the origin is new and updates it otherwise. An origin is set when the skill is created and cannot change. Terraform sets the origin for you.
• spec.permissions: Who can use and change the skill. Each entry grants custom_skill:read, custom_skill:write, or custom_skill:delete to a role (admin or basic_member), a teamId, or a userId. When the list is present on an update, it replaces the stored grants exactly. When it is absent, an update keeps the stored grants, and a new skill gets the default access. See Who Can Change a Skill Managed as Code.
• defaultEnabled: Set defaultEnabled: false on an entry to ship the skill turned off for the people that entry covers. Each person can still turn it on with Enabled for you.
• metadata.labels["dash0.com/version"]: Optional on update. When you send it, Dash0 rejects the update if the skill changed since you read it. When you leave it out, the update applies without that check.

You cannot set spec.source or the dash0.com/enabled annotation in a definition. spec.source marks a skill imported from a Git repository, and whether a skill is enabled is each member's own choice.

Who Can Change a Skill Managed as Code

Default Access

A new skill whose definition sets no spec.permissions gets this access:

• Created with an organization auth token: Every member can read the skill.
• Created with a personal auth token: The skill is shared with the user who created it, who can read, edit, and delete it.

Editing in Dash0

The source of a skill with an origin is the Terraform configuration or the YAML you apply with the CLI. Whether anyone can also edit the skill in Dash0 depends on the tool:

• Admins: The Admin role always has Read and can delete the skill, but cannot edit it in Dash0.
• Skills managed by Terraform: These accept no custom_skill:write grant. Members can read them, and delete them if a grant allows it, but only the Terraform configuration changes their content.
• Skills managed with the CLI: These accept a custom_skill:write grant, so you can let members edit the skill in Dash0. The next dash0 apply overwrites their changes.

For the full sharing model, see Control Skill Sharing and Access.

Dash0 Terraform Provider

Manage skills as dash0_custom_skill resources. The custom_skill_yaml attribute takes the Dash0Skill document.

Example Usage

resource "dash0_custom_skill" "release_notes" {
  custom_skill_yaml = <<-YAML
kind: Dash0Skill
spec:
  files:
    - relativePath: SKILL.md
      content: |
        ---
        name: release-notes
        description: Write release notes in the house style.
        ---
        Write release notes as a bulleted list, one bullet per user-facing change.
  permissions:
    - role: basic_member
      actions: [custom_skill:read]
    - teamId: "<YOUR_TEAM_ID>"
      actions: [custom_skill:read, custom_skill:delete]
YAML
}

To keep the skill's files in a directory next to your configuration, build the YAML from that directory:

resource "dash0_custom_skill" "incident_response" {
  custom_skill_yaml = yamlencode({
    kind = "Dash0Skill"
    spec = {
      files = [
        for f in fileset("${path.module}/skills/incident-response", "**") : {
          relativePath = f
          content      = file("${path.module}/skills/incident-response/${f}")
        }
      ]
    }
  })
}

The provider sets an origin on the skill when it creates it. The id and origin attributes are computed.

Import an Existing Skill

# Import a skill by its origin when it has one, otherwise by its id. Skills
# created in Dash0, or with the Dash0 CLI using a personal auth token, have no origin.
terraform import dash0_custom_skill.incident_response "<origin-or-id>"

For more information, see the dash0_custom_skill resource documentation.

Dash0 CLI

Script skill operations with the Dash0 CLI. Use a dash0-cli_ prefix in the origin, so Dash0 shows the skill as managed by the CLI.

Apply from File

# Create or update a skill from a YAML file
dash0 apply -f skill.yaml

dash0 apply upserts by dash0.com/origin. A document without an origin creates a new skill, and a second apply of it fails because the skill name is already taken.

List Skills

# List the custom skills you can read
dash0 -X agent0 skills list

# Add the ORIGIN and ENABLED columns
dash0 -X agent0 skills list -o wide

# Only list skills whose origin starts with a prefix
dash0 -X agent0 skills list --origin-prefix dash0-cli_

Get Skill Details

# Get a skill by origin or id
dash0 -X agent0 skills get dash0-cli_incident-triage

# Export the full definition, ready to edit and apply again
dash0 -X agent0 skills get dash0-cli_incident-triage -o yaml

The exported YAML applies as is: dash0 apply leaves out the fields Dash0 sets, such as metadata.name, the version, and timestamps.

Create and Update Skills

# Create a skill from a YAML file
dash0 -X agent0 skills create -f skill.yaml

# Update an existing skill and show the diff
dash0 -X agent0 skills update -f skill.yaml

# Preview the update without changing the skill
dash0 -X agent0 skills update -f skill.yaml --dry-run

update fails if the skill does not exist yet.

Delete Skills

# Delete a skill by origin or id
dash0 -X agent0 skills delete dash0-cli_incident-triage --force

A deleted skill is kept for a while before it is purged. Applying its definition again restores it.

For more information, see the Dash0 CLI command reference.

Further Reading

• About Skills — What custom skills are, and how to create and invoke them
• About Managing as Code — Compare the infrastructure-as-code tools for Dash0 assets
• Control Skill Sharing and Access — Share a skill with members, teams, or roles, at Read or Edit
• Import Skills from a Git Repository — Bring in skills your team already keeps in GitHub or GitLab