Skills

Key Ideas

• Instructions Are Plain Text: users describe how an agent should work without authoring transport envelopes or output schemas.
• One Trigger per Skill: choose one workflow or lifecycle point, or Custom for manual execution. Clone a Skill to use its instructions elsewhere.
• Triggers Determine Results: the system supplies the completion contract for the selected trigger. Users do not configure result roles.
• Context Is Parameterized: instructions receive explicit Event input, Goal context, System context, and declared defaults.
• Execution and Gates Differ: history reports every executed Skill; only required results determine workflow permission.
• AI Judgment: the AI decides when to stop and what outcome to report. Refine coordinates that decision; it does not grade supporting material.

Purpose

Skills let projects and nodes express repeatable agent behavior in one place. They replace the separate Governance, Quality, and Guidance editors and fixed planning launch sequence while preserving Refine’s workflow, recovery, and integration responsibilities.

Expected Role

A Skill contains a stable ID, name, plain-text instructions, enabled state, scope, parameters, and one trigger. Enter and Exit triggers cover all ten workflow steps; Node starts covers lifecycle startup; Custom makes a Skill manually runnable. The agent reports a success, failure, or error decision. Refine attaches invocation, binding, and role identity from the owned provider call; agents do not transcribe routing IDs. The AI interprets the Goal and Skill instructions and decides when to stop. A Goal may be supplied by a user or generated by AI; users need not supply outcomes, expectations, or acceptance criteria. Quality and Governance Skills may include such instructions when their authors choose. Summaries, evidence lists, plans, test details, and recovery suggestions are optional context. Their presence or absence does not determine whether work succeeds. Retained legacy responses that supply identity must still match exactly; missing or mismatched legacy identity is never silently repaired. Unreadable decisions retain the original response and stop the attempt; they do not trigger a hidden retry. Completed provider receipts survive restart without repeating work.

Refine seeds Plan, Implement, Quality, and Governance Skills with blocking bindings at their corresponding Workflow Enter Events. Projects can edit those prompts or configure multiple Skills at the same trigger. Plan and Implement need an enabled required Skill at their Enter trigger. Quality and Governance pass when no enabled required Skills apply to that node; candidate identity and integration checks still run, and history records that no agent checks were performed. Refine waits for the selected required agents and follows their reported decisions. Plan reports are passed to Implement as context without a prescribed checklist or checklist matching. Quality agents decide which investigation and checks are useful; Refine does not execute commands found in their reports. Governance agents decide whether the work is acceptable under their instructions, without mandatory violation fields or a recovery proposal. Skill instructions and current user authorization govern permitted work, including edits and supported workflow changes. Plan and Governance do not impose a blanket read-only restriction. Superseding workflow changes invalidate old completions; reviewing one candidate never authorizes integrating a different candidate.

There is one default Plan Skill. The prompt can choose how to investigate, criticize, and finalize its work; Refine does not impose a separate proposal, criticism, and revision agent sequence. Existing finalized plans and historical planning artifacts remain readable. Scoped finding recovery invokes the Plan Skill with the reviewed recovery request and retained candidate while preserving later gates.

Context attachment bindings reuse Skill text without spawning an agent. Imported Guidance becomes context Skills with its applicability and enabled state preserved. The AI interprets that guidance; Refine does not infer applicability from file extensions or require a selection receipt before advancing. Existing Governance and Quality instructions become default Skill text. Migration archives the originals before installing the new configuration and is safe to resume. Imported Quality commands remain available to the AI as instructions and historical context; Refine no longer executes or enforces them independently. Existing Skill text is preserved, even when it contains older instructions about reports. Only fresh default prompts change. After installation, migration retires standalone Governance, Guidance, and Quality settings from live state; normal state sync publishes their removal. Exact source text is retained in content-addressed archives under automation/retired-settings/, alongside the original migration evidence. Interrupted retirement resumes safely, archive failures preserve the source, and files reintroduced by older nodes are archived and retired again without changing Skills. Legacy Quality settings readers and writers reject migrated stores, so they cannot recreate a second configuration authority.

The Skill modal leads with rendered Markdown instructions and an edit icon for Markdown authoring. Its title identifies the Skill. Instructions and Settings use the shared application tab styles. Instructions opens first; Settings contains the name, Trigger, Scope, Status, parameters, and workflow options. Switching tabs preserves drafts, supports keyboard navigation, and validation reveals the tab requiring attention. Trigger, Scope, and Status share one row and stack on narrow screens. A Skill and its trigger save atomically under an observed revision; concurrent edits fail without erasing the current configuration. Deleting a Skill removes its trigger. Each workflow occurrence pins its configuration on first admission. Editing instructions affects future occurrences and never rewrites admitted requirements, completed invocations, or Round evidence. Effective Quality requirements identify selected bindings, instructions, resolved parameters, context attachments, and the completion contract; unrelated Skill edits do not change their identity. Clone Skill creates an independent copy with a new identity.

Controls → Skills and the command palette list enabled Custom Skills for the selected node. Manual runs launch only the selected Skill, independently of an open Goal. The browser collects typed inputs and opens an agent tab using the existing managed terminal lifecycle, transcript, reconnect, and stop controls. The CLI launches a supervised task and exposes its results, history, and cancellation through refine skills. Pending Skills participate in the active workflow admission cycle, including while Goal agents are running. Node-local wait reasons distinguish capacity, checkout contention, and paused automation. History distinguishes original recorded state from the outcome of all executed Skills and shows work and report-repair attempts separately. Background failures remain visible without vetoing a satisfied required gate.

Release and email intake can be ordinary project-authored Custom Skills. A Node starts Skill can queue another Skill and exit without waiting, preserving the one-trigger model and releasing its agent slot. Startup occurrences and explicit request IDs prevent duplicate launches. Email fetching uses a bounded one-shot capability with host-local credentials, a target-bound sender allowlist, deterministic Goal identities, and durable retry records. It does not require a dedicated poller or email-specific approval automation.

Configurations from the earlier multiple-trigger model are archived and converted deterministically: each assignment receives its own Skill while preserving instructions, parameters, execution order, effective scope, enabled state, and existing override relationships. Historical runs retain their pinned snapshots.

Backlog and Todo lifecycle Skills can execute before Plan without an implementation branch. Applicable executable bindings receive an invocation-owned managed checkout from an explicit target-derived source commit; their output remains lifecycle evidence and cannot become the implementation candidate. Scheduler-owned Todo-to-Plan execution uses the current workflow claim and reuses retained Todo Entry evidence before creating the implementation checkout. Queueing and disabled or context-only bindings do not materialize a checkout.

Goal-bound Skills carry a pinned workspace admission through ordered bindings, diagnostic repairs, and recovered invocations. Refine verifies the current Goal and Round and the linked checkout before every launch, result acceptance and cached-success settlement. Lifecycle invocations also retain and recheck their authored request, node and transition or durable-occurrence authority. Quality Skills and each supervised check run against the admitted exact candidate; a primary checkout or stale registration is an infrastructure error. Independently launched Custom Skills receive only their explicit execution context: opening a Goal never attaches that Skill to the Goal or changes its workspace.

Future Direction

Improve reuse, discovery, and context selection while keeping authored instructions readable. Additional result contracts should remain Refine-owned so richer execution does not turn Skill editing into schema programming.

Runtime completion instructions define response transport and identity, not substantive pass/fail rules. Skill instructions and current user authorization govern the decision; the wrapper must not turn discovered or unresolved findings into an automatic failure verdict.