skill - extend agent capabilities with SKILL.md packages

OVERVIEW

Skills are SKILL.md-based capability packages that extend the agent's system prompt. Each skill is a directory containing a SKILL.md file with YAML frontmatter and markdown instructions. When loaded, skill headers appear in the system prompt under AVAILABLE SKILLS. The agent reads the full SKILL.md on demand via read_file.

Philosophy: new agent capabilities should be skills, not hardcoded features. Skills are the primary extension mechanism — composable, installable, and shareable.

SKILL TYPES

Native Skills

Location: /workspace/skills/<name>/

Install-managed via skill install and skill uninstall. Can include a manifest.yaml for structured installation (file additions, modifications, dependency/conflict declarations). These are the only skills that support install/uninstall lifecycle management.

Compatibility Skills

Discovered read-only from .agents/skills/*/SKILL.md and .claude/skills/*/SKILL.md anywhere in the reachable VFS. These are not install-managed — they remain read-only unless explicitly copied into /workspace/skills/. Discovery is recursive and cached, with cache invalidation on filesystem mutations.

Discovery Precedence

When multiple skills share the same name, precedence is: native > .agents > .claude. The highest-precedence skill wins; lower-precedence duplicates are shadowed.

SKILL.MD FORMAT

---
name: my-skill
description: Teaches the agent how to do X
allowed-tools: Bash(my-command:*)
---

# My Skill

Instructions for the agent go here in markdown.
The agent reads this content via read_file when it needs to use the skill.

Frontmatter fields:

name — Skill identifier (defaults to directory name)
description — What the skill does (shown in system prompt)
allowed-tools — Optional tool restrictions for the skill

MANIFEST.YAML

Native skills can optionally include a manifest.yaml for structured installation:

skill: my-skill
version: 1.0.0
description: What this skill does
adds:
  - path/to/new/file
modifies:
  - path/to/existing/file
depends:
  - other-skill
conflicts:
  - incompatible-skill
test: bash run-tests.sh
author: Your Name

SKILL CONTENTS

A skill directory can contain more than just SKILL.md:

.jsh scripts — JavaScript shell scripts that become shell commands. Discovered automatically; command name is the filename without .jsh.
Assets — Images, data files, templates, or any supporting files the skill needs.
.shtml files — Sprinkle panels that provide interactive UI.

SYSTEM PROMPT INTEGRATION

During scoop initialization, skills are loaded from /workspace/skills/ (for the cone) or /scoops/{name}/workspace/skills/ (for scoops), plus any accessible compatibility roots. The system prompt includes a summary:

AVAILABLE SKILLS

The following skills are available. To use a skill, first read its full instructions:
  read_file({ "path": "<skill path>" })

- **skill-name**: Description of what it does
  Path: /workspace/skills/skill-name/SKILL.md

Only headers are injected by default — full content is loaded on demand to preserve context window space.

SKILL CATALOG

The built-in catalog at /shared/skill-catalog.json lists curated skills with metadata including display names, descriptions, source repositories, and affinity tags (apps, tasks, role, purpose). Used by upskill recommendations to suggest skills matching the user's profile.

SHELL COMMANDS

skill — Local skill management

skill list                    List discoverable skills and their status
skill info <name>            Show details about a skill
skill read <name>            Read the SKILL.md instructions
skill install <name>         Install a native /workspace/skills skill
skill uninstall <name>       Uninstall a native /workspace/skills skill

Discovery roots: /workspace/skills plus accessible **/.agents/skills/* and **/.claude/skills/* anywhere in the VFS. Only native /workspace/skills entries are install-managed.

upskill — External skill sources

upskill search "query"                    Search ClawHub + Tessl registries
upskill owner/repo --list                 List skills in a GitHub repo
upskill owner/repo --all                  Install all skills from a repo
upskill owner/repo --skill name           Install a specific skill
upskill owner/repo --path subdir --all    Restrict to a subfolder
upskill owner/repo@branch --all           Install from a specific branch
upskill clawhub:user/skill                Install from ClawHub
upskill https://clawhub.ai/user/skill     Install from ClawHub URL
upskill tessl:skill-name                  Install from Tessl registry
upskill recommendations                   Show profile-matched suggestions
upskill recommendations --install         Install all recommended skills

Options:

--skill <name>      Install specific skill (repeatable)
--all               Install all skills from source
--path <subfolder>  Only discover skills under this subfolder
--branch, -b <name> Install from a specific branch (default: main)
--list              List available skills without installing
--force             Overwrite existing skills

GitHub rate limits: anonymous access may be rate-limited on shared IPs. Configure a token: git config github.token <PAT>

STATE

Installation state is tracked in /.slicc/state.json, recording which native skills have been applied and their versions. The skills system version is currently 1.0.0.