Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
15 changes: 10 additions & 5 deletions DESIGN.md
Original file line number Diff line number Diff line change
Expand Up @@ -27,7 +27,10 @@ are resolved before comparison with installed claims.

`apply::compare` reports present entries, missing entries, and extras. Planning
asks each `Harness` (`plan_install`) to turn missing entries into actions, and reuses
removal plans for extras only in exact mode. Snapshotting converts typed installed
removal plans for extras only in exact mode. A missing skill entry is the exception: its
source is fetched once per plan, and each agent whose marketplace supplies every named skill
installs the owning plugins by the rule `install --skill` uses (`install::native_skills`); the
other agents, and every agent when the fetch fails, use `npx skills`. Snapshotting converts typed installed
facts into reproducible entries; it reports missing sources, invalid definitions,
and secret-bearing MCP servers as skipped.

Expand All @@ -42,8 +45,9 @@ asks which to install and returns its steps (`plan_add_source`); the remaining a
`npx skills`. The steps are shown as one plan and run only once approved. The CLI and the workspace
share `Session::install_source`, which also records what arrived in the library.
Explicit skill selections
use the owning plugins when the marketplace supplies all selected skills; sources without a
matching plugin use loose skills. Codex recognizes native and legacy Claude marketplaces.
use the owning plugins when the marketplace supplies all selected skills, none refused for a
symlink that leaves the source; sources without a matching plugin use loose skills. Library
installs and profile applies share this rule. Codex recognizes native and legacy Claude marketplaces.
Its project plugin plans download Git marketplace metadata without registering it globally,
then stage marketplace declarations and plugin enablement in the project's config, once per
marketplace however many of its plugins are picked. Codex materializes the declared plugins in
Expand Down Expand Up @@ -88,8 +92,9 @@ so an isolated command launches only after its profile is ready.
stored in profiles and the library. The name suggests a declarative desired state.
- **`Installed`**: what a harness reports it has, with identity, scope, agents, typed
details and the removal `Action`s.
- **`Action`**: one side effect (run a command, remove a path, edit a file). Planning is pure;
`harness::action` executes plans with staging.
- **`Action`**: one side effect (run a command, remove a path, edit a file). Planning changes nothing:
it reads, and fetches skill sources through the injected runner; `harness::action` executes
plans with staging.
- **`Harness`**: one coding tool (Claude, Codex). It reports `installed` and plans
`plan_install`, `plan_update` and `plan_add_source`. The `npx` module (free functions named like the
trait methods, `installed`, `plan_install` and `plan_update`, with their own parameters; not a
Expand Down
15 changes: 9 additions & 6 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -75,8 +75,10 @@ skills, and installs everything such a plugin ships. The plan names each plugin
skills it brings, and for `--all` lists the skills of the source that no plugin supplies, which
are not installed (name them with `--skill`). Sources without a matching plugin use `npx
skills`. A malformed marketplace or plugin manifest in the source never fails the install, its
skills install loose instead. `library install` and profile applies still install a loose
skill entry with `npx skills`, not through the plugin its source may offer.
skills install loose instead. `library install`, `use`, `run` and the list install a skill entry
the same way: the plan fetches its source, and each agent whose marketplace supplies every named
skill installs the owning plugin; the others, and all of them when the fetch fails, use `npx
skills`.

A Codex project install writes the marketplace and plugin into `.codex/config.toml`, which a team
usually commits, so skillz refuses a source with a user, password or token in its URL (use ssh or
Expand Down Expand Up @@ -127,7 +129,7 @@ extends = ["base"] # optional, see below
agents = ["claude", "codex"] # default for entries that name none (this is the default)

[[entry]]
kind = "skill" # installed with `npx skills`
kind = "skill" # the owning plugin, else `npx skills`
source = "mattpocock/skills" # org/repo, git URL or local path
names = ["tdd", "grilling"]

Expand Down Expand Up @@ -163,7 +165,7 @@ Every value must be non-empty and must not start with `-`; an MCP entry has exac

| Kind | Claude | Codex |
| --- | --- | --- |
| skill | `npx skills add`, all agents at once | same |
| skill | the owning plugin when the source's marketplace supplies every name, else `npx skills add` with the other agents | same |
| plugin | `claude plugin marketplace add` + `plugin install`; project scope uses Claude's `local` scope, never the file the team shares | Global: `codex plugin marketplace add` + `plugin add`. Project: marketplace and plugin settings in `.codex/config.toml`; Codex materializes them on a marketplace refresh in a trusted project |
| subagent | `.md` files into `.claude/agents` (`~/.claude/agents` global) | `.toml` files into `.codex/agents` (`~/.codex/agents` global) |
| hook | `settings.json` (global) or `.claude/settings.local.json` (project) | `hooks.json` in the same scope |
Expand All @@ -189,7 +191,7 @@ wins.
```sh
skillz profile save web # snapshot what this project has installed (--force replaces)
skillz profile ls | show web | rm web
skillz use web --dry-run # what installing `web` into this project would do
skillz use web --dry-run # what installing `web` would do; installs nothing, but still fetches skill sources to plan
skillz use web # shows the plan, asks, then installs what is missing
skillz use web --exact # also removes what `web` does not want (-y skips the question)
skillz use web -g # the same at user level: plugins, skills and the rest for every project
Expand Down Expand Up @@ -243,7 +245,8 @@ change. It only ever adds: a second run adds nothing, labels you
gave are kept, and items that are no longer installed stay. The only way out of the library is
`skillz library remove` or removing it by hand in `store.json`. `SKILLZ_NO_SYNC=1` turns the startup scan
off. A hand-made skill or subagent is recorded by the directory that holds it (engine `local`,
marked detected), so it is reinstalled with `npx skills add <that directory> --skill <name>`.
marked detected), so it is reinstalled from that directory: through the owning plugin when the
directory's marketplace supplies it, else with `npx skills add <that directory> --skill <name>`.
Items needing secrets, and items with nothing to reinstall them from, are not recorded.

**Moving a folder.** skillz keeps no registry of projects, so moving a project is fine, but a
Expand Down
1 change: 1 addition & 0 deletions src/app/apply/each_tests.rs
Original file line number Diff line number Diff line change
Expand Up @@ -89,6 +89,7 @@ fn watched_with(
env: &env,
scope: Scope::Project,
probe,
runner,
};
let mut events = Vec::new();
let each = applier.run(
Expand Down
3 changes: 3 additions & 0 deletions src/app/apply/mod.rs
Original file line number Diff line number Diff line change
Expand Up @@ -23,6 +23,7 @@ use crate::app::stale::Probe;
use skillz_harness::agents::{self, Harness};
use skillz_harness::env::Env;
use skillz_harness::model::{Installed, Scope};
use skillz_harness::runner::CommandRunner;

/// Everything a switch of one scope works with.
pub struct Applier<'a> {
Expand All @@ -31,6 +32,8 @@ pub struct Applier<'a> {
pub scope: Scope,
/// Tells whether a local source still exists before anything is installed from it.
pub probe: &'a dyn Probe,
/// Fetches a skill entry's source at plan time to see whether its marketplace supplies it.
pub runner: &'a dyn CommandRunner,
}

impl Applier<'_> {
Expand Down
85 changes: 73 additions & 12 deletions src/app/apply/plan.rs
Original file line number Diff line number Diff line change
@@ -1,6 +1,11 @@
use std::collections::{BTreeSet, HashMap};

use crate::app::install::{NativeSkills, native_skills};
use crate::app::profile::Profile;
use skillz_harness::Spec;
use skillz_harness::action::Action;
use skillz_harness::clone;
use skillz_harness::model::Agent;
use skillz_harness::provision::{self, Unsupported};

use super::Applier;
Expand All @@ -9,7 +14,8 @@ use super::switch::Switch;

impl Applier<'_> {
/// What the scope needs to hold `target`: what is missing gets installed and, when `exact`,
/// what the profile does not want gets removed. Reads source locations and the installed inventory.
/// what the profile does not want gets removed. Reads source locations and the installed
/// inventory, and fetches the sources of missing skills.
pub fn plan(&self, target: &Profile, exact: bool) -> anyhow::Result<Switch> {
let target = target.clone().in_env(self.env);
let standing = compare(&target.resolved(), &self.installed()?);
Expand All @@ -30,22 +36,77 @@ impl Applier<'_> {
})
}

/// The install steps for each entry, and what some agent cannot take.
/// The install steps for each entry, and what some agent cannot take. A skill's agents whose
/// source marketplace supplies it install the owning plugins; the others use `npx skills`.
fn installs_for(&self, entries: &[Spec]) -> (Vec<(Spec, Vec<Action>)>, Vec<Unsupported>) {
let mut native = self.native_skills_by_entry(entries);
let mut installs = Vec::new();
let mut unsupported = Vec::new();
for entry in entries {
let planned = provision::plan_entries(
self.adapters,
std::slice::from_ref(entry),
self.scope,
self.env,
);
unsupported.extend(planned.unsupported);
if !planned.steps.is_empty() {
installs.push((entry.clone(), planned.steps));
for (index, entry) in entries.iter().enumerate() {
let mut steps = Vec::new();
let through_npx = match native.remove(&index) {
Some(split) if !split.native.is_empty() => {
steps.extend(split.native.into_iter().flat_map(|(_, steps)| steps));
(!split.rest.is_empty()).then(|| entry.clone().with_agents(split.rest))
}
_ => Some(entry.clone()),
};
if let Some(through_npx) = through_npx {
let planned = provision::plan_entries(
self.adapters,
std::slice::from_ref(&through_npx),
self.scope,
self.env,
);
unsupported.extend(planned.unsupported);
steps.extend(planned.steps);
}
if !steps.is_empty() {
installs.push((entry.clone(), steps));
}
}
(installs, unsupported)
}

/// How each skill entry divides between agents installing its owning plugins and agents
/// keeping `npx skills`, by its index in `entries`. Each source is fetched once; an entry whose
/// source cannot be fetched or read is left out, so all its agents keep `npx skills`.
fn native_skills_by_entry(&self, entries: &[Spec]) -> HashMap<usize, NativeSkills> {
let skills: Vec<(usize, &str, &[String], &[Agent])> = entries
.iter()
.enumerate()
.filter_map(|(index, entry)| match entry {
Spec::Skill {
source,
names,
agents,
} => Some((index, source.as_str(), names.as_slice(), agents.as_slice())),
_ => None,
})
.collect();
let sources: BTreeSet<&str> = skills.iter().map(|&(_, source, ..)| source).collect();
let mut split = HashMap::new();
for source in sources {
let fetched =
clone::with_source(source, &self.env.project, self.runner, |src, resolved| {
let from_source = skills.iter().filter(|&&(_, from, ..)| from == source);
Ok(from_source
.filter_map(|&(index, _, names, agents)| {
let native = native_skills(
self.adapters,
self.env,
self.scope,
(src, resolved),
names,
agents,
)
.ok()?;
Some((index, native))
})
.collect::<Vec<_>>())
});
split.extend(fetched.unwrap_or_default());
}
split
}
}
Loading
Loading