File-Based Prompts — External Prompt Loading Skill

File-Based Prompts — External Prompt Loading

Use this skill to load agent system prompts from external files instead of embedding them in config. Enables version control, sharing, and cleaner configuration.

How It Works

Instead of embedding prompts in JSON:

// ❌ Embedded prompt (hard to version, hard to share)
{
  "agents": {
    "hermes": {
      "prompt": "You are Hermes, the backend specialist. Your expertise is..."
    }
  }
}

Load from files:

// ✅ File-based prompt (versioned, shareable)
{
  "agents": {
    "hermes": {
      "prompt": "file://./prompts/hermes-prompt.md"
    }
  }
}

Supported Path Formats

| Format | Example | Resolves To | |--------|---------|-------------| | Relative | file://./prompts/hermes.md | <project>/prompts/hermes.md | | Home expansion | file://~/prompts/hermes.md | ~/.config/opencode/prompts/hermes.md | | Absolute | file:///opt/prompts/hermes.md | /opt/prompts/hermes.md |

Use Cases

1. Version Control Prompts Separately

project/
├── opencode.json          # Config (prompt references)
├── prompts/
│   ├── hermes-prompt.md   # Backend specialist prompt
│   ├── aphrodite-prompt.md # Frontend specialist prompt
│   └── themis-prompt.md   # Review specialist prompt

Prompts can be versioned independently from config.

2. Share Prompts Across Projects

~/.config/opencode/prompts/
├── hermes-prompt.md       # Shared across all projects
├── aphrodite-prompt.md
└── themis-prompt.md

{
  "agents": {
    "hermes": {
      "prompt": "file://~/prompts/hermes-prompt.md"
    }
  }
}

3. Append Category-Specific Context

{
  "categories": {
    "deep": {
      "prompt_append": "file://./prompts/deep-category-append.md"
    }
  }
}

Appends additional context to the category's prompt without duplicating the base prompt.

Prompt File Format

Prompt files are plain markdown:

# Hermes — Backend Specialist

You are the **BACKEND TASK IMPLEMENTER** (Hermes) called by Zeus to implement
FastAPI endpoints, services, and routers.

## Core Principles
- TDD first: write tests that fail, write minimal code to pass
- Async/await on all I/O operations
- Type hints on all parameters
- Max 300 lines per file

## Your Tools
- FastAPI, SQLAlchemy, Pydantic, Redis
- pytest for testing
- ruff for linting

## When to Delegate
- @apollo for codebase discovery
- @themis for code review
- @demeter for database migrations

Benefits

| Benefit | Description | |---------|-------------| | Version control | Prompts in git, track changes over time | | Sharing | Same prompt across multiple projects | | Cleaner config | Config files stay concise | | Easier editing | Edit prompts in any text editor | | Category context | Append category-specific instructions without duplication |

Integration

This is a configuration feature, not a runtime skill. The file is loaded once at agent startup and injected into the system prompt.

Agent Skills: File-Based Prompts — External Prompt Loading

Install this agent skill to your local

Skill Files