Skills

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

Skills are portable and composable. You can share them across teams or pull 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 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

Skill discovery is adapter-owned. The concrete paths where skills are found depend on which harness adapter you are using. Adapters locate skill files and make them available for Weave to resolve by name.

Adapter-owned discovery

The exact filesystem paths for skills (e.g., under a .weave/ or harness-specific directory) are determined by your adapter. Consult your adapter's documentation for the canonical skill directory layout.

Assigning Skills to Agents

Add a skills array to any agent block in your .weave config:

agent shuttle {
  models ["anthropic/claude-sonnet-4-5"]
  mode subagent
  skills ["react-best-practices", "typescript-strict", "testing"]
}

agent pattern {
  models ["anthropic/claude-opus-4"]
  mode subagent
  skills ["api-design"]
}

Each skill listed must be discoverable by the adapter.

Disabling Skills

To exclude a skill from all agents, even if it exists in the skill path:

disable skills ["tdd", "some-inherited-skill"]

This is useful when you have inherited skills from a shared library and want to opt out of specific ones for a particular project.

Example: Using a Third-Party Skill

Skills are portable, so you can use community-maintained ones. For example, to use a TDD skill:

1. Place the SKILL.md file where your adapter can discover it.
2. Assign it to Shuttle in your config:

agent shuttle {
  models ["anthropic/claude-sonnet-4-5"]
  mode subagent
  skills ["tdd"]
}

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.