A portable operating layer for AI agents: shared skills, recoverable configuration, and safer execution harnesses.
Generated with quokkify/project-toolkit at v2.12.1. Run copier update to apply future template changes; Renovate updates workflow version 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
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.mdpackages; - references, templates, and deterministic helper scripts;
- review and promotion workflows for reusable lessons;
- validation, privacy checks, and release automation.
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.
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.
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.
| 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 |
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.
Clone the repository:
git clone https://github.com/quokkify/skills.git
cd skills./scripts/bootstrap.sh --provider claude --install-skillsThis installs the shared hooks, Claude settings, and managed CLAUDE.md block with timestamped backups. 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.
./scripts/bootstrap.sh --provider codex --install-skillsThe installer creates $CODEX_HOME/AGENTS.md as a symlink to the selected shared base — the overlay's copy if --overlay provides one, otherwise the public checkout's — merges config.toml and hooks.json, installs native agent definitions and shared hooks, and configures global Git hooks. Review and approve command hooks in the Codex TUI with /hooks.
To install both runtimes (the default):
./scripts/bootstrap.sh --install-skillsUse --dry-run to print every planned operation without changing files, symlinks, or Git configuration.
Point Hermes directly at the canonical skill directory:
skills:
external_dirs:
- /absolute/path/to/skills/skillsThe same example is available at adapters/hermes/config.example.yaml. Start a new Hermes session after changing the discovery path. A same-named profile-local skill can take precedence over the shared copy, so keep shared changes on an isolated Git branch or worktree.
The repository currently contains 19 portable skills spanning:
- orchestration and agent recovery;
- skill lifecycle and promotion;
- repository safety and quality gates;
- software development and browser QA;
- infrastructure operations;
- game troubleshooting and source reconnaissance.
Browse the complete Skill Catalog or open the documentation site.
From a clean checkout on main:
./scripts/sync-shared-skills.shThe helper fetches only origin/main, validates the exact fetched snapshot with the currently trusted validator, allows fast-forward updates only, disables Git hooks during branch movement, and rejects concurrent checkout changes. It never executes scripts from the fetched tree.
Copied Codex adapter files are not refreshed by this command. Rerun the installer when adapters/codex/AGENTS.md changes.
Run the portable CI-equivalent gate:
./scripts/validate.sh --ciRun the complete local gate, including full-history Gitleaks scanning:
./scripts/validate.sh --fullGitleaks 8.30.1 or newer must be available on PATH or through GITLEAKS_BIN for --full.
The repository records its quokkify/project-toolkit template source and answers in .copier-answers.yml. From a clean checkout, review and apply template updates with:
copier update --trustRepository-specific validation remains in scripts/validate.sh; the generated update contract and reusable CI workflow keep shared project plumbing versioned without replacing that custom gate.
Optional repository-local Git hooks:
./scripts/install-git-hooks.shThe validator checks skill layout and frontmatter, duplicate names, Markdown links, symlinks, machine-specific paths, and public/private boundaries.
This is a public repository. Do not commit credentials, memories, transcripts, sessions, runtime databases, private project context, machine-specific configuration, or backup archives. Read SECURITY.md before promoting locally generated material.
Every pull request runs repository validation and Gitleaks. Scanner success complements manual privacy review; it does not prove that content is appropriate to publish.