Skip to content

Skills as a Behaviour Primitive (Proposal)

Status: draft proposal. Not part of the canonical numbered set. If accepted, this folds into 03 Agent Architecture & Extensibility as a new section, with catalogue surfacing in 08 Agents Catalogue & Platform Services; the decision record (ADR-030 below) is appended to the decision log. Do not run the docs index/changelog maintainer against this file until promoted. ADR number provisional (latest accepted is ADR-027).

Precis

Thinklio has two extensibility primitives today: the agent (the actor — a configured prompt + scoped knowledge + tools + policy) and the tool (the capability — a thing an agent can invoke). There is a gap between them: a reusable unit of behavioural guidance for a category of work — the rules, no-gos, patterns, and tips that should shape how an agent does a kind of task, independent of which agent is doing it.

A concrete example: "writing TypeScript" carries conventions (object-form Convex functions, validators, index discipline), no-gos (no unscoped ctx.db, no any), patterns (custom-function middleware), and tips. That guidance is not an agent (many agents may write TS) and not a tool (it invokes nothing). It is a skill: a declaratively-triggered bundle of instructions loaded into the agent loop when the work matches.

This is the same primitive as Open Brain's and Claude Code's SKILL.md — frontmatter with a triggering description, a body of procedure — and it composes cleanly into Thinklio's agent architecture. This proposal defines it, distinguishes it sharply from agents, tools, and durable knowledge, and scopes/governs it across the four knowledge layers.

1. The gap in the current model

Primitive Answers Example
Agent Who acts "The Code Assistant agent"
Tool What it can invoke "Run tests", "search Cliniko"
Knowledge What is true (durable facts, scoped) "Our deploy server is builds-nbg1"
Skill (proposed) How to do a category of work "When writing TS, follow these rules and no-gos"

The skill is the missing "how." Without it, this guidance gets crammed into agent system prompts (not reusable across agents, bloats every turn) or into knowledge facts (wrong primitive — guidance is not a sourced truth claim and should not be retrieved as evidence). A first-class skill fixes both.

2. What a skill is

A skill is a reusable, declaratively-triggered bundle of behavioural guidance for a category of work. It has:

  • A trigger — a description (and optional explicit signals) that lets the harness decide when the skill is relevant to the current turn, the same triggering model as SKILL.md and Thinklio's own Skill-tool invocation.
  • A body — the rules, no-gos, patterns, tips, and (optionally) a procedure or checklist.
  • Scope — which layer it belongs to (platform / account / team / agent), governing visibility and precedence.
  • Metadata — author, version, when-to-use / when-not-to-use, optional requires_tools.

It is declarative and inert: a skill invokes nothing and asserts no truth. It only shapes how an agent reasons and acts when loaded.

skill: defineTable({
  scope: v.union(
    v.literal("platform"),  // seeded, available to all (e.g. "writing TypeScript")
    v.literal("account"),
    v.literal("team"),
    v.literal("agent"),     // bound to a specific agent definition
  ),
  scopeId: v.optional(v.string()),     // accountId/teamId/agentId per scope
  accountId: v.optional(v.id("account")),
  name: v.string(),
  slug: v.string(),
  triggerDescription: v.string(),       // when this skill is relevant (matched by the harness)
  body: v.string(),                      // markdown: rules, no-gos, patterns, tips, procedure
  requiresTools: v.optional(v.array(v.string())),
  whenNotToUse: v.optional(v.string()),
  version: v.string(),
  isSystem: v.boolean(),                 // platform-seeded, immutable to end users
  status: v.union(v.literal("active"), v.literal("draft"), v.literal("archived")),
  embedding: v.optional(v.array(v.float64())),  // for trigger matching by similarity
  updatedAt: v.number(),
})
  .index("by_scope", ["scope", "scopeId"])
  .index("by_account", ["accountId"])
  .index("by_slug", ["slug"]),

3. How a skill differs from each neighbour

  • vs Agent. An agent is the actor and carries identity, tools, and policy. A skill is portable across agents — many agents can load "writing TypeScript." An agent may declare default skills, but the skill is not the agent.
  • vs Tool. A tool does something (invokes a capability, has side effects, consumes budget). A skill guides — it has no side effects and invokes nothing. A skill may declare requiresTools (this guidance assumes the test-runner tool is available) but it is not itself a tool.
  • vs Knowledge. Knowledge is what is true — sourced, scoped, retrieved as evidence, governed by the use-policy axis (Memory as a Service §6). A skill is how to work — instruction by nature, authored and reviewed, not extracted from interactions. Do not store skills as knowledge facts: conflating durable truth with behavioural guidance would muddy retrieval (a skill would surface as "evidence") and governance (a skill is instruction-grade by construction, which the evidence-by-default knowledge model deliberately resists). They are different primitives with different defaults.

4. How a skill composes into the agent loop

The agent loop is prompt → retrieve(memory) → LLM → act → loop (doc 02 §8.3). Skills slot in at context assembly, parallel to knowledge retrieval:

  1. Match. At turn start, the harness selects relevant skills by matching the turn (and the agent's declared defaults) against triggerDescription — by similarity and/or explicit signals. This reuses the same triggering instinct as the Skill tool.
  2. Load. Matched skill bodies are assembled into the turn context as behavioural guidance, distinct from retrieved knowledge (which is evidence) — clearly delineated so the model treats rules as rules and facts as facts.
  3. Apply. The LLM reasons and acts under that guidance. No-gos act as guardrails; patterns/tips shape output.
  4. Precedence. Where skills conflict, layer precedence applies: account skills override agent skills override platform skills, consistent with the four-layer governance order (account is the ceiling — doc 02 §9.1). Account-scoped no-gos cannot be overridden by a lower layer.

Skills are part of context, not a tool call, so they cost no extra round-trip and consume only context budget — which argues for keeping bodies tight and matching precise.

5. Scope and governance

Skills follow the four-layer model, with authoring governed like the relation vocabulary in the wiki proposal (§4.1):

  • Platform skills (isSystem) are seeded and immutable to end users — e.g. "writing TypeScript", "research synthesis", "meeting synthesis" (the latter two mirror Open Brain's skill packs).
  • Account/team skills are authored through a governed admin path; the policy middleware denies skill creation/mutation by end users and by agents unless explicitly permitted. Agents use skills; they do not author the skill catalogue (the same agents-may-create-edges-but-not-vocabulary rule as the wiki proposal).
  • Agent skills are bound to an agent definition as its defaults.

A future "skill creation" capability (an agent that distils repeated corrections into a draft skill — Open Brain's "Aiception" pattern) is possible but must land drafts into the governed authoring path for human review, never auto-publish. This is the skills analogue of the memory use-policy rule: machine-proposed, human-confirmed.

6. Relationship to the broader ecosystem

This primitive is deliberately the same shape as Open Brain / Claude Code SKILL.md, which means:

  • Skills are portable — a well-formed skill body is reviewable plain text and could be imported/exported across systems.
  • The catalogue (doc 08) gains a skills section alongside the agent templates, surfacing platform and account skills.
  • Skills are a natural community/marketplace unit later (like Open Brain's open skills/ category), though that is out of scope here.

7. Build sequence

  1. Define the skill table and the platform-seeded set (start with "writing TypeScript" and one or two work-synthesis skills).
  2. Add skill matching + loading to context assembly, clearly delineated from knowledge in the prompt.
  3. Layer precedence and the governed authoring path.
  4. Catalogue surfacing (doc 08) and agent-default binding.
  5. (Later) machine-proposed skill drafts via the governed authoring path.

8. Draft decision record (draft ADR-030)

To be appended to decision-log.md on acceptance. Number provisional.

ADR-030: Skills as a First-Class Behaviour Primitive

Date: 2026-06-15 Status: Proposed

Context: Thinklio has agents (actors) and tools (capabilities) but no reusable unit for behavioural guidance — the rules, no-gos, patterns, and tips for a category of work. That guidance currently has no home and gets miscast as agent prompt bloat or, worse, as knowledge facts.

Decision: Introduce a first-class skill primitive: a declaratively-triggered bundle of behavioural guidance, scoped across the four layers, governed at authoring time, loaded into the agent loop at context-assembly time, and kept distinct from agents, tools, and durable knowledge. Model it on SKILL.md (triggering frontmatter + procedural body). Agents use skills; the skill catalogue is admin-governed.

Reasoning: Behavioural guidance is reusable across agents and must not be retrieved as evidence — it is instruction by nature, the opposite default from the evidence-by-default knowledge model. A distinct primitive keeps prompts lean, guidance reusable, and the knowledge/governance boundaries clean, while aligning with the portable SKILL.md ecosystem.

Implications:

  • New skill table; platform-seeded set; matching + loading in context assembly.
  • Layer precedence for conflicting guidance; account no-gos are the ceiling.
  • Governed authoring path; agents may use but not author skills; machine-proposed drafts require human confirmation.
  • Catalogue surfacing in doc 08; agent definitions may declare default skills.

9. Open questions

  1. Matching mechanism — pure embedding similarity on triggerDescription, explicit tags, agent-declared defaults, or a blend. Avoid over-loading context with weakly-relevant skills.
  2. Context budget — how many skills may load per turn, and how skill bodies are summarised/truncated under budget pressure (ties to doc 02 §9.4 token allocation).
  3. Skill vs agent system prompt — how much of today's agent system-prompt guidance migrates into shared skills vs stays agent-specific.
  4. Authoring UX — the governed admin path for account skills, and whether the catalogue (doc 08) is the surface.
  5. Naming collision — the platform's own "Skill" tool (slash-command invocation) vs the user-facing "skill" primitive; confirm the terminology does not confuse.

10. Revision history

Date Change
2026-06-15 Initial draft proposal, arising from the Open Brain / Nate B. Jones design conversation.