Skills - Weaver

Skills are reusable knowledge modules that enhance Weaver’s capabilities for specific domains or tasks. They provide specialized instructions, workflows, and context that guide the agent’s behavior.

What are Skills?

A skill is a markdown file (SKILL.md) containing:

Domain-specific instructions
Workflow guides
Best practices
Reference documentation
Tool usage examples

Skills are injected into the agent’s context when needed, providing expertise without requiring code changes.

Skill Sources

Weaver loads skills from three locations (in priority order):

Workspace Skills (<workspace>/skills/) - Project-specific
Global Skills (~/.weaver/skills/) - User-wide
Builtin Skills - Bundled with Weaver

Higher priority sources override lower ones.

Skill Structure

Basic Skill Format

---
name: github
description: GitHub operations and best practices
---

# GitHub Skill

This skill provides expertise in GitHub operations.

## Common Tasks

### Creating a Pull Request
1. Create feature branch: `git checkout -b feature-name`
2. Make changes and commit
3. Push: `git push -u origin feature-name`
4. Use `gh pr create` tool

### Code Review Guidelines
- Check for tests
- Verify documentation
- Review security implications

## Tools Available
- `gh pr create` - Create pull requests
- `gh pr list` - List PRs
- `gh issue create` - Create issues

Frontmatter

Skills use YAML frontmatter for metadata:

---
name: skill-name
description: Brief description of what this skill provides
---

Constraints:

Name: Alphanumeric with hyphens, max 64 chars
Description: Max 1024 chars
Both fields are required

Installing Skills

From GitHub

Install community skills from GitHub repositories:

installer := skills.NewSkillInstaller(workspace)
err := installer.InstallFromGitHub(ctx, "owner/repo")

This fetches SKILL.md from the repository’s main branch and installs it to <workspace>/skills/<repo-name>/.

Manual Installation

Create directory: mkdir -p <workspace>/skills/my-skill
Create skill file: <workspace>/skills/my-skill/SKILL.md
Add frontmatter and content
Restart Weaver or reload skills

List Available Skills

Browse the community skill registry:

installer := skills.NewSkillInstaller(workspace)
available, err := installer.ListAvailableSkills(ctx)

This fetches the skill catalog from:

https://raw.githubusercontent.com/operator.onl/weaver-skills/main/skills.json

Managing Skills

Listing Installed Skills

loader := skills.NewSkillsLoader(workspace, globalPath, builtinPath)
allSkills := loader.ListSkills()

for _, skill := range allSkills {
    fmt.Printf("%s (%s): %s\n", skill.Name, skill.Source, skill.Description)
}

Output:

github (workspace): GitHub operations and best practices
kubernetes (global): Kubernetes cluster management
hardware (builtin): Hardware interfacing with I2C/SPI

Loading a Skill

loader := skills.NewSkillsLoader(workspace, globalPath, builtinPath)
content, ok := loader.LoadSkill("github")
if ok {
    // Skill content (frontmatter stripped)
    fmt.Println(content)
}

Loading Multiple Skills

skillNames := []string{"github", "kubernetes", "docker"}
combined := loader.LoadSkillsForContext(skillNames)
// Returns formatted content with separators

Uninstalling Skills

installer := skills.NewSkillInstaller(workspace)
err := installer.Uninstall("skill-name")

This removes the skill directory from the workspace.

Using Skills in Agents

Auto-Discovery

Weaver automatically discovers and lists skills:

loader := skills.NewSkillsLoader(workspace, globalPath, builtinPath)
summary := loader.BuildSkillsSummary()

Generated XML:

<skills>
  <skill>
    <name>github</name>
    <description>GitHub operations and best practices</description>
    <location>/workspace/skills/github/SKILL.md</location>
    <source>workspace</source>
  </skill>
  <skill>
    <name>docker</name>
    <description>Docker container management</description>
    <location>~/.weaver/skills/docker/SKILL.md</location>
    <source>global</source>
  </skill>
</skills>

This summary is injected into the agent’s system prompt, allowing it to discover and load skills on demand.

Loading Skills on Demand

When the agent identifies a need for a skill:

Agent sees skill in <skills> list
Agent requests skill by name
Skill content is loaded and injected
Agent uses skill knowledge to complete task

Creating Effective Skills

Best Practices

Clear Structure
- Use markdown headings for organization
- Group related information
- Include table of contents for large skills
Actionable Instructions
- Provide step-by-step workflows
- Include code examples
- Reference available tools
Context and Background
- Explain when to use the skill
- Document prerequisites
- Link to external resources
Tool Integration
- List relevant tools
- Show tool usage examples
- Explain tool parameters
Error Handling
- Common failure modes
- Troubleshooting steps
- Fallback strategies

Example: Hardware Skill

---
name: hardware
description: Interface with I2C and SPI devices on Linux
---

# Hardware Interfacing Skill

This skill enables interaction with hardware devices via I2C and SPI buses.

## Prerequisites
- Linux system with I2C/SPI support
- Kernel modules: i2c-dev, spidev
- Device tree configuration

## I2C Operations

### Detecting I2C Buses
```json
{
  "tool": "i2c",
  "args": {"action": "detect"}
}

Reading from Sensor (AHT20)

{
  "tool": "i2c",
  "args": {
    "action": "read",
    "bus": "1",
    "address": 56,
    "length": 6
  }
}

SPI Operations

Listing SPI Devices

{
  "tool": "spi",
  "args": {"action": "list"}
}

Reading from Display

{
  "tool": "spi",
  "args": {
    "action": "read",
    "device": "2.0",
    "speed": 1000000,
    "length": 128
  }
}

Common Issues

Permission Denied

Add user to i2c/spi groups:

sudo usermod -a -G i2c,spi $USER

Device Not Found

Load kernel modules:

sudo modprobe i2c-dev
sudo modprobe spidev

## Skill Registry Format

Community skills are listed in `skills.json`:

```json
[
  {
    "name": "github",
    "repository": "weaver-community/github-skill",
    "description": "GitHub operations and workflows",
    "author": "community",
    "tags": ["git", "github", "vcs"]
  },
  {
    "name": "kubernetes",
    "repository": "weaver-community/k8s-skill",
    "description": "Kubernetes cluster management",
    "author": "devops-team",
    "tags": ["k8s", "containers", "devops"]
  }
]

Advanced Features

Skill Dependencies

Skills can reference other skills:

# Docker Compose Skill

This skill builds on the `docker` skill.
Ensure the docker skill is loaded first.

## Prerequisites
- Load the `docker` skill
- Docker Compose installed

Skill Resources

Bundle additional files with skills:

skills/
  my-skill/
    SKILL.md
    templates/
      config.yaml
    scripts/
      setup.sh

Reference in skill:

See `templates/config.yaml` for configuration template.

Implementation Details

SkillsLoader

type SkillsLoader struct {
    workspace       string
    workspaceSkills string  // <workspace>/skills
    globalSkills    string  // ~/.weaver/skills
    builtinSkills   string  // /usr/share/weaver/skills
}

SkillInfo

type SkillInfo struct {
    Name        string  // Skill identifier
    Path        string  // Absolute path to SKILL.md
    Source      string  // "workspace", "global", or "builtin"
    Description string  // From frontmatter
}

Validation

Skills are validated on load:

Name format: alphanumeric with hyphens
Name length: max 64 characters
Description length: max 1024 characters
Frontmatter presence and format

Performance

Skills are loaded on-demand, not at startup
Frontmatter is parsed only when listing skills
Content is stripped of frontmatter before injection
Skills are cached in memory during agent session

Security

Skills are plain markdown (no code execution)
Workspace skills override global/builtin (user control)
Skill paths are validated to prevent traversal
GitHub installation validates repository format

Get Started

Core Concepts

Guides

Features

​What are Skills?

​Skill Sources

​Skill Structure

​Basic Skill Format

​Frontmatter

​Installing Skills

​From GitHub

​Manual Installation

​List Available Skills

​Managing Skills

​Listing Installed Skills

​Loading a Skill

​Loading Multiple Skills

​Uninstalling Skills

​Using Skills in Agents

​Auto-Discovery

​Loading Skills on Demand

​Creating Effective Skills

​Best Practices

​Example: Hardware Skill

​Reading from Sensor (AHT20)

​SPI Operations

​Listing SPI Devices

​Reading from Display

​Common Issues

​Permission Denied

​Device Not Found

​Advanced Features

​Skill Dependencies

​Skill Resources

​Implementation Details

​SkillsLoader

​SkillInfo

​Validation

​Performance

​Security

Build docs developers (and LLMs) love