libra-workflow-and-versioning

A cross-agent Agent Skills repository. It packages reusable SKILL.md skills that work — unmodified — across Claude Code, OpenAI Codex CLI, Google Gemini CLI, and opencode, using the open Agent Skills standard.

Tracked with Libra, the AI-agent-native version control system.

Skills in this repo

Skill	What it does
libra-workflow-and-versioning	Version-control workflow discipline for Libra repositories — commits, branches, the shared-storage worktree model, cloud backup/publish, structured output, and stable error codes.

Why one repo serves every agent

SKILL.md is an open standard: a folder containing a SKILL.md file with name + description YAML frontmatter and a Markdown body. Every supported agent reads the same format; the only difference is which directory each one scans. This repo lays the files out so that opening it with any supported agent auto-discovers the skills, and a single install.sh makes them global.

Agent	Project (workspace) path it scans	Global (user) path	Reads .agents/skills/?
Claude Code	.claude/skills/	~/.claude/skills/	no → mirrored here
Codex CLI	.codex/skills/	~/.agents/skills/, ~/.codex/skills/	global yes → mirrored for project
Gemini CLI	.gemini/skills/ or .agents/skills/	~/.gemini/skills/ or ~/.agents/skills/	yes (native)
opencode	.opencode/skills/, .claude/skills/, .agents/skills/	~/.config/opencode/skills/, ~/.claude/skills/, ~/.agents/skills/	yes (native)

Single source of truth: edit the canonical files in .agents/skills/ — read directly by Gemini CLI and opencode. Claude Code (.claude/skills/) and Codex (.codex/skills/) hold mirrored copies of that store, regenerated by scripts/sync-skills.sh. Copies (rather than symlinks) are used because Libra does not track symlinks and because copies survive Windows clones and zip downloads. scripts/sync-skills.sh --check flags any drift, so the mirrors never silently diverge.

Layout

libra-workflow-and-versioning/
├── .agents/skills/<name>/SKILL.md   ← canonical source (Gemini + opencode read directly)
├── .claude/skills/<name>/SKILL.md   ← mirrored copy for Claude Code (+ opencode)
├── .codex/skills/<name>/SKILL.md    ← mirrored copy for Codex CLI
├── scripts/sync-skills.sh           ← mirror canonical → per-tool dirs (--check for CI)
├── install.sh                       ← install every skill globally for all agents
├── AGENTS.md                        ← conventions for editing this repo
└── README.md

Use it

Per-project (no install)

Clone the repo and open it with any supported agent — the skills are discovered automatically from the directories above.

libra clone <this-repo-url> libra-workflow-and-versioning
cd libra-workflow-and-versioning
# then run `claude`, `codex`, `gemini`, or `opencode` in this directory

To add the skills to another project, symlink (or copy) the skill folder into that project's .agents/skills/ (Gemini + opencode) and .claude/skills/ + .codex/skills/ (Claude + Codex).

Globally (available in every repo)

./install.sh

This symlinks every skill in .agents/skills/ into:

• ~/.agents/skills/<name> — picked up by Codex CLI, Gemini CLI, and opencode
• ~/.claude/skills/<name> — picked up by Claude Code

Re-run it after pulling updates. Remove a skill globally by deleting the symlinks of the same name from those two directories.

How each agent triggers a skill

• Claude Code — auto-invoked when your task matches the description, or type /libra-workflow-and-versioning.
• Codex CLI — run /skills, type $ to mention it, or let Codex pick it implicitly by description.
• Gemini CLI — auto-discovered; the skill's name + description are injected into the system prompt and loaded on demand.
• opencode — auto-discovered; the agent loads the body on demand via its native skill tool.

Add or edit a skill

1. Create or edit .agents/skills/<name>/SKILL.md. Keep the frontmatter portable — only name (lowercase, digits, single hyphens, ≤64 chars) and description (≤1024 chars) are needed; name must equal the directory name.
2. Run scripts/sync-skills.sh to mirror it into .claude/skills/ and .codex/skills/. (CI can run scripts/sync-skills.sh --check to fail the build if a mirror drifted.)
3. Commit with Libra: libra add ... then libra commit -s -m "feat(skill): ...". (See the libra-workflow-and-versioning skill for the workflow it documents — this repo follows its own advice.)

See AGENTS.md for the full contributor conventions.

License

MIT.