Skip to content

docs(readme): simplify sdk install examples #9

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
samzong merged 1 commit into from
Jun 30, 2026
Merged

docs(readme): simplify sdk install examples #9

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
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
90 changes: 26 additions & 64 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -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

Expand All @@ -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:
Expand Down Expand Up @@ -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 (
Expand Down Expand Up @@ -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

Expand Down
21 changes: 8 additions & 13 deletions docs/vision.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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:

Expand All @@ -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
Expand All @@ -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.

Expand All @@ -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.
Expand Down Expand Up @@ -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

Expand Down Expand Up @@ -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:

Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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.

Loading