Instruction, not runtime codeA Skill teaches an Agent a workflow. A plugin contributes code and effects. Put Skills in discovered roots; do not install them with dsh plugin add.

Create one project Skill.

mkdir -p .dsh/skills/repository-review/references

$EDITOR .dsh/skills/repository-review/SKILL.md
---
name: repository-review
description: Review a repository change for correctness, safety,
  and missing tests. Use for PRs, patches, and pre-merge audits.
---

# Repository review
1. Read changed files and their callers.
2. Cite evidence for every confirmed defect.
3. Check failure paths, permissions, cleanup, and tests.
4. Do not edit unless the user asks for a fix.

The description owns routing.

CatalogName + description

Small, sorted, model-visible. State the outcome and when to use it.

LoadFull body

Workflow, safety conditions, completion evidence, and links.

ResourcesOn demand

References, scripts, and assets resolve relative to the Skill bundle.

Choose one of two invocation paths.

Agent-selectedMatch the task
Review this patch for correctness, safety, and missing tests.

The catalog description routes the model to the skill tool.

or
User-explicitName it directly
/repository-review Review this patch. Do not edit files.

The full body is injected once; the Agent must not load it again.

Prove four signals.

  1. 01The expected name and description appear in the catalog.
  2. 02The current body is selected or explicitly injected.
  3. 03The response exhibits the workflow's observable constraints.
  4. 04The result cites real repository evidence.

Know which root wins.

100project .dsh
200project .agents
300custom
400user .dsh
500user .agents
600bundled

Lower rank wins within one scope layer. A nearer Agent scope wins the same name before rank is considered. The project root is the nearest ancestor containing .git, not the nearest monorepo package.

Route a missing Skill.

Wrong root

Inspect the Session cwd and nearest .git.

Wrong shape

Use one direct <name>/SKILL.md or <name>.md entry.

Shadowed name

Identify the nearer scope or lower-rank provider.

Invalid policy

Use exact kebab-case keys and valid YAML booleans.

Loading is not compliance.

A successful Skill call proves instruction availability. Test a positive trigger, a nearby non-trigger, explicit invocation, and observable result constraints.

Primary evidence.

Keep the complete guide.

The canonical guide covers invocation policy, hot refresh, duplicate precedence, monorepo discovery, progressive disclosure, testing, and failure diagnosis.

Read the complete guide on GitHub