Agent Skills

Portable AI-agent workflows for Pi, Claude Code, and Codex. This repository keeps reusable skills, Claude-style sub-agents, and shared prompt templates in one source so workflows can be authored once and used across clients.

Related repositories

These independently usable repositories are installed and versioned separately, but complement the workflows here:

• AI Tools — runtime tools and configuration glue for Pi, Claude Code, and Codex.
• Pi Skill Model Router — an optional Pi extension that maps this repository's portable routing metadata to locally configured models.

What you get

• Skills — focused workflows stored as skills/<name>/SKILL.md and installed into the portable ~/.agents/skills/ root.
• Agents — Claude-style sub-agent definitions stored in agents/ and installed into ~/.claude/agents/.
• Prompt templates — shared Pi and Claude Code slash commands stored in prompts/; Pi links are managed automatically and Claude Code setup remains manual.

Browse the skills catalog for the complete list.

Quick start

git clone https://github.com/flurdy/agent-skills.git
cd agent-skills
make dry-run   # preview managed symlink changes
make apply     # install skills, Claude aliases/agents, and Pi prompts
make doctor    # verify the installation

The installer manages individual symlinks rather than replacing destination roots, so unrelated user-owned skills, agents, and prompts remain untouched.

Client support

Client	Skills	Agents	Prompt templates
Pi	Discovers ~/.agents/skills/	Not managed by this repository	Managed links in ~/.pi/agent/prompts/
Codex	Discovers ~/.agents/skills/	Uses Codex-native agent support	Not installed; custom prompts are deprecated
Claude Code	Managed aliases in ~/.claude/skills/	Managed links in ~/.claude/agents/	Manual configuration

make apply-codex remains as a compatibility alias for applying the shared skill root and Claude compatibility aliases, without Claude-style agents or Pi prompts.

How it works

The assembler resolves shared and optional private layers, preflights collisions, and creates managed symlinks in each client location. Later layers can override units with the same name without copying shared content.

agent-skills/
  skills/<name>/SKILL.md
  agents/<name>.md
  prompts/<name>.md
  docs/
  assemble.sh
  Makefile

Detailed destination variables, private layers, migration behavior, and cleanup rules live in the installation and configuration guide.

Model routing

Shared skills declare portable capability and reasoning requirements in frontmatter:

model-tier: standard
effort: medium

The supported tiers are economy, standard, and premium; reasoning effort is low, medium, high, or xhigh. These values describe what a workflow needs, not a fixed provider or model. Exact model IDs, fallback order, billing classification, and spend controls remain runtime-local.

See MODEL_ROUTING.md for the policy. Pi can optionally enforce this metadata with the router described under Related repositories. Claude Code and Codex use their own runtime configuration and capabilities.

Prompt templates

Browse the prompt catalog for the available slash commands. Templates use $ARGUMENTS, which Pi and Claude Code both expand. make apply installs managed Pi links for every top-level template; run /reload in Pi afterward. Follow the prompt-template setup for Claude Code. The commands provide instructions only; none performs Git operations itself.

Optional private overlays

A sibling agent-skills-private/ repository can add private shared units plus machine-, client-, and profile-specific overrides. The resolved order is shared → private → machine → clients. The shared repository remains usable without any private repository.

See Private overlays for the directory layout and commands.

Documentation

• Skills catalog — available workflows and descriptions
• Installation and configuration — destinations, prompts, private layers, migrations, and cleanup
• Contributing — authoring skills and agents, metadata, permissions, validation, and tests
• Model routing — portable tier and effort policy
• Documentation index — public guides and component references

Bugs and pull requests

• Report issues at github.com/flurdy/agent-skills/issues.
• Pull requests are welcome at github.com/flurdy/agent-skills/pulls.

Creator

Created by flurdy.

License

MIT License. See LICENSE.