Shared Agent Skills
A portable operating layer for AI agents: shared skills, recoverable configuration, and safer execution harnesses.
Generated with quokkify/ci-kit at v3.2.1. Run copier update to apply future template changes; the toolkit owns the versions inside the workflows it renders, and Renovate updates the remaining action references independently.
The project is built around one idea: an agent should be able to learn once, move between providers, recover its setup, and execute through explicit safety boundaries.
Learn → Preserve → Execute safely
The Ecosystem
1. Skills Hub
This repository is the public, canonical source for reusable workflows. Every portable skill lives once under skills/ and can be consumed by Hermes, Claude Code, Codex, or another compatible agent without maintaining provider-specific copies.
- portable
SKILL.md packages;
- references, templates, and deterministic helper scripts;
- review and promotion workflows for reusable lessons;
- validation, privacy checks, and release automation.
2. Genericized Global Adapters
Portable skills describe how to work; a global adapter decides what a runtime loads before any skill runs. This repository publishes that layer as templates and genericized defaults only: a runtime-neutral global instruction base plus cross-runtime lifecycle hook scripts under adapters/shared/, and thin per-runtime wiring under adapters/claude/ and adapters/codex/.
Publishable means: no real credentials, no employer identifiers, no machine paths, no pinned personal model choices, and no session or transcript state. See ADR-0001 for the decision that reversed the earlier "no global configuration" boundary and for the list of content that remains forbidden.
3. Private Configuration Vault
Your real personal configuration needs a different trust boundary. Employer conventions, project trust lists, credentialed MCP servers, employer-only skills, and machine paths live in a separate private overlay repository, merged over the public templates at install time, alongside backups with restore scripts and a version/source manifest.
The vault is intentionally not part of this public repository. Secrets, memories, transcripts, runtime databases, machine-specific settings, and raw agent-home snapshots must never be promoted here. See Project Architecture for the boundary and recovery model.
4. Agent Harness
Skills describe how to work; a harness controls how work is executed. The harness layer connects agent runtimes to typed tools, validation, permissions, observations, approval gates, retries, and recovery contracts.
The included agent-harness-design skill captures the design principles: make correct actions easy to express, unsafe actions hard to invoke accidentally, and failures easy to diagnose.
What Exists Today
| Layer | Status | Where it lives |
|---|
| Portable skill hub | Available | skills/ |
| Provider adapters | Available | adapters/ |
| Genericized global adapter templates | Available; installed by scripts/bootstrap.sh | adapters/shared/, adapters/claude/, adapters/codex/ |
| Harness design guidance | Available | agent-harness-design |
| Validation and safe synchronization | Available | scripts/, tests/, CI |
| Private overlay and configuration backup vault | Separate deployment | Deliberately outside this public repository |
Repository Layout
skills/
├── <category>/<skill-name>/SKILL.md # canonical entry point
├── <category>/<skill-name>/references/ # supporting guidance
├── <category>/<skill-name>/scripts/ # deterministic helpers
└── <category>/<skill-name>/templates/ # reusable templates
adapters/
├── shared/ # runtime-neutral global instruction base, lifecycle hooks, git hooks
├── claude/ # Claude Code connection notes and per-runtime templates
├── codex/ # Codex project instructions and per-runtime templates
└── hermes/ # Hermes configuration example
docs/ # architecture, decision records, catalog, and guides
scripts/ # install, validation, and safe-sync helpers
tests/ # dependency-free regression tests
skills/ is the only source of truth for portable skills; a skill body must never be duplicated into an adapter. adapters/ holds tool-specific configuration and genericized global templates. Your real personal, employer, and machine-specific configuration belongs in the separate private overlay, which is not a directory inside this repository. Claude Code discovers project skills from .claude/skills, while Codex uses .agents/skills—not .codex/skills.
Quick Start
Clone the repository:
git clone https://github.com/quokkify/skills.git
cd skills
Claude Code
./scripts/bootstrap.sh --provider claude --install-skills
This installs the shared hooks, Claude settings, and managed CLAUDE.md block with timestamped backups. Claude Code requires oh-my-claudecode and superpowers, and Codex requires superpowers (ADR-0003; on Claude Code superpowers owns the process and oh-my-claudecode the agents, ADR-0005); the installer warns when one is missing. Add --overlay /path/to/private-overlay to layer private files after the public base. The overlay is read in place and is never copied into this checkout.
This is the beginning of the README. Read the rest at the original. Read the full README ↗
