Canonical skills¶

The canonical skill is adept's single source of truth. Everything else — the files in .claude/, .cursor/, AGENTS.md, and so on — is rendered output derived from it.

On disk¶

A canonical skill is a directory named by its id, containing a SKILL.md plus optional sidecars:

<canonical>/pr-review/
├── SKILL.md
├── scripts/
├── references/
└── assets/

Where <canonical> lives depends on the project layout:

Consumer layout (default): <root>/.adeptability/skills/
Library layout (init --as-library): <root>/skills/

SKILL.md¶

SKILL.md is YAML frontmatter followed by a markdown body. adept also accepts a skill.yaml sidecar for the frontmatter. Recognized frontmatter fields:

Field	Purpose
`id` (alias `name`)	The skill identity (validated id charset, ≤ 50 chars)
`description`	Used by agent-mode harnesses for progressive disclosure / activation
`activation`	`always` \| `globs` \| `agent` \| `manual`
`globs`	File globs that activate a `globs` skill
`allowed-tools`	Tool allowlist carried into Claude Code
`tags`	Free-form topic tags

---
id: pr-review
description: Use before opening a PR. Tests, security, performance.
activation: agent
allowed-tools: [Read, Grep]
tags: [review, quality]
---
# PR Review Checklist
...

The body is arbitrary markdown. Sidecar files (scripts/, references/, assets/) ship alongside the body and are preserved by harnesses that support them.

Identity is content, not version¶

A skill's identity is (id, content-hash). There are no version numbers — the content hash is the source of truth for "did this change." This is what powers the drift detection: adept compares hashes of the project canonical, the last-synced base snapshot, and the library canonical to decide whether a skill is synced, ahead, behind, or diverged — and separately compares canonical against each harness's rendered output to detect harness drift.

Validation¶

Every skill is validated against pkg/adeptschema/skill.schema.json on load. Invalid frontmatter or an out-of-charset id fails fast with a clear error rather than producing broken harness output.

Resolution order¶

When adept builds the set of skills for a project, it resolves:

Project canonical skills (highest priority)
Skills from each configured library, in order

A project-canonical skill shadows a library skill sharing the same id, and across multiple libraries the first match wins. Use adept skill list to see the resolved set.