Skills

QARK implements the open Agent Skills specification — a lightweight format for extending agents with specialized knowledge and capabilities. A skill is a folder containing a SKILL.md file with metadata and instructions, plus optional scripts, references, and assets. Skills are adopted across the industry by tools like Claude Code, Cursor, GitHub Copilot, Gemini CLI, and many others.

Skills solve a fundamental problem: agents are capable, but often lack the procedural knowledge and domain-specific context needed to do real work reliably. Instead of cramming everything into a system prompt, skills let agents load specialized knowledge on demand — only when the task requires it.

How Skills Work

Skills use a three-tier progressive disclosure model to manage context efficiently:

Tier	What Loads	When	Token Cost
Catalog	Name + description of every skill	Always (system prompt)	~100 tokens per skill
Instructions	Full SKILL.md body + resource listing	On demand (agent calls activate_skill)	Varies (< 5,000 tokens recommended)
Execution	Script output from scripts/ directory	On demand (agent calls skill_execute)	Output only

The agent sees the catalog at all times. When a task matches a skill’s description, the agent activates it to load full instructions. If the skill bundles executable scripts, the agent can run them within the skill’s sandboxed directory. See Multi-Tier Injection for the complete architecture.

Skill Folder Structure

my-skill/
├── SKILL.md          # Required — metadata + instructions
├── scripts/          # Optional — executable code (Python, Node, Bash)
├── references/       # Optional — supporting documentation
└── assets/           # Optional — templates, data files, images

SKILL.md Format

Every skill starts with a SKILL.md file containing YAML frontmatter and Markdown instructions:

---
name: pdf-processing
description: Extract PDF text, fill forms, merge files. Use when handling PDFs.
license: Apache-2.0
metadata:
  author: example-org
  version: "1.0"
---

# PDF Processing

## When to use this skill
Use this skill when the user needs to work with PDF files...

## How to extract text
1. Use pdfplumber for text extraction...

Frontmatter Fields

Field	Required	Description
name	Yes	Lowercase letters, numbers, hyphens. Max 64 chars. Must match parent directory name.
description	Yes	What the skill does and when to use it. Max 1,024 chars.
license	No	License name or reference to bundled license file
compatibility	No	Environment requirements (system packages, network access, etc.)
metadata	No	Key-value pairs for custom metadata. QARK recognizes special keys: skip-doc-search, extract-text, extract-images, required-tools. See Writing Skills.
allowed-tools	No	Space-delimited list of tools the skill may use (experimental)

The Markdown body after frontmatter contains the actual instructions — step-by-step procedures, examples, edge cases. There are no format restrictions. Write whatever helps agents perform the task effectively.

Three Activation Methods

Skills can be activated in three ways:

• /skill-name in the composer — one-shot activation for the current message only
• #skill-name in the composer — pinned activation, persists across all future messages in the conversation
• Agent defaults — skills configured in the agent editor, always active for that agent

See Activating Skills for details on each method.

What Skills Can Do

• Domain expertise — package specialized knowledge into reusable instructions (legal review, data analysis, code review patterns)
• New capabilities — give agents abilities they don’t have natively (creating presentations, analyzing datasets, building MCP servers)
• Repeatable workflows — turn multi-step tasks into consistent, auditable procedures
• Tool orchestration — skills can auto-enable tools they need via allowed-tools, and execute bundled scripts in Python, Node.js, or Bash
• Document handling — skills can take over document interaction entirely, bypassing RAG for specialized processing

Managing Skills Add skill folders, discover skills, enable/disable, and manage the skill sidebar.

Multi-Tier Injection How catalog, instructions, and execution tiers work — the architecture behind skill loading.

Activating Skills Slash syntax, hash syntax, agent defaults — three ways to activate skills in conversations.

Skills and Documents How skills interact with document search, the skip-doc-search flag, and File Tools mode.

Writing Skills Author your own skills — SKILL.md best practices, scripts, references, and the Agent Skills spec.