diff --git a/README.md b/README.md index 5823b23..57f5563 100644 --- a/README.md +++ b/README.md @@ -2,7 +2,8 @@ Shared installer SDK for bundled and public GitHub Agent Skills. -CLI authors ship or point to a skill. `kitup` models that skill as a directory tree, resolves safe agent targets, validates `SKILL.md`, copies the full tree into the right host directories, and writes ownership metadata so updates stay safe. +CLI authors ship or point to a skill. `kitup` models that skill as a directory tree, resolves safe agent targets, validates `SKILL.md`, +copies the full tree into the right host directories, and writes ownership metadata so updates stay safe. ```text mycli skill install @@ -38,7 +39,9 @@ mycli/ skills/mycli/SKILL.md ``` -Your CLI owns the command name and framework shell. `kitup` owns the standard install flags, agent selector mapping, host detection, safe selection policy, summary text, confirmation, workflow exit classification, target paths, bundle validation, copy/update semantics, metadata, and conflicts. +Your CLI owns the command name and framework shell. `kitup` owns the standard install flags, agent selector mapping, +host detection, safe selection policy, summary text, confirmation, workflow exit classification, target paths, +bundle validation, copy/update semantics, metadata, and conflicts. ### TypeScript @@ -48,76 +51,38 @@ Install: npm install @kitup/sdk ``` -Use the workflow API for user-facing install commands: - -```ts -import { - directoryBundle, - installFlagError, - installWorkflowError, - parseInstallFlags, - runBundledSkillInstall, -} from "@kitup/sdk"; - -const flags = parseInstallFlags({ - scope: "user", - agents: ["codex"], - yes: false, - dryRun: false, -}); -const flagError = installFlagError(flags.errors); -if (flagError) throw flagError; - -const result = await runBundledSkillInstall({ - appId: "mycli", - skillBundle: directoryBundle("./skills/mycli"), - scope: flags.scope, - scopeSet: flags.scopeSet, - promptScope: true, - agents: flags.agents, - yes: flags.yes, - dryRun: flags.dryRun, -}); -const workflowError = installWorkflowError(result); -if (workflowError) throw workflowError; -``` - -For embedded bundles, pass the whole skill tree: +Embed the install workflow: ```ts -import { filesBundle, runBundledSkillInstall } from "@kitup/sdk"; +import { directoryBundle, runBundledSkillInstall } from "@kitup/sdk"; await runBundledSkillInstall({ appId: "mycli", - skillBundle: filesBundle([ - { path: "SKILL.md", contents: skillMd }, - { path: "references/guide.md", contents: guide }, - ]), + skillBundle: directoryBundle("./skills/mycli"), scope: "user", - agents: ["codex"], }); ``` -For public GitHub directories, configure the GitHub bundle in the embedding CLI. The user-facing install command stays the same: +For full CLI flags, wire `parseInstallFlags` into `runBundledSkillInstall` with `scopeSet` and `promptScope`, then map exits with `installFlagError` and `installWorkflowError`; see [API](docs/API.md). -```ts -import { githubBundle, runBundledSkillInstall } from "@kitup/sdk"; +For embedded bundles or public GitHub directories, pass a different `skillBundle` value to the same install call: -await runBundledSkillInstall({ - appId: "mycli", - skillBundle: githubBundle({ - owner: "acme", - repo: "mycli-skills", - path: "skills/mycli", - ref: "v1.2.3", - }), - scope: "user", - agents: ["codex"], +```ts +import { filesBundle, githubBundle } from "@kitup/sdk"; + +const embeddedSkillBundle = filesBundle([ + { path: "SKILL.md", contents: skillMd }, + { path: "references/guide.md", contents: guide }, +]); + +const githubSkillBundle = githubBundle({ + owner: "acme", + repo: "mycli-skills", + path: "skills/mycli", + ref: "v1.2.3", }); ``` -Go, Rust, and Cobra use the same `skillBundle` shape; see [API](docs/API.md) for language-specific constructors. - ### Go Install: @@ -161,7 +126,7 @@ result, err := kitup.RunBundledSkillInstall(kitup.InstallWorkflowOptions{ }) ``` -For Cobra CLIs, use the optional adapter. The adapter does not own installer behavior; it only wires Cobra flags to the core workflow. +For Cobra CLIs, the adapter does not own installer behavior; it only wires Cobra flags to the core workflow. ```go import ( @@ -203,11 +168,8 @@ let result = kitup::run_bundled_skill_install(&kitup::InstallWorkflowOptions { })?; ``` -The workflow result contains the selected agents, dry-run plan, final install report, and cancellation state. The final install report contains `installed`, `updated`, `skipped`, `conflicts`, and `errors`. - -For lower-level integrations, `InstallBundledSkill` / `installBundledSkill` / `install_bundled_skill` remain primitive copy APIs. Do not wire a user-facing CLI directly to `agents: "auto"` unless you intentionally want primitive auto-detect behavior. Use the shared flag parsing, selector mapping, UX strings, and workflow exit helpers for CLI commands. - -For user-facing install commands, missing `--scope` is interactive state, not `user`. Pass `scopeSet` and enable `promptScope` so TTY workflows ask for scope before agent selection. `--yes` uses the configured default scope. +The workflow result contains the selected agents, dry-run plan, final install report, and cancellation state. +The final install report contains `installed`, `updated`, `skipped`, `conflicts`, and `errors`. ## Docs diff --git a/docs/vision.md b/docs/vision.md index 2c53c0e..7ac3b4e 100644 --- a/docs/vision.md +++ b/docs/vision.md @@ -18,7 +18,7 @@ If 1,000 CLI projects each write their own skill installer, and 100 agent hosts ## What kitup Is -`kitup` is the shared installer SDK for bundled Agent Skills. +`kitup` is the shared installer SDK for bundled and public GitHub Agent Skills. It lets a CLI author say: @@ -34,7 +34,7 @@ The SDK handles the boring parts: - detecting installed agent hosts - resolving user and project skill directories - validating `SKILL.md` -- copying bundled skill files +- copying skill bundle files - writing ownership metadata - updating changed skills - skipping unchanged skills @@ -45,11 +45,7 @@ That is all v0.1 needs to do. ## What kitup Is Not -`kitup` is not a marketplace. - -It is not a remote registry. - -It is not a skill marketplace or remote registry. +`kitup` is not a marketplace or remote registry. Marketplace tools serve users who want to discover and install arbitrary skills. `kitup` serves CLI authors who already ship a skill with their product. @@ -62,7 +58,7 @@ Marketplace flow: kitup flow: CLI author owns skill X user runs mycli skill install - kitup installs that bundled skill into local agent hosts + kitup installs that configured skill bundle into local agent hosts ``` Keeping that boundary small makes the SDK reliable enough for other projects to embed. @@ -94,7 +90,7 @@ mycli -> kitup SDK -> local agent hosts -> installed SKILL.md A CLI author should not need to know where Codex, Claude Code, Cursor, OpenCode, Gemini CLI, or future hosts keep skills. They should only choose: - app id -- bundled skill path +- skill bundle - user or project scope - automatic or explicit agent selection @@ -151,7 +147,7 @@ It is infrastructure, but infrastructure that removes real product friction. ## Long-Term Direction -The first release should prove bundled skill installation. +The first release should prove safe producer-side skill installation. After that, `kitup` can grow in three directions: @@ -182,9 +178,9 @@ Help CLI authors build better bundled skills: ### 3. Optional package-manager layer -Only after the producer-side SDK is stable, consider remote installs: +Public GitHub directory bundles are a producer-owned bundle input, not a package-manager layer. Only after the producer-side SDK is stable, consider broader package-manager behavior: -- install from GitHub repository +- private source authentication - install from tarball - registry index - version pinning @@ -220,4 +216,3 @@ Their agents should get the right skill. The CLI author should never maintain a list of 100 host-specific install paths. That is the whole product. -