byo-skill

Drop-in Agent Skill for BYO. Once installed, Cursor / Claude Code / Codex / GitHub Copilot / Goose / OpenCode / any SKILL.md-aware AI knows how to integrate BYO into your codebase the right way the first time:

• which key (pk_ vs sk_) goes where
• the canonical SDK calls and OpenAI-compat drop-in
• webhook signature verification (raw body, timing-safe HMAC)
• the typed error hierarchy and what each one means
• the BYOA / MCP integration
• the gotchas that surface as cryptic 401s and 403s otherwise

It's the same shape we use internally — three files, ~600 lines total, zero runtime dependencies. Strictly follows the open Agent Skills spec (originally from Anthropic, now adopted by every major coding agent).

Install

npx byo-skill install

Default install path is ./.agents/skills/byo/ — the cross-client convention every spec-compliant tool (Cursor, Claude Code, Codex, Copilot, Goose, OpenCode, OpenHands, Junie, Roo Code, …) scans on startup. One install, every tool picks it up. Commit it to git and your whole team's agents stay in sync.

When run outside a repo, it falls back to ~/.agents/skills/byo/.

Install for a specific tool

If you'd rather scope to one tool's native path:

npx byo-skill install --target cursor-project       # ./.cursor/skills/byo/
npx byo-skill install --target cursor-personal      # ~/.cursor/skills/byo/
npx byo-skill install --target claude-personal      # ~/.claude/skills/byo/
npx byo-skill install --target codex-personal       # ~/.codex/skills/byo/
npx byo-skill install --target openclaw-personal    # ~/.openclaw/workspace/skills/byo/
npx byo-skill install --dest ./docs/agent/byo       # custom path

After installing, restart your agent (or open a fresh chat) so it picks up the new skill. Then try:

"Add BYO to this app so my customers can bring their own OpenAI keys."

What ships

.agents/skills/byo/
├── SKILL.md                    # injected when triggered (BYO, BYOK, byo-sdk, …)
└── references/
    ├── REFERENCE.md            # full SDK + REST surface, errors, env vars
    └── EXAMPLES.md             # Next.js, FastAPI, Express, LangChain, MCP

Layout matches the agentskills.io directory spec. The skill uses progressive disclosure — SKILL.md is short and always-on, the files in references/ are read by the agent only when the specific task needs them (so a one-line "what's a refId?" question doesn't pull in ~600 lines of context).

Update

npx byo-skill@latest install --force

--force overwrites the local copy. Without it, files that have been edited locally are preserved.

Uninstall

rm -rf ./.agents/skills/byo            # or wherever you installed it

Validate (optional)

The skill is checked against the skills-ref reference validator before each release. To re-validate locally:

npx skills-ref validate ./.agents/skills/byo

Python users

The skill itself is language-agnostic — same SKILL.md works whether you end up calling byo-sdk (Node) or byok (PyPI). If you'd rather not have Node at all, copy the directory manually:

git clone --depth 1 https://github.com/treadiehq/byo /tmp/byo
mkdir -p ./.agents/skills/byo
cp -R /tmp/byo/packages/skill/skill/. ./.agents/skills/byo/

License

FSL-1.1-MIT, same as the rest of BYO.