Skills

Skills are reusable knowledge modules stored as SKILL.md files. When assigned to an agent, a skill's content is prepended to that agent's prompt — injecting domain expertise without modifying the base prompt.

Skills are Weave's primary extension mechanism. They're portable, composable, and can be shared across teams or pulled from open-source repos.

Skill File Structure

A skill is a Markdown file with YAML frontmatter:

---
name: react-best-practices
description: React development guidelines
---

# React Best Practices

- Use functional components with hooks
- Memoize expensive computations with useMemo and useCallback
- Test with React Testing Library, not enzyme
- Prefer composition over inheritance

The name field in the frontmatter is the identifier you use when assigning the skill to agents. The description helps Loom understand what the skill provides when building delegation prompts.

Where Skills Live

Weave discovers skills through two mechanisms:

1. OpenCode API (Primary)

Weave fetches skills from OpenCode's HTTP API (GET /skill). OpenCode aggregates skills from its standard locations and returns them to Weave — so you manage skills in one place (OpenCode's skill directories) and Weave consumes them automatically.

2. Filesystem Fallback

If the API is unavailable or returns no results, Weave scans the filesystem directly:

Location	Scope	Description
.opencode/skills/	Project	Project-specific skills
~/.config/opencode/skills/	User	Your personal skill library

Precedence

When both sources return skills, API results take precedence over filesystem results for skills with the same name. Within the filesystem fallback, project-level skills override user-level skills.

Assigning Skills to Agents

Add a skills array under any agent in your config:

{
  "agents": {
    "shuttle": {
      "skills": ["react-best-practices", "typescript-strict", "testing"]
    },
    "tapestry": {
      "skills": ["tdd"]
    }
  }
}

Each skill listed must exist as a SKILL.md file discoverable via the OpenCode API or in one of the filesystem skill directories.

Dynamic Skill Injection

Beyond static assignment in config, Loom can inject skills dynamically at runtime. When delegating to Shuttle, Loom passes load_skills based on the task context — so if Loom determines a task involves React, it can inject your react-best-practices skill automatically.

This means well-named, well-described skills get used more intelligently without any manual wiring.

Example: Using a Third-Party Skill

Skills are portable, so you can use community-maintained ones directly. For example, to use Matt Pocock's TDD skill:

1. Download the SKILL.md file and place it at .opencode/skills/tdd/SKILL.md
2. Assign it to Shuttle in your config:

{
  "agents": {
    "shuttle": {
      "skills": ["tdd"]
    }
  }
}

3. Shuttle will now follow a red-green-refactor TDD workflow when writing code.

Skills vs. Prompt Append

Use skills for reusable domain knowledge you want to share across projects or teams (React patterns, testing conventions, API guidelines). Use prompt_append for project-specific instructions that don't need to be portable.

Example Skill Library

A typical project might have these skills in .opencode/skills/:

.opencode/skills/
├── company-standards/SKILL.md    # Code style, review checklist, internal conventions
├── testing/SKILL.md              # Testing patterns, coverage requirements
├── typescript-strict/SKILL.md    # Strict TypeScript settings and patterns
└── api-design/SKILL.md           # REST API design guidelines

Assign them selectively to the agents that need them:

{
  "agents": {
    "shuttle": {
      "skills": ["company-standards", "testing", "typescript-strict"]
    },
    "pattern": {
      "skills": ["api-design"]
    }
  }
}