Primitive 02 / Skill

Teach it once. Reuse the judgment.

A skill is a named package of operating knowledge. It gives the right agents the same rules, vocabulary, procedure, and output contract without copying that context into every role.

Skill

reusable policy attached to a role or loaded when a trigger matches

Inspect the real scope-capture skill to see how a rule becomes a reusable system asset.

skills/scope-capture/SKILL.mdReference implementation

01 / The boundary

A skill is not a smaller agent.

It does not own a pipeline stage, maintain workflow state, or decide when the team advances. It equips a role to handle one recurring situation consistently.

PrimitiveOwnsStarts whenEnds with

CommandEntry and mode selectionThe user invokes itA routed workflow

AgentOne kind of judgmentThe orchestrator launches or adopts itA bounded result

SkillReusable operating knowledgeIts trigger becomes relevantConsistent behavior inside the owner’s result

Placement test

If the content answers “who owns this work?”, it belongs in an agent. If it answers “how should any qualified owner handle this recurring situation?”, it belongs in a skill.

02 / Progressive disclosure

Context is a budget, not a warehouse.

Some skills are declared dependencies because a role needs them on every run. Situational skills can remain discoverable by metadata and load only after a trigger matches.

Declared dependency

Attach at agent launch

Use for persistent role doctrine: the architect, engineer, and most reviewers explicitly list rails-principles in frontmatter.

Triggered capability

Load when recognized

Use for situational behavior. Keep its description discoverable; load the procedure only when the described condition appears.

Context loadedTiny

skill catalog → name + description

Keep discoverability always available.

The system can scan compact descriptions to match a situation without placing every policy, schema, and example into the model’s working context.

scope-capture — When to name adjacent work, choose its GitHub label, and hand it off without expanding scope.

Boundary warning

“Load every skill at startup” converts a reusable knowledge system back into one enormous prompt. Retrieval has disappeared; token cost and instruction conflict return.

03 / Three useful forms

Package knowledge by the reason it changes.

The reference implementation separates shared engineering policy, artifact schemas, and workflow safeguards. Each can evolve without rewriting the agents that consume it.

01rails-principles

Domain policy

A shared engineering rulebook used by the architect, engineer, and reviewers.

Changes when: The team’s engineering doctrine changes
Does not own: Any one artifact’s shape

02architect-spec-format

Artifact schema

Fourteen required sections give the architect a writing contract and the orchestrator a validation contract.

Changes when: The handoff contract changes
Does not own: How the architect reaches a decision

03scope-capture

Workflow safeguard

A cross-role response to adjacent work: preserve the idea without expanding the feature.

Changes when: The capture or routing policy changes
Does not own: The shared GitHub issue tracker

The reference implementation ships eight skills in total. These three are one example each of why a form exists — the full set:

rails-principlesDomain policy

Rails-first design, naming, concerns, dependency discipline — shared by architect, engineer, and reviewers.

design-systemDomain policy

This project's CSS framework, visual grammar, and component classes — read before designing or reviewing views.

architect-spec-formatArtifact schema

The architect's 14-section spec format — the shared definition of “complete” for engineer and orchestrator alike.

discovery-brief-formatArtifact schema

The handoff contract between discovery and architect: what a complete brief must contain.

product-brief-formatArtifact schema

The fixed-section contract for a whole-product brief, read cold by other teams' discovery agents.

scope-captureWorkflow safeguard

Name adjacent work without building it or losing it — needs-discovery, tech-debt, or bug.

agent-logTooling reference

CLI reference for bin/agent-log: run lifecycle, decision and event logging, backed by db/agent_log.sqlite3.

github-cliTooling reference

gh CLI reference: routes features to the project board, bugs to labeled issues, isolates work in a worktree.

04 / Reuse graph

Skills compound when many roles depend on one source.

Copying rules into agents feels simpler once. A shared skill becomes more valuable on every revision because one policy change reaches every consumer.

AArchitect

EEngineer

CRCode review

FRFidelity review

SSecurity

PPerformance

Shared policyrails-principlesOne doctrine · five consumers

Shared safeguardscope-captureOne handoff rule · every role

Copied prompt fragments6 edits per policy changeShared skill1 edit, reused on the next run

05 / Enforcement

Write judgment in prose. Move certainty into checks.

Deterministic

Mechanics the system can verify

Directory and file names
Required frontmatter fields
Required output sections
Allowed enum values and tags
Exact artifact addresses
Scripts that validate structure

Probabilistic

Interpretation the model must perform

Recognize when the trigger applies
Select relevant principles
Distinguish a gap from adjacent scope
Apply examples to a new situation
Judge whether an exception is justified
Explain uncertainty to the next owner

Design rule

A checklist can guide the agent. A validator should enforce every checklist item that can be tested without interpretation.

06 / Failure modes

A skill fails when its reuse boundary is unclear.

Topic-only descriptionRails architecture guidance.

Trigger-rich descriptionUse when designing, implementing, or reviewing Rails application code.

The catalog needs a recognition rule, not a filing label.

Copied into agents

Architect rulebook v3
Engineer rulebook v2

One shared sourceskills: [rails-principles]

Duplication turns policy evolution into drift.

Shared-file mutationEvery reviewer files its own GitHub issue.

Race-free handoffReviewers tag reports; orchestrator sweeps once.

A skill may coordinate behavior without granting ownership.

07 / Portable template

Begin with the trigger and the boundary.

Keep the main file navigational. Move long references, scripts, or assets behind explicit routes only when they reduce repetition or enable deterministic work.

Inspect the source skills

skills/<skill-name>/SKILL.mdPortable skeleton

---
name: <skill-name>
description: Use when <observable trigger>;
  provides <one reusable capability>.
---

# <Skill name>

## Single responsibility
This skill defines <one policy or procedure>.
It does not own <neighbor responsibility>.

## Trigger
Use this when <recognizable situation>.
Do not use it when <near miss>.

## Procedure
1. Inspect <evidence>.
2. Apply <decision rule>.
3. Produce <bounded result>.

## Deterministic contract
- Required path: <address>
- Allowed values: <enum>
- Validate with: <script or check>

## Handoff
Record <evidence and uncertainty> for
<next owner>. Do not mutate <shared state>.

## Examples
- Positive: <clear match>
- Negative: <clear non-match>
- Edge: <ambiguous case and resolution>