Suphia

Suphia is a compatibility layer for AI agent ecosystems.

It provides a set of tools that allow developers to work with multiple, fast-evolving AI agents using a single source of truth for context and configuration — without duplication.

Suphia is designed to keep context close to your code, while adapting that context to many different agents and formats.

---

The Problem Suphia Solves

AI development today rarely involves just one agent.

Developers often experiment with:

• Claude
• Gemini
• Copilot
• OpenCode
• Codex
• new or experimental agents
• changing formats and conventions

Each agent introduces:

• different discovery rules
• different configuration formats
• different expectations about layout

Without Suphia, developers end up:

• copying context files again and again
• restructuring repos for each tool
• losing alignment between code and context

Suphia exists so you adapt once, not agent-by-agent.

---

Suphia’s Core Idea

Keep one canonical source of context, close to your code, and project it outward to any agent that needs it.

Suphia does not enforce a single format. It provides adapters and tooling so agents can coexist.

---

What Suphia Is

• A CLI toolset
• A Python module library
• An adapter layer between agent ecosystems

Suphia can be:

• used directly via CLI
• integrated into other frameworks
• embedded in automation or CI

---

What Suphia Is Not

• An agent runtime
• A prompt framework
• A vendor-specific solution

Suphia complements agents — it does not replace them.

---

Initial Focus: Skills

Suphia v1 starts with skills as a practical, high-impact use case.

It allows you to:

• Place skills anywhere in your repo
• Keep them near relevant code
• Discover them recursively
• Publish them into agent-specific discovery roots
• Avoid copying or rewriting skill files

This enables skill reuse across:

• Claude-style agents
• Copilot-style agents
• OpenCode and others

See docs/SuphiaSkillLifecycleDesign.md for the planned skill lifecycle model, including bundle/extract workflows, the target registry, self-skills, global/local/custom scopes, Windows/WSL support, and shared terminology.

Implemented CLI examples:

suphia skills validate --source .
suphia skills plan --source . --target generic --scope local
suphia skills publish --source . --target opencode --scope global
suphia skills bundle --source . --output skills.suphia --profile public --all
suphia skills bundle --source . --output selected.suphia --include lint
suphia skills bundle --output selected.suphia --select
suphia skills bundle --output selected.suphia --include "lint,docs-*" --include "re:^test-"
suphia skills extract skills.suphia --target generic --scope local --all
suphia skills extract skills.suphia --dest .claude/skills --include lint
suphia self install-skills --target generic --scope global
suphia targets list
suphia targets show vscode-copilot
suphia templates copy vscode-copilot/openai-compatible.template.json --dest ./template.json
suphia -v

After installing or upgrading with uv tool install suphia or uv tool upgrade suphia, refresh Suphia's packaged usage skill explicitly:

suphia self install-skills --target generic --scope global

Package upgrades do not mutate skill copies already installed into agent roots.

Use --security-policy policy.json with skills validate or skills bundle to add repository-specific denylist patterns or safe placeholder values without storing secrets in the repository.

When skills bundle --source is omitted, Suphia auto-detects a skill source by checking global user roots such as ~/.claude/skills and ~/.config/opencode/skills, then the detected workspace/current path. Use --select to show an arrow-key toggle menu with skill origin hints; use Space to toggle, Enter to confirm, all to select every listed skill, and q/Esc to abort. Use --include with exact names, comma-separated lists, glob patterns, or regex patterns written as re:<pattern> or /pattern/. Bundle and extract require explicit selection intent: use --all, --include, or --select. Do not combine --all with selective options. Combining --include with --select lists the matching candidate skills before bundling. Bundles record whether they came from a global user root, local workspace root, or custom path. During interactive extraction, Suphia lists bundled skills first, then shows source metadata and lets you install to the global user root, the current workspace root, or choose global/local per skill. Per-skill mode shows one table of selected skills where Space toggles the highlighted row between global and local, and Enter confirms the whole table. Bundle and extract commands print highlighted scan, selection, write, and install progress so long-running operations stay visible. After bundling, Suphia prints next-step extract commands for another workspace or PC. After extraction, it prints the install location and a validation command.

Project defaults can be stored in suphia.json or .suphia.json:

{
  "target": "generic",
  "scope": "local",
  "profile": "public",
  "excludes": [".venv"],
  "security_policy": "suphia-security.json"
}

For Windows/WSL migration patterns, see docs/WindowsWslMigration.md.

---

Installation

Suphia uses uv for Python tooling.

Install:

uv pip install suphia