What a skill is
A skill is a written procedure for one well-defined job, such as checking whether a plan over-builds (diff-minimizer), finding which test runner a project uses (test-runner-discovery) or creating a decision request (decision). Each skill is a folder containing a SKILL.md file, and often helper scripts, reference notes and output templates.
A skill tells the AI what to do; scripts inside the skill, and paqad's own commands, check the result. The AI following the procedure is judgement. The scripts it calls are machine checks.
Where skills come from
paqad-ai 1.91.1 ships 92 skills inside the framework install that .paqad/framework-path.txt points to:
| Group | Count |
|---|---|
| Base (every project) | 45 |
| Coding capability | 29, plus 1 shared stack skill |
| Security capability | 11 |
| Content capability | 6 |
Stage instructions in feature-development.yaml and paqad's router name skills by their folder name, for example "run the test-runner-discovery skill", and the AI reads that skill's SKILL.md from the install. Onboarding does not copy skills into your project's tool folders.
The SKILL.md header
Each SKILL.md starts with a header block (frontmatter) with a fixed schema. When paqad's own code loads skills, one that fails validation is skipped and recorded in .paqad/skills/events.jsonl rather than breaking the others.
| Field | Meaning |
|---|---|
name, description | Required. The skill's identifier and a one-line purpose. |
model_tier | Required. fast, medium, reasoning or deep: how much thinking the job needs. It maps to the models in your project profile's model_routing; whether that model is used depends on your tool. |
triggers | When the skill is relevant, as lists of classification values, for example process_depth: [fast lane, graduated lane, full lane]. |
cacheable, cache_key_inputs | Required. Whether a result may be reused, and which files decide when it is still valid. |
output_format | Required. markdown, yaml or json. |
input_schema | Required. The inputs the skill expects. |
The skill result cache
paqad includes a cache for skill results, so a skill run twice on unchanged inputs can return the stored result. It lives in .paqad/cache/skill-results/.
- Each entry is a file named
<skill>-<hash>.json. The hash is a SHA-256 fingerprint of the file paths and contents listed as the skill's inputs. - Only skills marked
cacheable: trueare stored. In 1.91.1, 15 shipped skills are. - No separate clean-up is needed when code changes: if any input file changes, the fingerprint changes and the old entry is simply not found. The cache code can also drop every entry that depends on a given module.
- Hits and misses are counted in
.stats.jsonin the same folder, and the hit rate appears in paqad's health metrics.
In 1.91.1 the cache is used by paqad's programmatic workflow engine and by a helper script. paqad does not intercept the skills your AI tool runs in an ordinary session, so during normal work the cache usually stays empty. Nothing needs to be warmed, and an empty cache changes nothing about how skills behave.
Checking the cache
paqad-ai doctor includes a "Skill cache healthy" check. It warns when the cache folder is missing or when a cache file is not valid JSON, and names the corrupt files. A corrupt entry can be deleted safely: the next run simply finds no cached result. See Doctor.
Which skill wins when two share a name
Skills are resolved in layers inside the install: base first, then the capabilities your project has (content, coding, security) and the stack packs that match it. When two layers contain a skill at the same path, the more specific layer wins. See Pack precedence.