Skip to content

skills.md

Latest commit

 

History

History
334 lines (235 loc) · 13.1 KB

skills.md

File metadata and controls

334 lines (235 loc) · 13.1 KB
Raw

dreb can create skills. Ask it to build one for your use case.

Skills

Skills are self-contained capability packages that the agent loads on-demand. A skill provides specialized workflows, setup instructions, helper scripts, and reference documentation for specific tasks.

dreb implements the Agent Skills standard, warning about violations but remaining lenient.

Table of Contents

Locations

Note: Skills can instruct the model to run commands and may include executable code. Skim what you're loading, same as any other dependency.

dreb loads skills from:

  • Global:
    • ~/.dreb/agent/skills/
    • ~/.agents/skills/
  • Project:
    • .dreb/skills/
    • .agents/skills/ in cwd and ancestor directories (up to git repo root, or filesystem root when not in a repo)
  • Packages: skills/ directories or dreb.skills entries in package.json
  • Settings: skills array with files or directories
  • CLI: --skill <path> (repeatable, additive even with --no-skills)

Discovery rules:

  • Direct .md files in the skills directory root
  • Recursive SKILL.md files under subdirectories

Disable discovery with --no-skills (explicit --skill paths still load).

Using Skills from Other Harnesses

To use skills from Claude Code or OpenAI Codex, add their directories to settings:

{
  "skills": [
    "~/.claude/skills",
    "~/.codex/skills"
  ]
}

For project-level Claude Code skills, add to .dreb/settings.json:

{
  "skills": ["../.claude/skills"]
}

How Skills Work

  1. At startup, dreb scans skill locations and extracts names and descriptions
  2. The system prompt includes available skills in XML format per the specification
  3. When a task matches, the agent uses the skill tool to load the full SKILL.md with content substitution applied
  4. Users can also invoke skills directly via /skill:name [args] slash commands
  5. The agent follows the instructions, using relative paths to reference scripts and assets

This is progressive disclosure: only descriptions are always in context, full instructions load on-demand.

Invocation

Skill Tool (model-invocable)

The agent can invoke skills programmatically via the built-in skill tool:

skill(skill: "review-pr", args: "123")

The tool reads the SKILL.md, strips frontmatter, applies content substitution, and returns the expanded content. Skills with disable-model-invocation: true are hidden from the system prompt and return a warning if the model tries to invoke them.

Slash Commands (user-invocable)

Skills register as /skill:name commands in interactive mode:

/skill:brave-search           # Load and execute the skill
/skill:pdf-tools extract      # Load skill with arguments

Arguments after the command are passed through content substitution into the skill content.

Skills with user-invocable: false are hidden from the / menu but remain available to the model via the skill tool.

Toggle skill commands via /settings in interactive mode or in settings.json:

{
  "enableSkillCommands": true
}

Skill Structure

A skill is a directory with a SKILL.md file. Everything else is freeform.

my-skill/
├── SKILL.md              # Required: frontmatter + instructions
├── scripts/              # Helper scripts
│   └── process.sh
├── references/           # Detailed docs loaded on-demand
│   └── api-reference.md
└── assets/
    └── template.json

SKILL.md Format

---
name: my-skill
description: What this skill does and when to use it. Be specific.
argument-hint: "<input file>"
---

# My Skill

## Setup

Run once before first use:
\`\`\`bash
cd ${DREB_SKILL_DIR} && npm install
\`\`\`

## Usage

Process the input file: $1

\`\`\`bash
${DREB_SKILL_DIR}/scripts/process.sh $1
\`\`\`

Use relative paths from the skill directory:

See [the reference guide](references/REFERENCE.md) for details.

Frontmatter

Per the Agent Skills specification, plus dreb-specific fields:

Field Required Description
name Yes Max 64 chars. Lowercase a-z, 0-9, hyphens. Must match parent directory.
description Yes Max 1024 chars. What the skill does and when to use it.
argument-hint No Hint text shown in the / menu (e.g. "[PR number or URL]").
user-invocable No Default true. When false, skill is hidden from the / menu but remains available to the model via the skill tool.
disable-model-invocation No When true, skill is hidden from system prompt. Users must use /skill:name.

Name Rules

  • 1-64 characters
  • Lowercase letters, numbers, hyphens only
  • No leading/trailing hyphens
  • No consecutive hyphens
  • Must match parent directory name

Valid: pdf-processing, data-analysis, code-review Invalid: PDF-Processing, -pdf, pdf--processing

Description Best Practices

The description determines when the agent loads the skill. Be specific.

Good:

description: Extracts text and tables from PDF files, fills PDF forms, and merges multiple PDFs. Use when working with PDF documents.

Poor:

description: Helps with PDFs.

Content Substitution

When a skill is invoked (via the skill tool or /skill:name), placeholders in the body are replaced before injection:

Placeholder Replaced with
$ARGUMENTS, $@ All arguments joined
$0 First argument (alias for $1)
$1, $2, ... Positional arguments (bash-style parsing: supports quoting)
${@:N} Arguments from the Nth position
${@:N:L} L arguments starting at N
${DREB_SKILL_DIR} Absolute path to the skill's directory
${DREB_SESSION_ID} Current session ID

Example:

---
name: review-file
description: Review a specific file for issues.
argument-hint: "<filename>"
---
Read ${DREB_SKILL_DIR}/checklist.md for the review criteria.

Review the file: $1
Focus areas: ${@:2}

Usage: /skill:review-file src/main.ts "security" "performance"

Validation

dreb validates skills against the Agent Skills standard. Most issues produce warnings but still load the skill:

  • Name doesn't match parent directory
  • Name exceeds 64 characters or contains invalid characters
  • Name starts/ends with hyphen or has consecutive hyphens
  • Description exceeds 1024 characters

Unknown frontmatter fields are ignored.

Exception: Skills with missing description are not loaded.

Name collisions (same name from different locations) warn and keep the first skill found.

Example

brave-search/
├── SKILL.md
├── search.js
└── content.js

SKILL.md:

---
name: brave-search
description: Web search and content extraction via Brave Search API. Use for searching documentation, facts, or any web content.
---

# Brave Search

## Setup

\`\`\`bash
cd ${DREB_SKILL_DIR} && npm install
\`\`\`

## Search

\`\`\`bash
./search.js "query"              # Basic search
./search.js "query" --content    # Include page content
\`\`\`

## Extract Page Content

\`\`\`bash
./content.js https://example.com
\`\`\`

Built-in Skills

dreb ships with mach6, a development workflow that orchestrates the full issue-to-merge lifecycle using GitHub as shared memory. Six skills cover each stage:

Skill What it does
mach6-issue Assess an existing issue or create a new one
mach6-plan Explore codebase, plan, create branch and draft PR
mach6-push Commit, push, post progress comment
mach6-review Explicit round-aware review with delta re-reviews, three-gate assessment, and later-round adversarial counter-pressure
mach6-implement Implement plans, fix review findings, or fix CI failures
mach6-publish Pre-merge checks, docs update, merge, tag, release
model-routing-guide Research scoped models and sanitized local subagent evidence into a validated routing guide

Built-in skills are always available and can be overridden by placing a skill with the same name in any user or project location. mach6-review is model-invocable when the user directly asks an agent to run it, as well as user-invocable through its slash command. Agents must never start formal review autonomously; implementation must first be committed and pushed.

See docs/mach6.md for full documentation.

model-routing-guide

model-routing-guide is an explicit, potentially expensive research workflow with exactly two supported scope sources.

Pass comma-separated model patterns directly to make them authoritative:

/skill:model-routing-guide anthropic/claude-*,openai/gpt-5.6-sol

Or invoke it without arguments to use the effective non-empty enabledModels array:

/skill:model-routing-guide

When model scope rotates, update the existing guide incrementally instead of regenerating every retained entry:

/skill:model-routing-guide update
/skill:model-routing-guide update anthropic/claude-*,openai/gpt-5.6-sol

update must be the first argument. The skill validates the existing guide against its own coverage, diffs that coverage against the newly resolved authoritative scope, preserves retained model sections, removes unscoped sections and summary references, and researches only newly added canonical models. It refreshes scope/local-evidence metadata and performs the same complete final validation before atomically replacing the guide. A missing or malformed existing guide fails loudly and requires normal generation.

Model-pattern arguments after the optional update keyword take precedence over enabledModels; the skill selects one source and does not search for any other runtime or session scope. Because this Stage 1 workflow is implemented only as a skill, it cannot discover the current session's --models value or later in-session scope changes. To research that runtime scope, pass the same comma-separated patterns as skill arguments.

The skill refuses missing/empty and effectively all-model scopes. It obtains available candidates with dreb --list-models, resolves the selected patterns to canonical provider/model IDs, and snapshots subagent evidence before launching research children. It reads global-only subagentSessionDir using AgentSession path semantics, then also reads the legacy <agent-dir>/subagent-sessions root when different, in that order with canonical deduplication; project settings cannot redirect this evidence scan and no files are migrated. It combines sanitized aggregate local observations with official documentation, model cards, benchmarks, issue trackers, forums, and practitioner reports. Existing unreadable or malformed snapshotted child logs fail the run; genuinely empty history across all discovery roots is labeled cold-start.

The generated ~/.dreb/agent/model-routing-guide.md is human-readable Markdown with schema-versioned YAML frontmatter and one validated section per canonical candidate. Evidence is labeled as vendor claims, measured benchmarks, community reports, or local observations, with dates, confidence, sample counts, contrary findings, and explicit unknowns. The workflow prohibits copied prompts, outputs, tool arguments, secrets, paths, and identifying project details.

Semantic local-evidence assessment uses normal dreb tools, so inspected session content is processed by the active research model's configured provider. The persisted guide is sanitized and generalized, but invoking the skill is still a decision to send the inspected evidence to that provider.

Its primary routing safeguards are practical: Explore is for factual collection and navigation, not planning or implementation; routine lookup, extraction, repetitive file inspection, and straightforward summarization should use the least expensive scoped model demonstrated adequate by the evidence.

The optional global-only Dispatch Arbiter now consumes this file before every subagent spawn. Its live scope is the current session's exact explicit candidate set, so guide frontmatter and model headings must match that set exactly. A guide generated from enabledModels will work when the session uses the same resolved scope; for runtime --models, pass those patterns to the skill. Missing/stale/malformed guide coverage fails the child launch rather than bypassing arbitration.

Skill Repositories

  • Anthropic Skills - Document processing (docx, pdf, pptx, xlsx), web development
  • Pi Skills - Web search, browser automation, Google APIs, transcription (from pi-mono, dreb's upstream fork)