Skip to main content

Skills

A skill is a reusable set of instructions, written as Markdown with YAML frontmatter, that the agent reads when a task needs it. Quick Apps follow the Agent Skills standard. This page covers where skills come from, how the agent uses them, and their limits. It is for platform engineers and app developers who add skills to Quick Apps. It assumes you know orchestration.

Where skills come from​

SourceWhere it livesBundled filesLoaded
Predefinedconfig/predefined/skills/<name>/SKILL.md in the backendNoAt startup
DIAL promptA DIAL prompt, prompts/<bucket>/<path>NoOn each request
DIAL skill resourceA DIAL skill folder, skills/<bucket>/<path>Yes, text filesOn each request
Picked on a messageA user's own DIAL skill, chosen in the chatYes, text filesOn each request

DIAL skill resources and skills picked on a message need DIAL Core 0.48.0 or later.

How the agent uses skills​

  • The system prompt lists every skill's name and description in an <available_skills> block.
  • The agent reads a skill's full instructions with the read_skill tool, when it decides it needs them.
  • A DIAL skill resource lists its bundled files in the instructions. The agent opens a file with read_skill(skill_name, file_path).
  • The built-in tool-call-file-parameter-formatting skill is always present. It teaches the agent the file parameter convention.

Add skills to an app​

skills lists the DIAL prompts and DIAL skill resources of an app. Predefined skills are always available and aren't listed here.

{
  "skills": [
    { "type": "dial-prompt", "url": "prompts/<bucket>/skills/code-review" },
    { "type": "dial-skill", "url": "skills/<bucket>/refund-policy" }
  ]
}
typeurl
dial-promptA prompt, with the prompts/ prefix. Its content must be a valid SKILL.md.
dial-skillA skill resource folder, with the skills/ prefix

When the app is deployed, DIAL Core shares a referenced prompt with the app automatically. A dial-skill isn't shared yet: it resolves only when the caller already has access, such as their own skill, one shared with them, or a published one.

Skill format​

---
name: refund-policy
description: How to handle refund requests, by region.
---

# Refund policy

Determine the customer's region, then read the matching reference file.
FieldRequiredRules
nameYesUp to 64 characters: lowercase letters, numbers, and single hyphens, not at the start or end
descriptionYesUp to 1024 characters. It helps the agent decide when to read the skill.
licenseNoAny text
compatibilityNoUp to 500 characters
metadataNoKey-value strings
allowed-toolsNoTool names. Shown to the agent, but not enforced.

For a predefined skill, the folder name must equal name. Invalid skills are skipped and logged.

Predefined skills​

Predefined skills ship with the backend. To add your own, put them in a folder layered over the built-in templates with the backend's PREDEFINED_EXTRA_PATHS. Each skill is a folder with a SKILL.md. Restart the backend after you add or change one.

DIAL skill resources​

A DIAL skill resource is a folder in DIAL: a SKILL.md plus any reference files. The agent reads only the files it needs, one DIAL Core request per file.

  • Readable files. Regular files with one of these extensions: .md, .markdown, .txt, .json, .yaml, .yml, .csv, .tsv, .xml, .html, .toml, .ini, .sql, .py, .sh, .js, .ts. Hidden files, subfolders, and binary files, such as images and PDFs, aren't available.
  • Only listed paths. A path that isn't in the skill's file list is refused, and the agent gets the list back.
  • Limits. DIAL_SKILLS_FILE_MAX_BYTES (default 262144) caps each file; a larger SKILL.md drops the skill. DIAL_SKILLS_MAX_FILES (default 200) caps the files listed. Files must be UTF-8.

Skills picked on a message​

A user can bring their own skill into a conversation with an agent they don't own. In DIAL Chat, they mention it in the message. The client sends it on the user message:

{
  "role": "user",
  "content": "/code-review focus on auth",
  "custom_content": { "skills": [{ "url": "skills/<bucket>/code-review" }] }
}
  • The skill is always loaded; the model doesn't choose. The user sees a Reading Skill stage for it.
  • A message can pick up to SKILL_INVOCATION_MAX_SKILLS_PER_MESSAGE skills, default 5. Across a conversation, the newest SKILL_INVOCATION_MAX_SKILLS, default 10, stay available.
  • DIAL Core shares each picked skill with the app for the request. It rejects the request with 400 for a malformed entry, and with 403 for a skill the user can't read.
  • A skill that can't be loaded gets an error result naming it, and the request is still served.
  • A pick made on a later message, not the first, keeps its instructions in context for that turn only. The skill stays listed, so the model can read it again.

Name collisions​

When two skills have the same name, one wins and the other is skipped and reported in the Initialization issues stage:

  • Among an app's own skills: predefined, then DIAL prompt, then DIAL skill resource. Within a source, the first one listed wins.
  • A skill picked on a message wins over the app's skill with the same name.

Errors​

A skill that fails to load never fails the request:

  • An invalid or inaccessible skill is skipped, with a reason in the Initialization issues stage.
  • If a DIAL skill's file list can't be read, the skill loads without its files.
  • If DIAL Core is down, the DIAL skills are dropped and the predefined ones stay.

Further reading​