Writing Skills

Skills are simple to create — a folder with a SKILL.md file is all you need to get started. This page covers the complete authoring guide, from minimal skills to full packages with scripts and references.

Quick Start

Create a directory and add a SKILL.md file:

my-skill/
└── SKILL.md

With minimal frontmatter:

---
name: my-skill
description: A brief description of what this skill does and when to use it.
---

# My Skill

Step-by-step instructions for the agent to follow...

Register the parent folder in QARK’s skill sidebar, and the skill is immediately discoverable.

SKILL.md Format

Frontmatter Reference

Field	Required	Constraints
name	Yes	1–64 characters. Lowercase letters, numbers, and hyphens only. Must not start/end with a hyphen or contain consecutive hyphens. Must match the parent directory name.
description	Yes	1–1,024 characters. Describe what the skill does and when to use it. Include keywords that help agents identify relevant tasks.
license	No	License name or reference to a bundled license file (e.g., Apache-2.0, Proprietary. LICENSE.txt has complete terms)
compatibility	No	1–500 characters. Environment requirements — intended product, system packages, network access, etc.
metadata	No	Arbitrary key-value mapping for custom properties. Keys should be reasonably unique to avoid conflicts.
allowed-tools	No	Space-delimited list of tools the skill may use. When active, these tools are auto-enabled. (Experimental)

Name Conventions

# Valid
name: pdf-processing
name: code-review
name: data-analysis

# Invalid
name: PDF-Processing    # uppercase not allowed
name: -pdf              # cannot start with hyphen
name: pdf--processing   # consecutive hyphens not allowed

The name field must match the parent directory name. A skill at pdf-processing/SKILL.md must have name: pdf-processing.

Writing Good Descriptions

The description is the most important field for discoverability. It determines whether agents will match a task to your skill.

# Good — specific, includes keywords, explains when to use
description: >
  Extract text and tables from PDF files, fill PDF forms,
  and merge multiple PDFs. Use when working with PDF documents
  or when the user mentions PDFs, forms, or document extraction.

# Poor — too vague for agents to match
description: Helps with PDFs.

Body Content

The Markdown body after frontmatter contains the skill instructions. There are no format restrictions — write whatever helps agents perform the task effectively.

Recommended sections:

• When to use this skill — helps the agent confirm the skill is relevant
• Step-by-step instructions — the core procedure
• Examples — sample inputs and expected outputs
• Edge cases — what to do when things go wrong

Keep the body under 500 lines. Move detailed reference material to separate files in references/.

Optional Directories

scripts/

Contains executable code that agents can run via the skill_execute tool.

my-skill/
├── SKILL.md
└── scripts/
    ├── process.py
    ├── transform.ts
    └── run.sh

Supported runtimes:

Extension	Runtime	Dependency Management
.py	uv run	Auto-creates .venv, installs from requirements.txt or pyproject.toml
.ts	npx tsx	Auto-installs from package.json
.js	node	Auto-installs from package.json
.sh	bash	System packages must be pre-installed

Scripts should be self-contained, include helpful error messages, and handle edge cases gracefully. The QARK_OUTPUT_DIR environment variable is set to a conversation-specific directory where scripts should write output files (images, PDFs, generated content).

references/

Contains additional documentation that agents can read when needed:

my-skill/
├── SKILL.md
└── references/
    ├── REFERENCE.md
    ├── style-guide.md
    └── api-docs.md

Reference files are listed in the Tier 2 resource listing when the skill is activated. The agent can read them on demand without loading everything into context at once. Keep individual reference files focused — smaller files mean less context usage.

assets/

Contains static resources — templates, images, data files, configuration schemas:

my-skill/
├── SKILL.md
└── assets/
    ├── template.docx
    ├── schema.json
    └── example.png

Best Practices

Size Budget

Component	Guideline
Description	Include keywords for matching. 1–2 sentences.
SKILL.md body	Under 500 lines / < 5,000 tokens. The full body loads into context on activation.
Reference files	Any size, but keep each file focused. Agents load them individually.
Scripts	Output capped at 100 KB. Write to files for larger outputs.

File References

When referencing other files in your skill, use relative paths from the skill root:

See [the reference guide](references/REFERENCE.md) for details.

Run the extraction script:
scripts/extract.py

Keep file references one level deep. Avoid deeply nested reference chains.

Tool Declarations

If your skill needs specific tools to function, declare them:

allowed-tools: web_search unix_command

This ensures the tools are auto-enabled when the skill is active. Without this, the user would need to manually enable tools for the skill to work.

Metadata Fields with Special Behavior

The metadata field is an arbitrary key-value mapping, but QARK recognizes several keys that control runtime behavior:

Key	Type	Default	Effect
skip-doc-search	boolean	false	Bypass RAG and File Tools entirely — skill receives raw document paths via activate_skill output
extract-text	boolean	true	Create .extracted.txt sidecar files when documents are uploaded (only relevant when skip-doc-search is true)
extract-images	boolean	false	Use a vision model to extract text from image attachments into .extracted.txt sidecars
required-tools	array	—	Fallback tool declaration. If the top-level allowed-tools frontmatter field is absent, QARK checks metadata.required-tools instead. Provided for compatibility with some skill authoring conventions.

See Skills and Documents for detailed explanations of the document processing flags.

You can also add arbitrary custom keys (e.g., author, version) — QARK passes them through without special handling.

metadata:
  skip-doc-search: true
  extract-text: true
  extract-images: false
  required-tools:              # Fallback if allowed-tools is absent
    - unix_command
    - web_search
  author: your-org
  version: "1.0"

The Agent Skills Specification

QARK’s skills implementation follows the open Agent Skills specification — a format adopted by Claude Code, Cursor, GitHub Copilot, Gemini CLI, VS Code, and many other tools. Skills you write for QARK are portable to any compatible agent product.

• Full specification — complete format reference
• Example skills — browse working examples on GitHub
• Reference library — validate skills with skills-ref validate ./my-skill
• Authoring best practices — tips for writing effective skills