skillcrumbs

name: skillcrumbs description: > Bootstrap and create tiny private/local agent skills stored outside the project repo. Use only when the user clearly wants a private, personal, local-only, not-for-team, uncommitted, or "skillcrumb" skill, especially with phrases like "add skillcrumb", "add a private skill here", "make a local skill just for me", "capture this as my private skill", or "repo-bound private skill". Skip when the user asks for a normal skill, global Codex skill, project/team-shared skill, committed repo skill, public skill, marketplace package, plugin, or any skill meant to be shared with the team.

Tiny private skills, stored outside the repo, tied to the repo you are working in.

Bootstrap

Run once:

bash scripts/bootstrap.sh

This installs:

agent-skills: discovers matching skill buckets and symlinks them into <repo-root>/.claude/skills/
skillcrumb: creates a new repo-bound skill skeleton

agent-skills adds .claude/skills/ to the current repo's local .git/info/exclude; it does not modify global gitignore.

Create Repo-Bound Skill

From any directory inside a git repo:

skillcrumb new <skill-name> "Use when ... Skip when ..."

Example:

skillcrumb new run-local "Use when the user asks to start this repo locally, run the dev server, or debug boot failures. Skip when working outside this repo."

For multiple repos that should share one skill, use a comma-separated bucket of repo names:

skillcrumb new --bucket "web,api" run-local "Use when starting web or api locally. Skip elsewhere."

For a specific repo path:

skillcrumb new --root /path/to/repo run-local "Use when starting this repo locally. Skip elsewhere."

What happens:

Finds git root, or uses current directory if not in git.
Uses repo root folder name plus a short path hash as bucket, unless --bucket is given.
Creates ~/.agents/<bucket>/skills/<skill-name>/SKILL.md.
Detects active git worktrees for that repo.
Runs agent-skills so the symlink appears in the main repo and every active worktree under .claude/skills/.
Writes ~/.agents/<bucket>/.skillcrumb-scope so current-repo skills match exact worktree paths and, when present, normalized origin remote.
Outside matching repos/worktrees, the skill does not symlink in and does not pollute the agent session.
If a repo is deleted and cloned again with the same origin, agent-skills revives the crumb by adding the new path to scope.

Edit the new SKILL.md body immediately. Keep it dirty-tiny: trigger phrases, exact commands, local quirks, and verification steps.

Interactive Skill Capture

When the user says something like "let's add skillcrumb", "add a private skill here", "make a local skill just for me", or "capture this as my private skill", ask only for missing details.

If the user says only "create a skill", "make a repo skill", "project skill", "global skill", or anything that could mean a normal/team-shared skill, do not proceed with Skillcrumbs yet. Ask:

Private crumb or shared skill?

Before creating any skillcrumb, confirm the write target:

Create private crumb under ~/.agents. Proceed?

Ask:

Scope: current repo, one named repo, several repo names, or global default.
Skill name: short kebab-case purpose name.
Trigger: literal user phrases that should activate it.
Body: exact commands, repo quirks, checks, and files to inspect.

If current repo scope is obvious, do not ask about scope; state the inferred repo root and continue. If several repos are named, create one comma-bucket skill:

skillcrumb new --bucket "repo-a,repo-b" <skill-name> "Use when ... Skip when ..."

If global scope is requested, use:

skillcrumb new --bucket default <skill-name> "Use when ... Skip when ..."

After creation:

Edit the new SKILL.md with the user's concrete workflow.
Keep it under one screen when possible.
Run agent-skills --load <skill-name> to verify body loading.
Tell the user where the skill lives and what phrase triggers it.
Do not copy the skill body into repo files unless explicitly asked.

If agent-skills says the main worktree has crumbs missing in the current worktree, ask before copying:

Copy main worktree crumbs here?

Then run:

agent-skills --copy-from-main

If the repo has multiple worktrees, be friendly and suggest the local hook:

I see you are using worktrees. Install local crumb sync hook?

If user agrees:

skillcrumb install-hook

Current Session Load

If a skill was just created, current agent session may not auto-see it yet. Load it manually:

agent-skills --load <skill-name>

Next session, it auto-triggers from .claude/skills/.

Rules

Do not put secrets in skills unless file permissions are locked down and sharing is controlled.
Keep repo skills private by default.
Created skills are stored under ~/.agents, not committed to the project repo.
.claude/skills/ is ignored per repo via .git/info/exclude, not global gitignore.
Created skill files and scope files are 0600; skill dirs are tightened to 0700.
Repo-bound skills activate only in matching repos/worktrees, not in unrelated sessions.
Re-cloned repos revive private crumbs when origin remote matches.
When creating in a git worktree setup, install symlinks in the main worktree and all active worktrees.
skillcrumb install-hook adds a local post-checkout hook in the repo common git dir so new worktrees can copy crumbs from main.
Keep skills small: one task, one workflow, concrete trigger phrases.
Prefer commands that can be pasted and verified.
Never commit .claude/skills/; it is symlink cache only.