suphia 0.1.3

A deterministic, cross-platform agent skill publisher.

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 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.

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