Skills & Goals

This page covers two complementary concepts: a skill is a reusable, task-specific instruction pack loaded on demand; a goal is a durable completion objective attached to a session that keeps the agent driving toward one thing across many rounds.

Skills

A skill is a set of task-specific instructions, usually a SKILL.md (or a flat Markdown file) plus optional scripts, resources, and references. It is not part of the system prompt — it loads on demand: the catalog injects only names and descriptions, and the body is read only when the agent decides to use it.

Where skills live

The harness discovers skills from several local roots, highest priority first:

The project root is the nearest ancestor containing .git; without one, the current working directory is used. Put skills under <dshHome>/skills (by default ~/.dsh/skills) to reuse them across projects.

Skill format

A skill is either a single-level directory (<name>/SKILL.md) or a flat Markdown file (<name>.md). The name must be kebab-case. The key frontmatter fields are name and description, with optional whenToUse, disable-model-invocation, and user-invocable. For example:

---
name: code-review
description: Review code for style, lint, and best practices
whenToUse: When the user asks for a code review
---

How the model loads skills

The session receives an <available_skills> catalog containing only skill names and capped descriptions. When the user names a skill or a task clearly matches one, the agent calls the skill tool with the exact name and receives the full <skill_content> instruction body.

The user can also invoke a skill directly with /name, which injects the full body as a user gesture — the entry point for disable-model-invocation skills that neither the catalog nor the skill tool exposes. A loaded skill affects only the current session, never others.

Goals

A goal is a single durable completion objective attached to an existing session, with a revisioned phase (active / paused / blocked / complete) and a goal-round cap. It is state, not a scheduler or a separate conversation: the session log is its source of truth.

Create in one line

When the user states a long-running objective, the agent can create a goal with create_goal; a direct request in any language may trigger it, but routine single-turn work should not. Before reading or mutating, the agent calls get_goal for the exact goal_id and revision, then applies update_goal with edit / pause / resume / complete / blocked.

Human control: the /goal command

The human-facing /goal command observes or mutates the current goal directly, without a model turn:

Continuation after resume and fork

Continuation authority is process-local and never persisted. After a session resume or fork, an active goal is disarmed even if its phase still reads active — automatic work begins only after a later human-authorized resume through /goal resume or update_goal resume. This prevents unconfirmed automatic continuation.

Blocking and round budget

The blocked phase records a policy code and an explanation. The model may mark a goal blocked only after the same condition persists for at least blockedAfterConsecutiveRounds goal rounds (default 3); difficulty, uncertainty, or useful remaining work is not blocked. defaultMaxGoalRounds (default 256) bounds goal rounds only — not tokens, cost, or wall time.

Next steps

• Ship skills alongside a preset: Agent Presets.
• Fan a big objective out to child agents: Subagents & Workflows.