8. Skills
8.1 The context contract
Section titled “8.1 The context contract”Every SKILL.md declares six fields:
| Field | Meaning |
|---|---|
| Required context | What the skill must read to work at all. |
| Conditional context | What it loads only when a named condition is present. |
| Excluded context | What the skill must not open. |
| Updates | Which state files the skill can write in place. |
| Capabilities | Which capabilities it needs, from the fixed vocabulary. |
| Completion | The outcome that means the skill is done. |
The release checks confirm these points for every skill and every branch:
- All six fields are present, once each, with real content. Each skill has its own Completion text, stated as an outcome.
- No file is both required and conditional, or both required and excluded. A file in both lists would make the contract say nothing.
- The capability names come from
capabilities.json. - A skill whose Updates field says “nothing” does not declare
file-write. In core, the one recorded exception isonline-research, which saves a file only when the user asks.
8.2 The 8 core skills
Section titled “8.2 The 8 core skills”Model-invocable (0): none. A route match names the skill that fits and stops (§5.2 rule 3).
User-only (8): a route can name them, but the agent never starts them:
| Skill | Purpose |
|---|---|
project-status |
Status menu. Routes to check-in, ongoing or triage (§5.4a). |
ingest |
Turn one approved source into a page in 3-Knowledge/. |
online-research |
Research from outside sources, without the check of the project’s own library first. |
system-settings |
Housekeeping menu. Routes to one of six branches (§5.4a). |
deliverable-brief |
Scope a deliverable in 2-Drafts/<slug>/_brief.md (core message, argument, headline outline), then lock it for draft-document. It starts from a matching profile (global, in ~/.familiar/brief-profiles/, or an extension’s brief-profiles/). A profile is built on request from the user’s own examples. It also reads project state and knowledge, without changing them. |
draft-document |
Deliverable menu. Routes to deck, document, review or workbook (§5.4a). |
handoff |
Handoff menu. Routes to session-handoff or assignment (§5.4a). |
save |
Memory menu. Routes to progress or to-memory (§5.4a). |
Branches (17): these are procedures, not skills. They have no frontmatter, no route and no slash command. You reach them only through their router’s menu.
| Router | Branch | Purpose |
|---|---|---|
project-status |
check-in |
The regular check-in: a first draft from state, then reconcile and health check. Sets up a new project on its first real run (§4.1, §12). |
project-status |
ongoing |
A read-only query: what is open right now. |
project-status |
triage |
Sort this project’s open work by effort or urgency. Read-only. |
system-settings |
update |
Update core or chosen extensions without touching other components’ files. |
system-settings |
tidy-workspace |
Survey old workspace files, propose a cleanup, and move files after approval. |
system-settings |
tracks |
The whole life of a track: propose, add, split, merge, retire. |
system-settings |
project-closeout |
Reconcile the final state and write a closeout summary. |
system-settings |
preferences |
Set this project’s signature (in 5-System/user-preferences.md), the default signature, and standing preferences (in the global ~/.familiar/user-preferences.md). |
system-settings |
hooks |
Turn the optional familiar-hooks on or off. |
draft-document |
deck |
Build or revise a presentation. |
draft-document |
document |
Create or revise a written document (.docx, or Markdown when Word builds are not possible). |
draft-document |
review |
Tracked changes and comment replies on a Word file that the team owns (tracked_edit.py). |
draft-document |
workbook |
Plan, build and check an Excel deliverable. xlsx_check.py names what a round trip through openpyxl would drop, and what a new version lost. |
handoff |
session-handoff |
Park or resume unfinished work across sessions. |
handoff |
assignment |
Write a self-contained brief for someone with no access to this project. |
save |
progress |
Reconcile every track before a break. Writes no new file. |
save |
to-memory |
Send a note to the right memory file. |
8.3 Procedure files
Section titled “8.3 Procedure files”Long procedures live in .familiar/core/. They load only when a skill names them, so skill bodies
stay short:
| File | Loaded by | Contents |
|---|---|---|
check-in.md |
project-status → Check-in |
Read state → draft the changes → reconcile → health check → close |
ingest.md |
ingest |
Read mode and ingest mode, the size check and bulk ingest, the ingest procedure, source dates and conflicts, privacy and failure |
status-format.md |
memory and track skills | Memory file formats, read order, update rules, decision records |
handoff-format.md |
handoff → Session handoff |
What a handoff is for, one file per thread, the four status values, the template, writing and reading one |
deck-rules.md / deck-build.md |
draft-document → Deck |
Template order, template inventory and brand rules, the headline test, visual design, content and bullet rules, checks and delivery; the build procedure |
docx-rules.md |
draft-document → Document, when it applies |
Word document content, copies, build and checks |
calendar-rules.md |
save → To memory, project-status → Check-in |
Timeline and memory as the only source of truth, the order of updates, safeguards |
familiar-behavior.md |
any route that needs project-lifecycle guidance | Neutral project-lifecycle behavior. It is not a startup checklist. |
voice.md |
a skill that writes prose, and on its own for a routed chat reply | §9 |
plain-language.md |
written output longer than a chat reply | §9 |
familiar-voice.md |
only when the project configuration turns it on | Optional companion voice |
retrieval-fallback.md |
when named-subagents is not active |
§10.2 |
running-scripts.md |
only when a script cannot run | What to do when Python or a package is missing |
_index.md maps which file loads when.