Defame1297/holocron
0
0
Fork 0
Code Issues 14 Pull Requests Actions Packages Projects Releases 3 Wiki Activity

feat: deploy skills pipeline with provider adapter pattern

Browse Source
This commit is contained in:
Defame1297
2026-05-15 08:46:25 +00:00
parent c0ede4b22e
commit 15a4387eb2
39 changed files with 175 additions and 104 deletions
Download Patch File Download Diff File Expand all files Collapse all files

4
docs/adr/0004-skills-in-agents-dir.md
View File

@@ -1,3 +1,5 @@
# Skills live in .agents/skills/, not .claude/skills/
Skills (slash commands) are stored in `.agents/skills/` following the [Agent Skills open standard](https://agentskills.io), not in `.claude/skills/` which is a Claude Code-specific location. Claude Code, GitHub Copilot, Cursor, and other tools read `.agents/skills/` natively without an adapter. Putting skills in `.claude/skills/` would make them Claude Code-only and contradict ADR-0003 (provider-agnostic where possible). Skills are the strongest shared primitive across providers — they should live at the most portable location available.
Skills (slash commands) are stored in `.agents/skills/` following the [Agent Skills open standard](https://agentskills.io), not in `.claude/skills/` which is a Claude Code-specific location. Putting skills in `.claude/skills/` would make them Claude Code-only and contradict ADR-0003 (provider-agnostic where possible). Skills are the strongest shared primitive across providers — they should live at the most portable location available.
`install.sh` deploys skills to `~/.agents/skills/` as the single canonical location. Providers that do not read `~/.agents/skills/` natively declare a symlink adapter in `providers/<name>/provider-manifest.sh`; `install.sh` discovers and creates these automatically. Claude Code is one such provider — it reads `~/.claude/skills/` natively, so it gets a `~/.claude/skills/ → ~/.agents/skills/` symlink. See ADR-0007 for the rationale behind using symlinks for provider adapters.

2
docs/adr/0006-install-always-overwrites.md
View File

@@ -1,3 +1,5 @@
# install.sh always overwrites deployed files
`install.sh` overwrites `~/.claude/` and `~/.claude/core/` unconditionally on every run. It does not merge, diff, or ask. The rationale: the source of truth is this repo. Editing deployed files directly is a usage error — `sync.sh` would overwrite those edits on the next pull anyway. Offering a merge path would imply that editing `~/.claude/CLAUDE.md` directly is a supported workflow, which it is not. If a local customisation is needed it belongs in a project-level override file, not in the deployed global config.
**Exception — skills**: `~/.agents/skills/` uses a merge-per-skill strategy. Each skill directory from `.agents/skills/` is replaced individually; the parent directory is never wiped. This preserves user-installed skills from other sources alongside the skills managed by this repo. The overwrite-always principle still holds for each individual managed skill — the per-skill replace is unconditional.

9
docs/adr/0007-provider-adapters-as-symlinks.md Normal file
View File

@@ -0,0 +1,9 @@
# Provider skill adapters are symlinks, not copies
Provider skill adapters — the mechanism that makes `~/.agents/skills/` visible to a provider that reads a different path — are implemented as symlinks, not file copies. This is a deliberate exception to ADR-0002 (copy-not-symlink), which applies to content files. Adapters are infrastructure, not content.
**Why symlinks here:** a provider adapter has no content of its own — it is purely a pointer to the canonical location. Copying would create a second source of truth and require install.sh to keep two directories in sync; any drift between them would be a silent bug. A symlink makes the relationship explicit and eliminates the sync problem entirely.
**Why ADR-0002 still holds for content:** ADR-0002's concern is that symlinks break if this repo moves. Provider adapters point to `~/.agents/skills/`, not into this repo — they survive repo relocation without modification.
Each provider that cannot read `~/.agents/skills/` natively declares its adapter path in `providers/<name>/provider-manifest.sh`. `install.sh` discovers all provider manifests and creates the symlinks. A provider that reads `~/.agents/skills/` natively needs no entry. If the adapter target already exists as a real directory, install.sh emits a warning and leaves it intact rather than destroying user data.