Skip to content

claude-skills — canonical Claude/Gemini skills

Single source of truth for the Claude Code (.claude/skills/) and Gemini/Antigravity (.agent/workflows/) skills shared across projects. Consuming projects vendor these skills, pinned to a version, via the skillsync CLI. Skills are never hand-edited in a consuming project — edit them here, cut a release, and let each project adopt it through a reviewed bump PR.

New here? See docs/SETUP.md for GitHub token/secret setup, onboarding a new project, releasing a skill change, and troubleshooting.

Layout

core/<name>/SKILL.md           Tier 1 — language-agnostic, identical in every project
variants/<name>/<flavor>/...   Tier 2 — same skill, per-stack flavor (fastapi | express)
packs/<pack>/<name>/SKILL.md   Tier 3 — opt-in named groups (e.g. firstdiamond), per-manifest
cli/skillsync                  the vendoring CLI (copied into each project's .agent/)
VERSION                        current version; releases are git tags (e.g. 1.1.0)
  • Core is copied verbatim into every consuming project.
  • Variants hold one folder per stack flavor. A project's manifest picks the flavor; the chosen folder is materialized to the plain skill name (feature-scaffold/). A skill with no folder for the project's flavor is simply skipped (e.g. openapi-sync only has a fastapi flavor).
  • Packs are opt-in named groups under packs/<pack>/. A project lists the packs it wants in its manifest packs array; each skill in those packs is materialized by name.
  • local skills live only inside a project and are declared in the manifest local list — skillsync never creates, overwrites, or prunes them.
  • With strict: true, a project is locked to centrally-available skills: any skill dir that isn't core/variant/pack-provided and isn't in local is flagged by --check and pruned by materialize.

Consuming this repo

Each project has .claude/skills.manifest.json:

{
  "source": "https://github.com/Twycis/claude-skills.git",
  "version": "1.1.0",
  "core": "all",
  "variant": "fastapi",
  "packs": ["firstdiamond"],
  "local": [],
  "strict": true
}

and a vendored copy of the CLI at .agent/skillsync. Then:

./.agent/skillsync          # materialize skills from canonical@<version>
./.agent/skillsync --check  # CI/pre-commit gate: fail if vendored skills drifted
./.agent/skillsync --latest # is the pinned version behind the latest tag?

SKILLSYNC_SOURCE=/path/to/local/checkout ./.agent/skillsync overrides source for local testing before this repo is published.

Releasing

  1. Edit/add skills under core/, variants/, or packs/.
  2. Bump VERSION and tag: git tag 1.2.0 && git push --tags.
  3. The auto-bump workflow opens a "bump skills" PR in each registered consuming repo. Merging it adopts the new skills.

Adding a skill

  • Same for everyone → core/<name>/SKILL.md.
  • Differs by stack → variants/<name>/fastapi/SKILL.md and/or .../express/SKILL.md.
  • Shared by some projects, opt-in → packs/<pack>/<name>/SKILL.md (e.g. a domain pack like firstdiamond); projects add the pack name to their manifest packs.
  • One project only → leave it in that project and add the name to its manifest local list (only allowed when the project is not strict).