Agent Skills
Give q portable instructions that are discovered when the current task makes them relevant.
How retrieval works
q implements the portable SKILL.md Agent Skills format as an on-demand retrieval layer. The full catalog and skill bodies stay out of the base prompt.
On a new user turn, task_start, or an answer returned through ask_to_user, q can search skill metadata and add up to four previously unseen candidate hints. A hint is not an instruction. The model must call get_skill before following the skill.
Roles with skill tools may also call search_skills later when new information shows that more guidance is needed.
Lexical ranking weights the skill name above tags and description. When embeddings are configured, q fuses BM25 and vector candidates. If a semantic candidate is confident while its lexical score is only noise, q can omit that weak BM25 contribution; this prevents a language mismatch from burying a strong semantic match. When semantic confidence is not high enough, the complete lexical branch remains available.
Discovery locations
q reads skills in increasing precedence from:
~/.agents/skills/
~/.q/skills/
<nearest-git-root>/.agents/skills/
<workspace>/.agents/skills/
<workspace>/.q/skills/
The nearest Git-root location is used only when it differs from the active workspace. It makes portable repository skills visible when q starts in a subdirectory without widening the workspace file-tool jail.
When the same skill name appears in both bounded result sets, the workspace definition wins.
Write a skill
Create a directory containing SKILL.md:
---
name: release-check
description: Verify a release candidate before publishing it.
---
# Release check
Read the release manifest, run the documented verification, and report evidence.
The frontmatter name is canonical but does not have to match the directory name. description is optional. Keep the body scoped to work where the instructions materially change the result.
Manage skills
Open /skills or run q skills. The two panels correspond to q-managed locations:
GLOBAL -> ~/.q/skills/<skill-name>
WORKSPACE -> <workspace>/.q/skills/<skill-name>
Use left/right or Tab to switch scope, Up/Down to select, A to clone a Git repository, U to fast-forward an installed skill, D to remove after confirmation, and R to rediscover all roots and reconcile the indexes.
Skills found under .agents/skills appear in the catalog but are read-only because q does not own those directories. A managed repository must contain SKILL.md at its root; its destination name comes from validated frontmatter rather than the repository URL.
Refresh and indexing
Without an embedding model, retrieval uses BM25 metadata search. With one assigned through /model, q combines BM25 and HNSW vector results. Assigning a new embedding model rebuilds and backfills the vector projection.
While q is running, skill use reconciles workspace skill roots when the previous check is at least 30 seconds old. Use /skills to manage q-owned skills and request an explicit reindex.