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.

Layer	Source	Editable in UI
User skills	Pimcore Studio → System → Pimcore Agent → Skill Configuration	Yes
Bundle skills	Directories listed under pimcore_agent.skills.paths	No, clone-only

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.

User skills (Pimcore Studio)

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

Field	Meaning
name	Unique identifier (e.g. my-custom-skill)
description	Shown in the agent editor's skill dropdown
instructions	Markdown body - the skill content
group	Optional 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.

Related docs

• Agents → skills field
• Tool Security Reference → the skill tool
• Shipping Presets - ship bundle skills from your own bundle