skillcaddy 0.27.0

package/CONTEXT.md

@@ -0,0 +1,149 @@
+# Skillcaddy
+
+Skillcaddy manages locally acquired skill sources and selectively enables their skills for individual projects or for the user's shared Agent environment.
+
+## Language
+
+**Skill source**:
+An external acquisition unit that contains one or more skills and retains enough origin information to be managed after download.
+_Avoid_: Download, plugin
+
+**Source identity**:
+A stable name that distinguishes a skill source across downloads and upgrades independently of its physical installation path. It uses the source name by default and adds a source namespace when that name would otherwise conflict.
+_Avoid_: Folder name, download URL
+
+**Source collision**:
+A destination-name conflict where Skillcaddy cannot establish that the incoming content and installed content share the same source identity. A collision is not an upgrade and never authorizes replacement.
+_Avoid_: Duplicate version, update
+
+**Source namespace**:
+A disambiguating provenance label used when two skill sources have the same name. Git sources use their repository owner; archive sources use the download URL's registrable domain unless explicitly overridden.
+_Avoid_: Author, hostname
+
+**Source bucket**:
+A top-level provenance classification for an acquired source. Hosted Git repositories belong to `github`, upstream archives and remote files to `official`, user-supplied local content to `personal`, and retired content to `archived`; callers do not select the bucket independently of provenance.
+_Avoid_: File type, install status
+
+**Source registry**:
+Skillcaddy-owned sidecar records that preserve source identity, sanitized provenance, integrity information, and discovered skill paths without modifying acquired source content.
+_Avoid_: Source manifest, package metadata
+
+**Source integrity baseline**:
+The registered SHA-256 of the accepted installed content of a non-Git skill source. It detects unadopted local drift but does not change the source's identity or provenance.
+_Avoid_: Current version, upstream checksum
+
+**Source registry repair**:
+An explicit adoption of a registered skill source's current validated state into its sidecar record without modifying the source content or its enablement links. Git repair adopts an externally advanced commit; non-Git repair adopts the current integrity baseline and discovered skill paths.
+_Avoid_: Source update, migration, content repair
+
+**Git source**:
+A skill source acquired as a complete Git repository from a hosted Git URL. A URL pointing into a repository may identify a source focus, but does not change the repository-sized acquisition unit.
+_Avoid_: GitHub skill, cloned skill
+
+**Source focus**:
+An optional path supplied with a hosted repository link that identifies the skills relevant to the current request without narrowing the acquired source.
+_Avoid_: Sparse checkout, partial source
+
+**Source credentials**:
+Access credentials managed by the user's existing Git or download environment rather than stored by Skillcaddy. Persisted source provenance never contains secrets or sensitive URL parameters.
+_Avoid_: Skillcaddy token, embedded password
+
+**Stable source URL**:
+A direct HTTP(S) origin that remains fetchable when stored without credentials, query parameters, or fragments, allowing the source registry to reuse it for later updates.
+_Avoid_: Signed URL, temporary download link
+
+**Archive source**:
+A versioned archive acquired from a direct download URL and unpacked into the central library. It may contain one skill or a collection of related skills, and only its latest installed version is retained.
+_Avoid_: ZIP skill, skill folder
+
+**Remote file source**:
+A skill source acquired from a direct HTTP(S) URL whose acquisition unit is one `SKILL.md`. Its origin and installed-content integrity remain registered so later downloads update the same source identity.
+_Avoid_: Repository path source, unmanaged download
+
+**Local source**:
+A skill source imported from a local archive or directory and copied into the central library so it does not depend on the original filesystem location.
+_Avoid_: Linked folder, working copy
+
+**Source acquisition**:
+The download, validation, and installation of a skill source into the central library without executing source-provided code or configuring a project.
+_Avoid_: Setup, enablement
+
+**Source validation**:
+Safety and discoverability checks applied before acquisition changes the central library. Safety failures reject the source, while non-security skill-format issues are reported as quality warnings.
+_Avoid_: Runtime preflight, setup check
+
+**Recognized skill layout**:
+A source-relative Skill location at the source root, within four directory levels under `skills/` or `skill/`, in a direct child `<name>/`, or within four directory levels under an immediate child collection's `<collection>/skills/`. Directory segments named `docs`, `references`, or `tests` are support content and are excluded. A populated root `skills/` layout is authoritative; otherwise, populated immediate child collections are authoritative, and unrelated deeper `SKILL.md` files outside the recognized collection roots are not discovered.
+_Avoid_: Recursive skill search, any SKILL.md
+
+**Source upgrade**:
+Replacement of an installed skill source with another valid package for the same source identity. Archive upgrades do not require Skillcaddy to infer or compare versions, and the replaced package is not retained as an active or historical copy.
+_Avoid_: Side-by-side install, version copy
+
+**Breaking source replacement**:
+A source upgrade that removes or relocates a previously discovered skill path and may therefore break a project or global link. It is distinct from version comparison and requires explicit authorization when an affected link is known.
+_Avoid_: New version, content update
+
+**Setup readiness**:
+The known state of prerequisites required before an enabled skill can work in a specific scope. Acquisition alone never establishes setup readiness, and readiness never controls whether the skill can be enabled.
+_Avoid_: Installed, downloaded
+
+**Unknown setup readiness**:
+The absence of a declared setup contract for a skill source. It does not imply that setup is required and does not prevent normal skill enablement.
+_Avoid_: Missing setup, incomplete setup
+
+**Setup reminder**:
+Non-blocking guidance shown for a skill whose source declares unmet setup prerequisites. Its type controls whether and how prominently Skillcaddy reminds the user, never whether the skill may be enabled.
+_Avoid_: Setup gate, enablement requirement
+
+**Runtime preflight**:
+A source-provided check performed when a skill is used to detect missing credentials, dependencies, or other runtime prerequisites and guide the user through them. It is outside source acquisition and enablement.
+_Avoid_: Source validation, Skillcaddy setup reminder
+
+**Enablement**:
+The creation of a scope-specific link to a skill already present in the central library. Source acquisition never implies enablement; both occur in one workflow only when the user expresses both intents.
+_Avoid_: Download, installation
+
+**Enablement scope**:
+The boundary that owns an enabled skill: one project, the user's shared Agent environment, or the user's Hermes environment.
+_Avoid_: Target path, install mode
+
+**Project enablement**:
+Enablement owned by one project and available through that project's Agent skill configuration. It can take precedence over a same-named global skill without changing the global enablement; Claude Code synchronization remains a separate project action.
+_Avoid_: Local installation, repository skill
+
+**Global enablement**:
+Enablement owned by the user and available to projects through the shared Agent environment. It is explicit, independent of any one project, and does not establish project setup readiness.
+_Avoid_: System installation, global package
+
+**Hermes enablement**:
+Enablement owned by the user and available through Hermes's fixed user skill directory. It is explicit and independent of project enablement, global Agent enablement, and project Claude Code synchronization.
+_Avoid_: Hermes mirror, global mirror
+
+**Hermes-eligible source**:
+An acquired `official`, `github`, or `personal` source that may be explicitly enabled into Hermes. Bundled repository skills and `archived` sources are outside Hermes enablement.
+_Avoid_: Third-party mirror, every source
+
+**Collection enablement**:
+A scoped operation that applies enablement to every eligible skill in one collection and classifies each candidate as enabled, unchanged, skipped, or failed. Project setup readiness remains project-scoped, and Collection enablement never establishes it; Hermes enablement still applies its source-eligibility boundary.
+_Avoid_: Bulk installation, collection setup
+
+**Skill**:
+An Agent-facing capability rooted at a directory containing `SKILL.md`, discovered within a skill source and enabled independently by enablement scope.
+_Avoid_: Library, repository
+
+**Library image**:
+A self-contained, relocatable snapshot of the central library that carries the library state needed to reconstruct an equivalent library on another machine: every source's installed bytes (including nested `.git`), the registry records, and the user-level enablement triples. It is the input to library image import and the output of library image export.
+_Avoid_: Archive, bundle, backup, snapshot, image
+
+**Upstream-less source**:
+A registered skill source whose provenance cannot be re-fetched: its bytes exist only on the machine that produced the library image, and any future update must keep the source's current type, origin, and bytes rather than adopt a new upstream. The library image preserves them as-is; it does not upgrade them.
+_Avoid_: Orphan source, broken source, untracked source
+
+**Code root**:
+The directory that holds the running Skillcaddy code together with the artifacts that ship with that code: `package.json`, `server.js`, the bundled `skills/` bucket, and the collection setup contracts. It is whatever directory the executable was launched from — a clone, an npm package directory, or a package manager's install prefix. The code root is never a place to keep acquired content.
+_Avoid_: Install directory, root directory, working directory
+
+**Library root**:
+The directory that holds the central library: the source buckets, the source registry, and the skill metadata sidecars. It is independent of the code root, so the same library is reachable from a clone, from an `npx` one-shot run, and from a package manager install. A git checkout keeps the library root at the checkout itself for backward compatibility; every other distribution form uses the user-level library directory unless the library root is set explicitly.
+_Avoid_: Root directory, data directory, working directory

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 chenweil
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.