Make the work you have invested in skills and agents portable across AI clients, machines, and repos.
This is for people who are tired of rebuilding the same AI workflows in Copilot, Claude Code, OpenCode, and project-local folders. Keep your real skill sources in repos you own, sync them into one shared toolkit, and point each client at the same reusable capabilities.
# 0. Install the required YAML parser.
brew install yq
# 1. Clone and initialize the toolkit without fetching external skills yet.
git clone git@github.com:bobthearsonist/ai.git ~/AI
cd ~/AI
./setup.sh --skip-sync
# 2. Register your existing skills repo in local.yaml.
# Edit collections.personal.path and the skills list.
${EDITOR:-vi} local.yaml
# 3. Sync local collections and git-managed skills into ~/AI/skills.
./scripts/sync.sh
# 4. Wire common clients to the shared skill output.
mkdir -p ~/.claude ~/.copilot
[ -e ~/.claude/CLAUDE.md ] || ln -s ~/AI/AGENTS.md ~/.claude/CLAUDE.md
[ -e ~/.claude/skills ] || ln -s ~/AI/skills ~/.claude/skills
[ -e ~/.claude/agents ] || ln -s ~/AI/agents ~/.claude/agents
[ -e ~/.copilot/skills ] || ln -s ~/AI/skills ~/.copilot/skills
# 5. Verify dependencies, collections, symlinks, and client wiring.
./scripts/doctor.shsetup.sh --skip-sync gives you a chance to edit local.yaml before fetching external skills. Run ./setup.sh without that flag if you want setup to sync immediately.
- Install the toolkit on a machine: Getting started
- Bring existing local skills under this workflow: Migration guide
- Configure
local.yamlcollections: Collections reference - Point AI clients at synced skills: Client support
- Add or improve a shared skill: Contributing
- Understand the repo layout: Skills and agents architecture
This repo is a portability layer, not a dumping ground. It keeps the shared contract in one place and lets the actual skill sources live where they make sense.
Source of truth: AGENTS.md for shared instructions, external-skills.yaml for repo-managed skills, local.yaml.example for the collection template, rules/ for tiny constraints, prompts/ for reusable prompt text, permissions/permissions.yaml for client permissions, and setup.sh plus scripts/ for automation.
Local machine config: local.yaml is gitignored and points at your personal, work, or team skill repos. This is where paths differ by machine.
Generated/synced output: skills/, agents/, and other collection links are produced by scripts/sync.sh. Do not make personal skills there directly; edit the source repo and sync again.
- Keep your real skill source in a repo you own, such as
~/Repositories/my-ai-skills/skills/<name>/SKILL.md. - Register that repo in
local.yamlundercollections. - Run
./scripts/sync.sh. - Configure your AI clients to read
~/AI/skillsand~/AI/agents. - Share broadly useful improvements by PR rather than editing synced output.
See the migration guide for the full path from existing local skills to shared project or team skills.
This repo separates source-of-truth content from generated/synced output:
- Internal skills live in this repo and are listed in
external-skills.yamlwithtype: internal. - Git-fetched skills are listed in
external-skills.yamlwithtype: git;sync.shcopies them intoskills/. - Personal or work skills live in your own repos and are listed in
local.yaml;sync.shsymlinks them intoskills/. - Project-shared skills should live in the project repo that needs them, usually under
.github/skills/or.claude/skills/, when they are only useful to that project.
Start with CONTRIBUTING.md. In short: update source files, not synced output; keep skills focused and triggerable; include verification steps; and run ./scripts/doctor.sh before opening a PR.