skillcaddy-manager
Manage Skillcaddy source acquisition, source updates, migrations, project skill links, and the Web/TUI CLI. Use for discovery, add/update requests, enable/disable, audits, maintenance, bootstrap, or Web/TUI access.
Install
npx skills add https://github.com/chenweil/skillcaddy/tree/main/skills/skillcaddy-manager
claude plugin marketplace add https://llmmart.ai/marketplace.json && claude plugin install chenweil-skillcaddy@llmmart
git clone https://github.com/chenweil/skillcaddy.git
The skills CLI installs just this skill, for any of its supported agents. Claude Code installs the whole chenweil/skillcaddy collection as a plugin from our marketplace. Git is the plain clone.
Skill manifest
Skillcaddy Manager
Treat Skillcaddy as a central skill library with explicit project/global/Hermes symlink activation. Keep one execution loop across every branch: state -> route -> preflight -> act -> verify.
Core Loop
- Resolve the Skillcaddy repository and target project. Default the project to the current working directory only when the user did not provide one.
- Complete when both absolute paths are known.
- For recommendations, audits, or mutations, read
GET /api/state?projectPath=<encoded-path>. For source acquisition, updates, or migration, also inspect the source registry withnpm run source -- listandnpm run source -- inspect <source-id>. If the server is unavailable, inspect the equivalent paths listed under Core Model.- Complete when repository, source registry, project, global, Hermes, Claude, metadata, and
advicestate relevant to the request are known.
- Complete when repository, source registry, project, global, Hermes, Claude, metadata, and
- Route to the required branch and load only its reference; load multiple references only when the request combines branches:
- Discovery, source acquisition/update/migration, enable/disable, audit, health, Git update, bootstrap, Web/TUI: OPERATIONS.md
- Recommendations: RECOMMENDATION_GUIDE.md
- Notes, tags,
autoEnable, migration, batch Chinese notes: METADATA.md - Complete when the selected branch, target identities, and completion criterion are explicit.
- For a mutation, apply the Mutation Gate before acting. Prefer the existing API, TUI, or repository commands over ad hoc filesystem changes.
- Complete when the preflight accounts for every affected item and all blocking ownership or alias issues are resolved.
- Execute the narrowest requested operation, rescan state, and report the observed result.
- Complete when the post-operation state proves every requested item succeeded, remained unchanged, was skipped, or failed with a stated reason.
Core Model
| Scope | Location | Role |
|---|---|---|
| Bundled | skills/<name>/ |
Skills shipped by this repository |
| Central | official/, github/, personal/, archived/ |
Source libraries |
| Source registry | .skillcaddy/sources/ |
Sidecar identity, provenance, integrity, install path, and discovered skill paths |
| Project | <project>/.agents/skills/ |
Codex-compatible activation symlinks |
| Project Claude | <project>/.claude/skills/ |
Claude compatibility symlinks |
| Global Agents | ~/.agents/skills/ |
Shared user-level links managed by Skillcaddy |
| Global Claude | ~/.claude/skills/ |
Read-only external Agent directory; Skillcaddy does not write it |
| Hermes | ~/.hermes/skills/ |
Explicit independent scope for eligible official/github/personal sources |
| Collection setup | collection-metadata/<source>/<collection>.json |
Tracked, read-only setup contract and readiness checks |
Preserve these invariants:
- Enable and disable operations are explicit about
projectorglobalscope; source skill directories remain intact. - Project enablement writes
<project>/.agents/skills/and best-effort syncs project Claude links. Global enablement writes only~/.agents/skills/and does not require a project. - Project and global aliases may coexist; project state is the higher-priority context when an Agent applies its normal precedence rules.
- Never take over an occupied ordinary entry, foreign symlink, or broken link. Same-target enablement is an unchanged result.
- Global disable may remove only a symlink whose target is provably inside the current Skillcaddy root's allowed source folders; foreign links and ordinary entries are read-only.
- Source acquisition changes only the central library. It never implies enablement, setup, or execution of acquired code.
addis for a new source identity. Only a matching source-registry record authorizesupdate; a destination collision never does.- An explicit combined request runs acquisition first, rescans state, resolves one requested acquired skill, and enables only that selection.
- Unknown setup readiness produces no reminder or gate. Declared setup reminders remain non-blocking; publisher runtime preflight owns proprietary credentials and setup.
archived/skills require an explicit user request.- GitHub-backed source directories remain free of Skillcaddy metadata; write catalog metadata to the sidecar store.
- Collection activation and project readiness are separate: setup may be missing after links are enabled.
- Interactive setup is never executed silently; obtain confirmation and let the declared setup skill own project edits.
- Repository behavior in
lib/skillStore.js,lib/projectActions.js, andlib/claudeStore.jsis authoritative when documentation and implementation differ. - The fixed default Web manager URL is
http://127.0.0.1:4173. - The clone-backed
skillcaddyentry keeps no-argument TUI compatibility and also supportsstart,stop,restart,-ufor registered Git source updates, and read-only-aanalysis. - Global bootstrap is explicit: run
npm run install:cliandnpm run check:clifrom the clone; the installed command provides both CLI and TUI, whileinstall:tuiremains a compatibility alias. - Source update and repair CLIs require an explicit
--project; global links are always scanned in addition to that project context. - If a registered Git checkout was manually advanced with
git pull, usenpm run source -- repair <source-id> --project <project-dir>to explicitly adopt the clean fast-forward state into the sidecar registry; never edit the registry directly.
Mutation Gate
Before changing state, present a compact preflight containing:
| Action | Skill | Source/collection | Alias | Target path | Advice/result |
|---|
Account for skills that will be changed, left unchanged, skipped, or rejected. Include relevant /api/state.advice and metadata writes.
Require confirmation before proceeding when:
- one request matches multiple skills and the user has not selected one;
- a project or global alias points to a different target;
- a project or global entry is not a symlink or is externally managed;
- a GitHub source has uncommitted changes before update;
- a breaking source replacement affects a known project or global link;
- a source identity is ambiguous or a destination collision is not backed by a matching registry record;
- the request reaches into
archived/without naming the archived target; - the request would delete a source skill rather than a project link;
- an advice item exposes a destructive or ownership ambiguity.
- an affected collection reports missing or partial interactive setup.
Surface informational duplicate-name and global-shadowing advice, but do not block solely on it. Use the full skill ID and a confirmed alias to resolve duplicates.
Reporting
For summaries, distinguish repository availability, project enablement, global presence, Claude compatibility, and unmanaged or broken state. Prefer:
| Action | Skill | Source | Alias | Result | Notes |
|---|
End with the verification performed: rescan/API state, validation command, tests, or server URL.
Files (skillcaddy)
-
agents
-
openai.yaml 305 B
Loading…
-
-
references
-
featured-skills.json 17.4 KB
Loading… -
METADATA.md 3.1 KB
Loading… -
OPERATIONS.md 17.1 KB
Loading… -
RECOMMENDATION_GUIDE.md 3.1 KB
Loading… -
skill-platforms.json 1.7 KB
Loading…
-
-
scripts
-
check-conflicts.cjs 3.6 KB · in bundle
-
check-global-skills.cjs 5.3 KB · in bundle
-
translate-skill-notes.cjs 9.8 KB · in bundle
-
version-manager.cjs 3.7 KB · in bundle
-
view-recommendations.cjs 7.9 KB · in bundle
-
-
SKILL.md 7.3 KB
--- name: skillcaddy-manager description: Manage Skillcaddy source acquisition, source updates, migrations, project skill links, and the Web/TUI CLI. Use for discovery, add/update requests, enable/disable, audits, maintenance, bootstrap, or Web/TUI access. --- # Skillcaddy Manager Treat Skillcaddy as a central skill library with explicit project/global/Hermes symlink activation. Keep one execution loop across every branch: **state -> route -> preflight -> act -> verify**. ## Core Loop 1. Resolve the Skillcaddy repository and target project. Default the project to the current working directory only when the user did not provide one. - Complete when both absolute paths are known. 2. For recommendations, audits, or mutations, read `GET /api/state?projectPath=<encoded-path>`. For source acquisition, updates, or migration, also inspect the source registry with `npm run source -- list` and `npm run source -- inspect <source-id>`. If the server is unavailable, inspect the equivalent paths listed under **Core Model**. - Complete when repository, source registry, project, global, Hermes, Claude, metadata, and `advice` state relevant to the request are known. 3. Route to the required branch and load only its reference; load multiple references only when the request combines branches: - Discovery, source acquisition/update/migration, enable/disable, audit, health, Git update, bootstrap, Web/TUI: [OPERATIONS.md](references/OPERATIONS.md) - Recommendations: [RECOMMENDATION_GUIDE.md](references/RECOMMENDATION_GUIDE.md) - Notes, tags, `autoEnable`, migration, batch Chinese notes: [METADATA.md](references/METADATA.md) - Complete when the selected branch, target identities, and completion criterion are explicit. 4. For a mutation, apply the **Mutation Gate** before acting. Prefer the existing API, TUI, or repository commands over ad hoc filesystem changes. - Complete when the preflight accounts for every affected item and all blocking ownership or alias issues are resolved. 5. Execute the narrowest requested operation, rescan state, and report the observed result. - Complete when the post-operation state proves every requested item succeeded, remained unchanged, was skipped, or failed with a stated reason. ## Core Model | Scope | Location | Role | |---|---|---| | Bundled | `skills/<name>/` | Skills shipped by this repository | | Central | `official/`, `github/`, `personal/`, `archived/` | Source libraries | | Source registry | `.skillcaddy/sources/` | Sidecar identity, provenance, integrity, install path, and discovered skill paths | | Project | `<project>/.agents/skills/` | Codex-compatible activation symlinks | | Project Claude | `<project>/.claude/skills/` | Claude compatibility symlinks | | Global Agents | `~/.agents/skills/` | Shared user-level links managed by Skillcaddy | | Global Claude | `~/.claude/skills/` | Read-only external Agent directory; Skillcaddy does not write it | | Hermes | `~/.hermes/skills/` | Explicit independent scope for eligible `official`/`github`/`personal` sources | | Collection setup | `collection-metadata/<source>/<collection>.json` | Tracked, read-only setup contract and readiness checks | Preserve these invariants: - Enable and disable operations are explicit about `project` or `global` scope; source skill directories remain intact. - Project enablement writes `<project>/.agents/skills/` and best-effort syncs project Claude links. Global enablement writes only `~/.agents/skills/` and does not require a project. - Project and global aliases may coexist; project state is the higher-priority context when an Agent applies its normal precedence rules. - Never take over an occupied ordinary entry, foreign symlink, or broken link. Same-target enablement is an unchanged result. - Global disable may remove only a symlink whose target is provably inside the current Skillcaddy root's allowed source folders; foreign links and ordinary entries are read-only. - Source acquisition changes only the central library. It never implies enablement, setup, or execution of acquired code. - `add` is for a new source identity. Only a matching source-registry record authorizes `update`; a destination collision never does. - An explicit combined request runs acquisition first, rescans state, resolves one requested acquired skill, and enables only that selection. - Unknown setup readiness produces no reminder or gate. Declared setup reminders remain non-blocking; publisher runtime preflight owns proprietary credentials and setup. - `archived/` skills require an explicit user request. - GitHub-backed source directories remain free of Skillcaddy metadata; write catalog metadata to the sidecar store. - Collection activation and project readiness are separate: setup may be missing after links are enabled. - Interactive setup is never executed silently; obtain confirmation and let the declared setup skill own project edits. - Repository behavior in `lib/skillStore.js`, `lib/projectActions.js`, and `lib/claudeStore.js` is authoritative when documentation and implementation differ. - The fixed default Web manager URL is `http://127.0.0.1:4173`. - The clone-backed `skillcaddy` entry keeps no-argument TUI compatibility and also supports `start`, `stop`, `restart`, `-u` for registered Git source updates, and read-only `-a` analysis. - Global bootstrap is explicit: run `npm run install:cli` and `npm run check:cli` from the clone; the installed command provides both CLI and TUI, while `install:tui` remains a compatibility alias. - Source update and repair CLIs require an explicit `--project`; global links are always scanned in addition to that project context. - If a registered Git checkout was manually advanced with `git pull`, use `npm run source -- repair <source-id> --project <project-dir>` to explicitly adopt the clean fast-forward state into the sidecar registry; never edit the registry directly. ## Mutation Gate Before changing state, present a compact preflight containing: | Action | Skill | Source/collection | Alias | Target path | Advice/result | |---|---|---|---|---|---| Account for skills that will be changed, left unchanged, skipped, or rejected. Include relevant `/api/state.advice` and metadata writes. Require confirmation before proceeding when: - one request matches multiple skills and the user has not selected one; - a project or global alias points to a different target; - a project or global entry is not a symlink or is externally managed; - a GitHub source has uncommitted changes before update; - a breaking source replacement affects a known project or global link; - a source identity is ambiguous or a destination collision is not backed by a matching registry record; - the request reaches into `archived/` without naming the archived target; - the request would delete a source skill rather than a project link; - an advice item exposes a destructive or ownership ambiguity. - an affected collection reports missing or partial interactive setup. Surface informational duplicate-name and global-shadowing advice, but do not block solely on it. Use the full skill ID and a confirmed alias to resolve duplicates. ## Reporting For summaries, distinguish repository availability, project enablement, global presence, Claude compatibility, and unmanaged or broken state. Prefer: | Action | Skill | Source | Alias | Result | Notes | |---|---|---|---|---|---| End with the verification performed: rescan/API state, validation command, tests, or server URL. -
skillcaddy.json 215 B
Loading…
Comments (0)
Sign in to join the conversation.
Reviews (0)
No reviews yet.
No comments yet.