add-prompts

Convert prompt-safe single-file agent skills into native prompt entries for Codex, Claude Code, and Pi.

[!IMPORTANT]

Why this exists

Skills are powerful, but a large skills folder can put too much into the agent's always-visible tool/behavior surface. Many workflows do not need automatic skill discovery at all: they only need to be called explicitly when you decide they are relevant.

add-prompts moves those manual-call workflows into prompt/command slots. The agent does not need to carry every skill in its active skill view; you can still load the workflow on demand with a slash command or custom prompt.

add-prompts is intentionally strict: it only converts a skill directory when that directory contains SKILL.md and no other meaningful files. If a skill depends on references/, scripts/, assets/, or any other sibling file, the CLI refuses to convert it because the result would lose behavior.

Coding agent targets

add-prompts writes to the native explicit-invocation prompt/command systems for each supported coding agent:

| Agent | Output type | Docs | | --- | --- | --- | | Codex | Custom prompts | Codex custom prompts | | Claude Code | Slash commands | Claude Code slash commands | | Pi | Prompt templates | Pi prompt templates |

Install from a source

npx add-prompts add https://github.com/tw93/Waza --skill think -a codex -a claude-code -a pi

Supported source formats:

npx add-prompts add owner/repo
npx add-prompts add https://github.com/owner/repo
npx add-prompts add https://github.com/owner/repo/tree/main/path/to/skill
npx add-prompts add https://github.com/owner/repo/blob/main/path/to/skill/SKILL.md
npx add-prompts add https://github.com/owner/repo/blob/main/SKILL.md
npx add-prompts add [email protected]:owner/repo.git
npx add-prompts add ./local-skills

A blob URL that points to a SKILL.md at the repository root is treated as a dependency-free single-file skill: only that file is converted, the surrounding repo (e.g. src/, package.json) is ignored rather than rejected, and the prompt name comes from the file's frontmatter name. For example, npx add-prompts add https://github.com/kaichen/add-prompts/blob/main/SKILL.md installs the to-prompt prompt.

Options

| Option | Meaning | | --- | --- | | -a, --agent <agents...> | Target codex, claude-code, pi, or '*'. | | -s, --skill <skills...> | Convert specific skills by name, or '*'. | | -l, --list | List source skills without installing. | | -g, --global | Install to user prompt directories. This is the default in 0.1.0. | | -y, --yes | Skip confirmations. Included for compatibility with skills-style commands. | | --all | Select every prompt-safe skill. If --agent is absent, target every supported agent. | | --dry-run | Show writes without changing files. | | --overwrite | Replace existing prompt files. | | --full-depth | Search nested skills even when the source root has SKILL.md. | | --bundle-extras | Bundle non-SKILL.md files into the generated prompt as XML-wrapped markdown/scripts/text. |

Output paths

| Agent | Global prompt path | | --- | --- | | Codex | ~/.codex/prompts/<name>.md | | Claude Code | ~/.claude/commands/<name>.md | | Pi | ~/.pi/agent/prompts/<name>.md |

Commands

add-prompts add <source> [options]
add-prompts list [options]
add-prompts remove <names...> [options]
add-prompts init [name]

Companion skill: to-prompt

The repo ships a bundled agent skill, SKILL.md (to-prompt), the in-conversation counterpart to the CLI. Where the CLI converts existing skill directories into prompts, to-prompt lets an agent stash a workflow, set of notes, or cautions you produced mid-session as a reusable prompt/command — persist now, re-import as context on demand instead of retyping.

It writes to the same native slots the CLI targets:

• Codex → ~/.codex/prompts/<slug>.md
• Claude Code → ~/.claude/commands/<slug>.md
• Pi → ~/.pi/agent/prompts/<slug>.md

Install it like any skill (e.g. npx add-prompts add kaichen/add-prompts --skill to-prompt -a '*'), then ask the agent to "save this as a prompt for all agents."

Examples

List convertible skills:

npx add-prompts add https://github.com/tw93/Waza --list

Install Waza's think workflow to Codex:

npx add-prompts add https://github.com/tw93/Waza --skill think -a codex

Preview writes before changing files:

npx add-prompts add https://github.com/tw93/Waza --skill think -a codex --dry-run

Install output includes the generated prompt markdown length:

would-create think for Codex: ~/.codex/prompts/think.md (1,234 chars)

Bundle a multi-file skill into one prompt:

npx add-prompts add https://github.com/mattpocock/skills/blob/main/skills/productivity/handoff/SKILL.md -a codex --bundle-extras

Remove an installed prompt:

npx add-prompts remove handoff -a codex

Prompt-safe rule

Accepted:

think/
  SKILL.md

Rejected:

think/
  SKILL.md
  references/

The rejected form should remain a skill. add-prompts converts explicit workflows into prompt templates; it does not emulate skill loading.

Pass --bundle-extras only when you intentionally want those extra files embedded into the generated prompt. Extra markdown files are wrapped in <markdown> tags, scripts in <script> tags, and other text files in <file> tags inside a <skill_bundle> block.