Multi-Tier Injection
Skills use a three-tier progressive disclosure pattern to manage context efficiently. Instead of dumping all skill knowledge into the system prompt, QARK loads information incrementally — the agent sees just enough to know a skill exists, then loads full instructions only when needed, and finally executes scripts only when required. This pattern is central to the Agent Skills specification.
The Three Tiers
Section titled “The Three Tiers”┌─────────────────────────────────────────────────────┐│ TIER 1 — CATALOG ││ ~100 tokens per skill ││ Always in system prompt ││ ││ <available_skills> ││ <skill name="web-scraper"> ││ Scrapes web pages and extracts data ││ </skill> ││ <skill name="pdf-processor"> ││ Converts PDFs to markdown ││ </skill> ││ </available_skills> │├─────────────────────────────────────────────────────┤│ TIER 2 — INSTRUCTIONS ││ Full SKILL.md body (< 5,000 tokens recommended) ││ Loaded on demand via activate_skill tool ││ ││ → Agent calls activate_skill("web-scraper") ││ ← Returns: full instructions + resource listing ││ + document paths + artifacts directory │├─────────────────────────────────────────────────────┤│ TIER 3 — EXECUTION ││ Script output (100 KB max) ││ Run on demand via skill_execute tool ││ ││ → Agent calls skill_execute("web-scraper", ││ "scripts/scrape.py", ["https://example.com"]) ││ ← Returns: stdout/stderr + new/modified files │└─────────────────────────────────────────────────────┘Tier 1 — Catalog
Section titled “Tier 1 — Catalog”What: Skill name + description only, injected as <available_skills> XML in the system prompt.
When: Always present when skills are active — whether from agent defaults, pinned skills, or available folders.
Cost: ~100 tokens per skill. A library of 50 skills costs roughly 5,000 tokens in the system prompt.
Purpose: The agent sees every available skill and can match tasks to skill descriptions. This is the “menu” — the agent reads it and decides which skill to activate.
When the user has pinned or one-shot skills, an additional <prioritized_skills> block is injected:
<prioritized_skills>web-scraper, pdf-processor</prioritized_skills>This tells the agent to activate these skills first if the task matches, before considering the broader catalog.
Tier 2 — Instructions
Section titled “Tier 2 — Instructions”What: The full SKILL.md body (frontmatter stripped), plus a resource listing showing available scripts, references, and assets.
When: On demand — the agent calls the activate_skill tool with the skill name.
Tool: activate_skill — automatically available when any skills are active. The agent sees it as a callable tool with a name parameter (enumerated from discovered skills).
Returns:
- Complete Markdown instructions from the skill body
- Skill directory path (absolute)
- Resource listing: files in
scripts/,references/,assets/ - Document paths (if the conversation has attached documents)
- Artifacts output directory path (
QARK_OUTPUT_DIR)
The resource listing lets the agent know what scripts it can execute and what reference files it can read, without loading them into context until needed.
Tier 3 — Execution
Section titled “Tier 3 — Execution”What: Execute a script from the skill’s scripts/ directory with automatic runtime detection.
When: On demand — the agent calls the skill_execute tool.
Tool: skill_execute — takes skill_name, command (relative path to script), and optional args.
Runtime auto-detection:
| Extension | Runtime |
|---|---|
.py | uv run (with auto-created .venv) |
.ts | npx tsx |
.js | node |
.sh | bash |
Safety:
- Scripts are sandboxed to the skill directory — no path traversal allowed
- Output is capped at 100 KB (stdout + stderr)
- Dependencies are auto-installed on first use (
.venvfor Python,node_modulesfor Node)
Environment variables:
QARK_OUTPUT_DIR— points togenerated_images/{conversation_id}/, where the skill should write output files (images, PDFs, etc.)
Returns:
- stdout and stderr
- Exit code
- List of new or modified files created during execution
Deduplication
Section titled “Deduplication”QARK tracks which skills have been activated within the current message stream to prevent redundant loading:
- Pinned skills (
#skill-name) and one-shot skills (/skill-name) are pre-populated in the dedup set - If the agent calls
activate_skillfor a skill already in the set, it receives a brief “Skill already active” message along with an updated document list (in case new documents were attached since activation) - This prevents the same instructions from being loaded multiple times in a single response
Tool Auto-Forcing
Section titled “Tool Auto-Forcing”When a skill declares allowed-tools in its frontmatter, those tools are automatically enabled for the current turn when the skill is active. For example:
allowed-tools: web_search unix_commandIf this skill is active, both web_search and unix_command are added to the enabled tools for that message — even if the user didn’t explicitly enable them. This ensures the skill has access to the tools it needs to function.
How It All Flows Together
Section titled “How It All Flows Together”Here’s a complete example of the three tiers in action:
- User types:
#web-scraper Extract product data from example.com - System prompt includes Tier 1 catalog with all skills, plus
<prioritized_skills>web-scraper</prioritized_skills> - Agent sees the catalog, recognizes the task matches
web-scraper, callsactivate_skill("web-scraper") - Tier 2 loads: agent receives full instructions — “Use scripts/scrape.py to fetch pages, parse with BeautifulSoup, output as JSON…”
- Agent follows the instructions, calls
skill_execute("web-scraper", "scripts/scrape.py", ["https://example.com"]) - Tier 3 executes: script runs in the skill’s directory, outputs JSON to stdout
- Agent receives the output and presents the extracted data to the user
The user’s context window only pays for what was actually needed — if a skill isn’t activated, only its ~100-token catalog entry is consumed.