Skip to content

Setup & Operations Guide

How to run the shared-skills system: the one-time GitHub setup, onboarding a new project, editing/releasing a skill, and troubleshooting. For the what and why, see the README.

1. Required GitHub secrets (one-time, per maintainer/admin)

Already configured — only needed for new repos/apps

These secrets are already set up for the current repos. You only need this section when onboarding a new consumer repo (add SKILLS_READ_TOKEN) or registering a new app for auto-bump. The existing token values are stored in NordPass under GitHub — reuse them rather than minting new ones.

claude-skills is a private repo, so both CI and the auto-bump bot need tokens to reach it. There are two:

Secret Lives on Used by Scope needed
SKILLS_READ_TOKEN each consumer repo skills-check CI — clones canonical to verify no drift Contents: read on Twycis/claude-skills
SKILLS_BUMP_TOKEN the claude-skills repo auto-bump workflow — opens "bump skills" PRs in each consumer Contents: read+write + Pull requests: read+write on all consumer repos

Create a token

GitHub → your avatar (top-right) → Settings → Developer settings (bottom of the left sidebar) → Personal access tokens. Direct link: https://github.com/settings/tokens

Fine-grained (recommended): Tokens (fine-grained) → Generate new token - Resource owner: Twycis (the org — not your personal account) - Repository access: Only select repositories → - SKILLS_READ_TOKEN → Twycis/claude-skills - SKILLS_BUMP_TOKEN → ReverseDiamond, DoubleDiamond, SalesFocus, Eos - Repository permissions: - SKILLS_READ_TOKEN → Contents: Read-only - SKILLS_BUMP_TOKEN → Contents: Read and write + Pull requests: Read and write

If the Twycis org has "Require approval for fine-grained tokens" enabled, an org owner must approve the token before it works (Org → Settings → Personal access tokens).

Classic (simpler, broader): Tokens (classic) → Generate new token → check the repo scope. One classic token covers both uses but grants access to all your repos.

Copy the value immediately — GitHub shows it only once.

Add it as a repo secret

Go to the repository → Settings → Secrets and variables → Actions → New repository secret. Direct link pattern: https://github.com/Twycis/<repo>/settings/secrets/actions

  • On Twycis/claude-skills → add SKILLS_BUMP_TOKEN
  • On each consumer repo → add SKILLS_READ_TOKEN

Without SKILLS_READ_TOKEN, the consumer's skills-check can't clone canonical and skillsync --check exits 3 (skip) — the gate is effectively off until the secret exists.

2. Onboard a new project

In plain terms

"Onboarding a project" means connecting one of our apps to this shared skill library so it automatically gets the same set of skills as everything else — and keeps them up to date by itself. Think of it like subscribing the project to a channel: once it's subscribed, new and improved skills arrive automatically, and a safety check makes sure nobody quietly changes a skill in just one project.

You do this once per project. It's a developer task run in the project's terminal (or you can ask Claude to do it). Here's what the steps below actually achieve:

  1. Install the helper tool that downloads and updates the skills (skillsync).
  2. Write a small settings file that says which skills this project wants — its tech stack (fastapi or express), whether it wants everything or a chosen few, and any skills unique to this project.
  3. Download the skills so they're available in the project.
  4. Turn on the automatic safety check so the project stays in sync and warns if a skill drifts out of line.
  5. (Optional) Add a local check that runs before each save/commit.

After that, two small admin steps wire it into the team system: add the project to the shared list so updates get offered to it, and add its read token (from Section 1).

Once you understand the above, the exact commands follow. From the project root:

# a) vendor the CLI
mkdir -p .agent && curl -fsSL \
  https://raw.githubusercontent.com/Twycis/claude-skills/main/cli/skillsync \
  -o .agent/skillsync && chmod +x .agent/skillsync
#   (or: cp ../claude-skills/cli/skillsync .agent/skillsync)

# b) write the manifest — pick the variant for this stack, list project-only skills
cat > .claude/skills.manifest.json <<'JSON'
{
  "source": "https://github.com/Twycis/claude-skills.git",
  "version": "1.0.0",
  "core": "all",
  "variant": "fastapi",
  "local": ["my-project-only-skill"]
}
JSON

# c) materialize skills + symlinks
./.agent/skillsync

# d) install the CI gate
mkdir -p .github/workflows
curl -fsSL https://raw.githubusercontent.com/Twycis/claude-skills/main/templates/skills-check.yml \
  -o .github/workflows/skills-check.yml

# e) (optional) local pre-commit hook
curl -fsSL https://raw.githubusercontent.com/Twycis/claude-skills/main/templates/pre-commit \
  -o .git/hooks/pre-commit && chmod +x .git/hooks/pre-commit

Then add the project to consumers.json (so auto-bump targets it) and add the SKILLS_READ_TOKEN secret (step 1).

Manifest fields: - variant — fastapi or express. Picks the per-stack flavor of each variant skill. - core — "all" or an explicit list like ["pdf","release-notes"]. - packs — opt-in named groups to install, e.g. ["firstdiamond"] (see packs/ in canonical). - local — skills that live ONLY in this project. skillsync never creates, overwrites, or deletes these. Not allowed alongside strict for non-central skills. - strict — true locks the project to centrally-available skills: any skill dir not provided by core/variant/packs and not in local is flagged by --check and pruned by materialize. Use this to guarantee a project never accumulates ad-hoc local skills.

3. Edit or add a skill (the only correct way to change skills)

In plain terms

Skills live in one central place (this claude-skills library), and every project gets a copy. So when you want to improve a skill or add a new one, you change it here, once — not inside an individual project. After you make the change, you "release" it (give it a new version number), and the system automatically offers that update to every project as a ready-to-approve change.

Why not just edit it inside the project you're working on? Because each project's copy is meant to stay identical to the central one. An automatic check will spot a one-off edit and flag it, so that work would be undone. Editing centrally is the only change that sticks.

The three things you decide when adding a skill: is it the same everywhere (most skills), does it differ by tech stack (fastapi vs express), or is it only for one project? The decision tree below covers each case.

Never hand-edit a vendored skill inside a consuming project — CI will revert your work by flagging drift. Instead:

git clone https://github.com/Twycis/claude-skills.git && cd claude-skills

# edit core/<name>/SKILL.md           (same for every stack)
#   or variants/<name>/<flavor>/...   (per-stack; add fastapi/ and/or express/)
#   new project-only skill?           leave it in the project, add to that manifest's `local`

# bump the version and release
echo "1.1.0" > VERSION
git commit -am "feat(pr-ready): add X" && git tag 1.1.0
git push origin main --tags

Pushing the tag fires auto-bump, which opens a "bump skills to 1.1.0" PR in each consumer repo. Review the skill diffs, merge, done — skills-check confirms the vendored files match canonical@1.1.0.

Adding a skill, decision tree: - Same content for every stack → core/<name>/SKILL.md - Differs by stack → variants/<name>/fastapi/SKILL.md and/or .../express/SKILL.md - Shared by some projects, opt-in (e.g. a domain skill) → packs/<pack>/<name>/SKILL.md; add the pack to those projects' manifest packs - One project only → keep it local and list it in local (only when the project isn't strict)

4. Adopt updates manually (without waiting for the bot)

In plain terms

Normally, when a skill is updated centrally, each project is offered the update automatically (as a pull request you just review and approve). This section is only for when you don't want to wait — you'd like to pull the newest skills into a project right now. The commands below check whether the project is behind and, if so, update it.

./.agent/skillsync --latest          # am I behind?
# bump "version" in .claude/skills.manifest.json to the new tag, then:
./.agent/skillsync                   # re-materialize
git add .claude .agent && git commit -m "chore: bump skills to 1.1.0"

5. Troubleshooting

In plain terms

A few common hiccups and how to fix them. The left column is what you'd see go wrong; the right column is the cause and the fix. Most issues come down to one of two things: a project is behind (just run the update), or a skill was edited in the wrong place (fix it centrally instead). When in doubt, running ./.agent/skillsync in the project resolves the majority of cases.

Symptom Cause / fix
skillsync --check exits 3, "canonical unreachable" Can't clone canonical. Locally: check network / git clone https://github.com/Twycis/claude-skills.git. In CI: add the SKILLS_READ_TOKEN secret. Offline pre-commit intentionally skips on exit 3.
skills-check CI is red with DRIFT: lines A vendored skill was hand-edited, or the project is behind. Run ./.agent/skillsync and commit, or bump version.
A variant skill is "skipped — no <flavor> flavor" That skill has no folder for your variant (e.g. openapi-sync is fastapi-only). Expected; it just isn't installed.
skillsync pruned a skill I wanted to keep It wasn't in local and isn't provided by canonical. Add it to the manifest local list.
Need to test against a local checkout before a release SKILLSYNC_SOURCE=/path/to/claude-skills ./.agent/skillsync overrides the manifest source.

Reference