Skip to main content
Version: 2026.2

Skills

Skills are markdown instruction files that teach an agent domain-specific behavior. At runtime the GitHub Copilot SDK loads the SKILL.md files from the materialized skill directory into the agent's system context - conceptually, skills are modular system-prompt extensions.

An agent references skills by name:

# in an agent YAML
skills:
  - pql-search
  - data-object-proposals

The names must match existing skills (unknown names are silently dropped). See the skills field on agents.

Where skills come from​

Like agents, skills follow the three-layer merge model - see README → The merge model. Bundle-provided skills are the bottom layer; user skills created through Pimcore Studio override bundle skills of the same name.

LayerSourceEditable in UI
User skillsPimcore Studio → System → Pimcore Agent → Skill ConfigurationYes
Bundle skillsDirectories listed under pimcore_agent.skills.pathsNo, but customizable

Every skill Pimcore Studio shows carries a bundle or user source badge so you can see at a glance whether you are looking at a bundle default or at your own override. A Custom / Preset switch at the top of the tree separates the two views - see Customizing a bundle skill in Pimcore Studio below.

Customizing a bundle skill in Pimcore Studio​

The Custom view lists only user skills with no matching bundle preset. The Preset view lists every bundle-provided skill, each tagged Bundle or Customized.

  • Customize materializes a bundle skill's full content (front-matter and body) as an editable copy in one click. The copy is written to the configured write target (settings-store by default, or a YAML file under var/config/agent/skills when set to symfony-config) and the skill then shows as Customized in the Preset view.
  • Reset to default removes the customization, so the shipped skill applies again on the next reload.
  • Activate / Deactivate toggles the skill's enabled flag (default true). A deactivated skill is excluded from the export the agent-server consumes, so no agent can load it - a non-destructive alternative to deleting it. Deactivating a skill that has not been customized yet stores a lightweight disable record instead of a full customization; customizing it later upgrades that record in place.

Bundle skill content is always read-only. Customize, Reset to default, and Activate/Deactivate are available only when the configured write target is writeable; the actions are disabled with an explanatory tooltip otherwise.

User skills (Pimcore Studio)​

Administrators can create simple skills directly in the Pimcore Studio skill editor. Each user skill has four fields:

FieldMeaning
nameUnique identifier (e.g. my-custom-skill)
descriptionShown in the agent editor's skill dropdown
instructionsMarkdown body - the skill content
groupOptional folder grouping in the skill config tree

At export time user skills are serialized into a single SKILL.md file with auto-generated YAML front-matter (name, description) followed by the instructions body.

Bundle skills​

Bundle skills are file-based. Each skill is a directory that contains a SKILL.md file:

config/skills/
├── pql-search/
│   └── SKILL.md
├── data-object-proposals/
│   ├── SKILL.md
│   └── resources/
│       └── field-types.md
└── tag-proposals/
    └── SKILL.md

Nested files alongside SKILL.md (examples, schemas, templates) travel through the export pipeline with the skill - the whole directory's files end up in the agent-server's materialized skill dir so SKILL.md can reference relative paths.

Bundles register skill parent directories via pimcore_agent.skills.paths. See Shipping Presets for the registration walkthrough (hard vs optional bundle dependency).

SKILL.md file format​

Each skill directory must contain a SKILL.md with YAML front-matter:

---
name: pql-search
description: >-
  Search for data objects using Pimcore Query Language (PQL)
  with field discovery and structured filters.
---

# PQL Search

Step-by-step workflow, syntax reference, examples…
  • name must match the directory name and is what the agent's skills: [...] list references.
  • description is shown in the agent editor's skill dropdown.
  • Everything below the closing --- is the skill body and becomes part of the agent's system message when the skill is active for a session.

Skill resolution at runtime​

An agent sees only the skills it lists. At runtime the agent-server materializes every skill in the registry to {skillsMaterializeDir}/{skillName}/ (default /app/var/skills/) and uses disabledSkills to opt the agent out of everything it did not ask for.

Wipe-and-rewrite semantics, the skill tool requirement, and the disabledSkills computation are documented in Architecture → Configuration System → Skill materialization.