warp

The warp package implements the Workspace Agent Resource Protocol (WARP) — a provider-agnostic, declarative format for defining AI agents and their supporting resources.

Warp is not tied to any particular LLM provider, orchestration framework, or runtime. Any tool that understands the format can load and execute the same resource files unchanged.

Getting Started

To add warp to your Go project:

go get github.com/your-username/warp

(Replace your-username with the appropriate repository path once hosted.)

File Format

---
apiVersion: warp/v1alpha1
kind: Agent            # Agent | Skill | Command
metadata:
  name: my-agent
  description: A helpful assistant.
spec:
  models: ["gpt-4o"]
  temperature: 0.7
  skills:
    - skills/finance.md
  commands:
    - commands/report.md
---

# My Agent

You are a helpful assistant that specializes in financial analysis...

Resource Kinds

Kind	Purpose
Agent	An autonomous agent with LLM configuration and references to the skills and commands it may invoke.
Skill	A bundle of expertise guidelines for a specific domain. Agents load skills to adopt a persona or follow conventions.
Command	A discrete, reusable operation an agent can invoke (e.g. "generate a report").

Loading Resources

OS filesystem — default directory

// Loads from .agents/ in the current working directory.
registry, err := warp.LoadDefault()
if err != nil {
    log.Fatal(err)
}

if err := registry.Validate(); err != nil {
    log.Fatal(err)
}

OS filesystem — custom directory

registry, err := warp.Load("/custom/path")

Custom fs.FS (embedded assets, testing, etc.)

//go:embed testdata
var testFS embed.FS

registry, err := warp.NewLoader(testFS).Load()

Programmatic Plugin Discovery

// Discovers resources exposed by a plugin before installing it.
resources, err := warp.DiscoverPluginResources("github.com/acme/finance-skills", "v1.2.0")
for _, r := range resources {
    fmt.Printf("Resource: %s/%s (%s)\n", r.Kind, r.Name, r.Description)
}

Programmatic Plugin Installation

// Installs a plugin into the workspace at the current directory.
err := warp.InstallPlugin(".", "github.com/acme/finance-skills", "v1.2.0", []string{"Skill/hello"})

Directory Layout

The default root directory is .agents. Inside it, resources are organised by kind into sub-directories:

.agents/
├── commands/         # Command definitions
│   └── report.md     # kind: Command
├── defs/             # Agent definitions
│   └── analyst.md    # kind: Agent
├── skills/           # Skill definitions
│   └── finance.md    # kind: Skill
├── tools/            # Tool definitions
├── mcps/             # MCP server definitions
└── providers/        # Model Provider definitions

API Reference

Types

• Registry – holds parsed resources indexed by their FS-relative path.
  • Agents, Skills, Commands — typed maps.
  • Validate() error — checks required fields and resolves Agent cross-references.
• Loader – walks an fs.FS and parses every .md file it finds.
  • NewLoader(fsys fs.FS) *Loader
  • Load() (*Registry, error)
• Load(root string) (*Registry, error) — loads resources from the given OS filesystem path.
• LoadDefault() (*Registry, error) — loads resources from the default .agents directory in the current working directory.
• Parse(content string) (*ParseResult, error) — parses a single warp Markdown string and returns the typed resource.
• DiscoverPluginResources(source, version string) ([]DiscoveredResource, error) — fetches the plugin at the given source/version and returns the list of all resources exposed by it.
• InstallPlugin(workspaceDir, source, version string, imports []string) error — downloads a plugin, computes its hashes, writes them to warp.lock, and registers the plugin in WORKSPACE.md.

Validation & Tooling

CLI Tool

Warp includes a CLI tool for validating your resources and workspaces.

# Build the tool
go build -o warp ./cmd/warp

# Validate a workspace
./warp validate .

JSON Schema

A JSON Schema is available at schema/warp.json to provide real-time validation and autocompletion in IDEs like VS Code.

To use it in VS Code, add the following to your settings (requires the YAML extension):

"yaml.schemas": {
  "https://raw.githubusercontent.com/masterkeysrd/warp/main/schema/warp.json": [
    "**/.agents/**/*.md",
    "**/AGENT.md",
    "**/WORKSPACE.md"
  ]
}

Contributing

We welcome contributions! Please see the CONTRIBUTING.md file (if available) or open an issue to discuss your proposed changes.

License

This project is licensed under the Apache License 2.0.