Activating Skills

Skills are activated — loaded into an agent’s working context — through three methods, each with different persistence and scope.

Slash Syntax — One-Shot

Type /skill-name anywhere in your message to activate a skill for that message only.

/pdf-processor Convert this PDF to markdown and extract all tables

The /pdf-processor token is stripped from the message before sending to the model
The skill is active for this single message only — it does not persist to future messages
The agent sees the skill in the <prioritized_skills> block and activates it immediately
Multiple one-shot skills can be combined: /web-scraper /pdf-processor Scrape and convert

Hash Syntax — Pinned

Type #skill-name anywhere in your message to pin a skill to the conversation.

#code-review Review all pull requests in this conversation with consistent standards

The #code-review token is stripped from the message before sending
The skill is persisted in the conversation’s configuration — it stays active for all future messages
Useful for skills that define ongoing behavior: coding standards, review checklists, output formatting
Pinned skills appear in the <prioritized_skills> block for every subsequent message

Agent Defaults

Skills can be configured as defaults for a specific agent in the agent editor. When you select an agent for a conversation, its default skills are always active.

Navigate to the agent editor → scroll to the Default Skills section → check the skills you want the agent to always use.

Default skills activate automatically whenever the agent handles a message
They do not need / or # syntax — they’re part of the agent’s identity
Useful for agents with specialized workflows: “The Research Agent always uses academic-search and citation-manager”
Default skills can be combined with one-shot and pinned skills — duplicates are automatically removed

When you type / or # followed by characters in the composer, a popover appears showing matching skills:

Filtered list — skills are filtered by name as you type
Name + description — each entry shows the skill name and its description
Active indicator — a checkmark shows which skills are already active in the conversation
Keyboard navigation — use ↑/↓ to browse, Enter to select, Escape to dismiss
Mode indicator — a lightning bolt icon for / (one-shot) and a pin icon for # (pinned)

Skill Priority and Merging

When multiple activation sources overlap, QARK merges and deduplicates:

Agent default skills are collected from the agent’s skill_config
Pinned skills are collected from the conversation’s config_overrides.active_skills
One-shot skills are collected from the current message’s /skill-name tokens
All three lists are merged into a single active_skill_names set — duplicates removed
The combined set is injected into the <prioritized_skills> block

The agent sees one unified list of skills to prioritize, regardless of how they were activated.

Tool Auto-Forcing

When an active skill declares allowed-tools in its frontmatter, those tools are automatically enabled for the current turn:

# In SKILL.md frontmatter
allowed-tools: web_search unix_command

If this skill is active (via any method), web_search and unix_command are added to the enabled tools — even if the user didn’t explicitly toggle them on. This ensures the skill has everything it needs to function without manual tool configuration.

The skill sidebar shows tool badges for each required tool. A warning icon appears if a required tool is unavailable (e.g., missing API key for web search).

Interaction with Document Search

Active skills can control how documents are handled through the skip-doc-search metadata flag:

metadata:
  skip-doc-search: true

When this flag is set and the skill is active:

The standard document search pipeline (both RAG and File Tools modes) is bypassed
The skill receives raw document paths via the activate_skill tool output instead
This allows the skill to implement its own document processing logic

See Skills and Documents for the full details.