From 30bb559a9a27dc776211be7c103e1114d942f229 Mon Sep 17 00:00:00 2001 From: Alberto De Bortoli Date: Wed, 22 Jul 2026 14:47:10 +0100 Subject: [PATCH] docs(skills): document mandatory version pinning and version: latest Reflects Luca PR #99 (versioned skill cache paths, repo-level version inheritance) and PR #101 (version: latest / --ref latest support). --- docs/getting-started/quick-start.md | 1 + docs/skills/global-skills.md | 4 +- docs/skills/installing-skills.md | 29 ++++++++++++-- docs/skills/lucafile-skills.md | 60 +++++++++++++++++++++++++++-- 4 files changed, 87 insertions(+), 7 deletions(-) diff --git a/docs/getting-started/quick-start.md b/docs/getting-started/quick-start.md index a77005e..1c52bbd 100644 --- a/docs/getting-started/quick-start.md +++ b/docs/getting-started/quick-start.md @@ -32,6 +32,7 @@ tools: skills: - name: swift-testing-expert repository: AvdLee/Swift-Testing-Agent-Skill + version: 1.2.0 agents: - claude-code diff --git a/docs/skills/global-skills.md b/docs/skills/global-skills.md index 0a3c9ca..4635a76 100644 --- a/docs/skills/global-skills.md +++ b/docs/skills/global-skills.md @@ -18,7 +18,7 @@ luca install --global Install a specific skill globally from a repository: ```bash -luca install AvdLee/Swift-Testing-Agent-Skill --skill swift-testing-expert --global +luca install AvdLee/Swift-Testing-Agent-Skill --ref 1.2.0 --skill swift-testing-expert --global ``` Use a custom global Lucafile: @@ -40,7 +40,9 @@ Example `~/.config/luca/Lucafile`: skills: - name: swift-testing-expert repository: AvdLee/Swift-Testing-Agent-Skill + version: 1.2.0 - repository: vercel-labs/agent-skills + version: latest agents: - claude-code diff --git a/docs/skills/installing-skills.md b/docs/skills/installing-skills.md index 3d38201..5d17a18 100644 --- a/docs/skills/installing-skills.md +++ b/docs/skills/installing-skills.md @@ -9,20 +9,34 @@ Skills are Markdown files hosted in Git repositories that extend the capabilitie ## Install All Skills from a Repository +Individual skill installs require a version, pinned with `--ref`: + ```bash -luca install AvdLee/Swift-Testing-Agent-Skill +luca install AvdLee/Swift-Testing-Agent-Skill --ref 1.2.0 ``` -Luca clones the repository, discovers all skills inside it, and symlinks them into every supported agent's skill directory in your project. +Luca clones the repository at that tag or commit, discovers all skills inside it, and symlinks them into every supported agent's skill directory in your project. ## Install Specific Skills Use `--skill` to install only named skills from a repository: ```bash -luca install vercel-labs/agent-skills --skill web-design-guidelines --skill deploy-to-vercel +luca install vercel-labs/agent-skills --ref 1.2.0 --skill web-design-guidelines --skill deploy-to-vercel +``` + +## Pinning a Version + +`--ref` accepts a git tag, a commit SHA, or the literal value `latest` (always resolves to the repository's current default-branch HEAD commit): + +```bash +luca install vercel-labs/agent-skills --ref 1.2.0 +luca install owner/repo --ref abc1234 +luca install owner/repo --ref latest ``` +Unlike a pinned tag or SHA, `--ref latest` re-checks the remote repository on every install, so the resolved commit — and therefore what gets installed — can change between runs as the upstream repository advances. See [Lucafile: skills](/skills/lucafile-skills) for the same behavior when declaring `version:` in a Lucafile. + ## Target Specific Agents Use `--agent` to install skills only for specific agents: @@ -47,6 +61,15 @@ luca install vercel-labs/agent-skills --use-npx luca installed --skills ``` +Output lists each installed version per skill name — including multiple versions when the same skill has been installed at different refs: + +``` +Installed skills: + swift-concurrency 2.1.1, abc1234 + swift-testing-expert 1.2.0 + deploy-scripts v3.0.0 +``` + ## Uninstalling Skills ```bash diff --git a/docs/skills/lucafile-skills.md b/docs/skills/lucafile-skills.md index 4407d33..c9dc6c8 100644 --- a/docs/skills/lucafile-skills.md +++ b/docs/skills/lucafile-skills.md @@ -14,8 +14,10 @@ Add a `skills:` section to your Lucafile to declare which skills to install alon skills: - name: swift-testing-expert # Install a specific skill by name (optional) repository: AvdLee/Swift-Testing-Agent-Skill + version: 1.2.0 # Git tag, commit SHA, or "latest" - repository: vercel-labs/agent-skills # Omit name to install all skills from the repo + version: abc1234 agents: # Agent identifiers to target (optional — omit for all) - claude-code @@ -27,21 +29,73 @@ agents: # Agent identifiers to target (optiona | Field | Required | Description | |---|---|---| -| `repository` | Yes | GitHub shorthand (`owner/repo`) or full HTTPS/Git URL. | +| `repository` | Yes | GitHub shorthand (`owner/repo`), full HTTPS/Git URL, or a `repos` alias key. | | `name` | No | Name of a specific skill to install. Omit to install all skills from the repository. | +| `version` | Yes, unless inherited from a `repos` alias | Git tag, commit SHA, or `latest`. | | `agents` | No | List of agent identifiers to install skills for. Omit to target all supported agents. | +Every skill must resolve to a `version` — either declared on the skill entry or inherited from its `repos:` alias. Installing without one fails with a clear error. + +## Versioning + +The `version` field accepts: + +- a git tag (e.g. `1.2.0`) +- a commit SHA (e.g. `abc1234`) +- the literal value `latest`, which always resolves to the repository's current default-branch HEAD commit + +```yaml +skills: + - name: skill-creator + repository: vercel-labs/agent-skills + version: latest +``` + +When `version: latest` is used, Luca runs `git ls-remote` against the repository on every install to determine the current HEAD commit SHA. That resolved SHA — never the literal string `latest` — is what's used for the on-disk cache path (`~/.luca/skills/{name}/{sha}/`) and the `git checkout`. This has two consequences: + +- Every install with `version: latest` requires a network round-trip to check the remote, even if the resolved commit turns out to be one already cached locally (in which case the download itself is still skipped). +- Two installs at different times can resolve to different commits — and therefore install different content — if the upstream repository gained new commits in between. Pin to a tag or SHA instead if you need fully reproducible installs across your team. + +Skills are cached at versioned paths — globally at `~/.luca/skills/{name}/{version}/` and project-locally at `.luca/skills/{name}/{version}/` — so different projects (or different skill entries referencing the same repository) can install different versions side by side without conflicting. + ## Repository Aliases -Use `repos:` to define shorthand aliases for repositories you reference often: +Use `repos:` to define shorthand aliases for repositories you reference often. An alias can be a bare string (URL only — each skill referencing it must set its own `version`) or an object with a default `version` inherited by every skill that uses the alias: ```yaml repos: - myskills: https://github.com/myorg/agent-skills + myskills: https://github.com/myorg/agent-skills # bare string, no default version + + ios-skills: + url: git@github.com:org/ios-skills.git + version: 1.2.0 # all skills below inherit this skills: - name: my-skill repository: myskills + version: 1.0.0 # required — myskills has no default version + + - name: swift-concurrency + repository: ios-skills # inherits 1.2.0 from the repo entry + + - name: swift-testing-expert + repository: ios-skills + version: abc1234 # overrides the repo version for this skill only +``` + +Referencing the same repository at two different versions (e.g. a stable tag for most skills and a specific SHA for one experimental skill) is supported — each unique `(repository, version)` pair is cloned and cached independently, so it won't trigger a version-conflict error: + +```yaml +repos: + ios-skills: { url: git@github.com:org/ios-skills.git, version: 947ad594 } + ios-skills-preview: { url: git@github.com:org/ios-skills.git, version: 3445c638 } + +skills: + - name: swift-concurrency + repository: ios-skills # cloned at 947ad594 + + - name: swift-concurrency-next + repository: ios-skills-preview # cloned at 3445c638 — separate checkout ``` ## Installing Only Skills