Skip to main content

​
Source layout

When authoring a facet, organize your files like this: 
my-facet/
  facet.yaml                    # Manifest (required)
  skills/
    my-skill/
      SKILL.md                  # Skill instructions
  prompts/
    my-agent.md                 # Agent prompt body
    my-command.md               # Command prompt body
  opencode/
    tools/
      my-tool.ts                # Tool implementation
The facet.yaml manifest references these files: 
name: my-facet
version: 1.0.0
skills:
  - my-skill                    # → skills/my-skill/SKILL.md
agents:
  my-agent:
    prompt: prompts/my-agent.md # → prompts/my-agent.md
commands:
  my-command:
    prompt: prompts/my-command.md
platforms:
  opencode:
    tools:
      - my-tool                 # → opencode/tools/my-tool.ts

​
Installed layout

After facets install, resources are materialized into the project’s .opencode/ directory: 
.opencode/
  facets.yaml                   # Project dependencies
  facets.lock                   # Lock file
  skills/
    my-skill/
      SKILL.md                  # Copied verbatim from source
  agents/
    my-agent.md                 # Assembled: frontmatter + prompt body
  commands/
    my-command.md               # Assembled: frontmatter + prompt body
  tools/
    my-tool.ts                  # Copied verbatim from source

​
How files are processed

​
Skills — verbatim copy

Skill files are copied exactly as they are from source to destination.
SourceDestination
skills/<name>/SKILL.md.opencode/skills/<name>/SKILL.md

​
Agents — assembled with frontmatter

Agent files are not copied verbatim. The prompt body is read from the source file, and YAML frontmatter is prepended based on the manifest’s agent descriptor. Given this manifest: 
agents:
  my-agent:
    description: Does a thing
    platforms:
      opencode:
        tools:
          write: false
And this prompt file (prompts/my-agent.md): 
You are an agent that does a thing.

Follow these steps...
The installed file at .opencode/agents/my-agent.md becomes: 
---
description: Does a thing
tools:
  write: false
---

You are an agent that does a thing.

Follow these steps...
The frontmatter includes:
  • description from the agent descriptor (if present)
  • tools from platforms.opencode.tools (if present)

​
Commands — assembled with frontmatter

Commands follow the same pattern as agents, but the frontmatter only includes description: 
---
description: What it does
---

Command prompt body here...

​
Tools — verbatim copy

Tool TypeScript files are copied exactly as they are.
SourceDestination
opencode/tools/<name>.ts.opencode/tools/<name>.ts

​
Cache layout

When a remote facet is cached (via facets add or facets update), it’s stored at ~/.cache/facets/<name>/ with the same structure as the source layout: 
~/.cache/facets/my-facet/
  facet.yaml
  skills/my-skill/SKILL.md
  prompts/my-agent.md
  prompts/my-command.md
  opencode/tools/my-tool.ts
The cache location respects $XDG_CACHE_HOME if set (defaults to ~/.cache).

​
Local facets

Local facets live in your project at .opencode/facets/<name>/ and follow the same source layout: 
.opencode/facets/my-facet/
  facet.yaml
  skills/...
  prompts/...
Local facets are resolved before cached remote facets during installation.