From 88939ad23da68c904dbbe9ef3b067951c38016ba Mon Sep 17 00:00:00 2001 From: Harlan Wilton Date: Tue, 1 Sep 2026 15:58:13 +1000 Subject: [PATCH 1/3] docs(brand): align repo words with the curated registry position Front doors still read as a v1 generator or a flat verb list. This lands the Workstream 1 wording: npm metadata and homepage, README rewrite with tagline, proof points, and Author a Skill, SECURITY.md, glossary terms for registry, provenance, curated, author, and lockfile, clap about lines, the TLS error wording, the protocol README, and one real example selector everywhere. Claude-Session: https://claude.ai/code/session_018T67Ndp8FAjnHWthXABbJW --- .github/logos/favicon.svg | 5 + .github/logos/logo-icon.svg | 4 + .github/logos/logo-light.svg | 13 ++ .github/logos/logo-mark-light.svg | 3 + .github/logos/logo.svg | 13 ++ GLOSSARY.md | 55 +++++++++ README.md | 131 ++++++++++----------- SECURITY.md | 49 ++++++++ crates/skilld-command/src/lib.rs | 19 +-- crates/skilld-command/tests/remote.rs | 2 +- crates/skilld-native/src/lib.rs | 2 +- package.json | 11 +- packages/cli-darwin-arm64/package.json | 1 + packages/cli-darwin-x64/package.json | 1 + packages/cli-linux-arm64-gnu/package.json | 1 + packages/cli-linux-arm64-musl/package.json | 1 + packages/cli-linux-x64-gnu/package.json | 1 + packages/cli-linux-x64-musl/package.json | 1 + packages/cli-win32-arm64-msvc/package.json | 1 + packages/cli-win32-x64-msvc/package.json | 1 + packages/protocol/README.md | 18 +-- skills/generate-package-skill/SKILL.md | 1 + skills/generate-project-skill/SKILL.md | 1 + 23 files changed, 245 insertions(+), 90 deletions(-) create mode 100644 .github/logos/favicon.svg create mode 100644 .github/logos/logo-icon.svg create mode 100644 .github/logos/logo-light.svg create mode 100644 .github/logos/logo-mark-light.svg create mode 100644 .github/logos/logo.svg create mode 100644 SECURITY.md diff --git a/.github/logos/favicon.svg b/.github/logos/favicon.svg new file mode 100644 index 00000000..2ec32ee1 --- /dev/null +++ b/.github/logos/favicon.svg @@ -0,0 +1,5 @@ + + + + + diff --git a/.github/logos/logo-icon.svg b/.github/logos/logo-icon.svg new file mode 100644 index 00000000..68dd2e66 --- /dev/null +++ b/.github/logos/logo-icon.svg @@ -0,0 +1,4 @@ + + + + diff --git a/.github/logos/logo-light.svg b/.github/logos/logo-light.svg new file mode 100644 index 00000000..f376adc7 --- /dev/null +++ b/.github/logos/logo-light.svg @@ -0,0 +1,13 @@ + + + + + skilld + diff --git a/.github/logos/logo-mark-light.svg b/.github/logos/logo-mark-light.svg new file mode 100644 index 00000000..e7b72348 --- /dev/null +++ b/.github/logos/logo-mark-light.svg @@ -0,0 +1,3 @@ + + + diff --git a/.github/logos/logo.svg b/.github/logos/logo.svg new file mode 100644 index 00000000..412011b5 --- /dev/null +++ b/.github/logos/logo.svg @@ -0,0 +1,13 @@ + + + + + skilld + diff --git a/GLOSSARY.md b/GLOSSARY.md index 72fffd4c..9426d843 100644 --- a/GLOSSARY.md +++ b/GLOSSARY.md @@ -22,6 +22,11 @@ Every public export, command, error, route, and document uses these terms. | Source status | lockfile and protocol | published value | skilld CLI, CI | source status | | Update relation | skilld CLI JSON v1 | published value | Agent, developer, CI | update relation | | Agent target | skilld CLI | published configuration | Agent | Agent target | +| registry | skilld.dev | published surface | developer, Agent | registry | +| curated | skilld.dev | published surface | developer | curated | +| author | GitHub | external standard | skilld.dev, developer | author | +| provenance | lockfile and protocol | published value | skilld CLI, developer | provenance | +| lockfile | `.skills/skilld-lock.yaml` | published file | skilld CLI, CI | lockfile | | Identifier | Term | | --- | --- | @@ -232,6 +237,56 @@ The Rust type for the second is `TransientSkill`, never `SkillRun`. **Casing:** `Outdated Skill report` in prose, `outdated` in commands. +### registry + +**Is:** the curated index of Skills that skilld.dev publishes and the skilld CLI searches. + +**Use for:** the skilld.dev catalogue as a whole and `skilld search` results. + +**Never:** marketplace, store, hub, directory. + +**Casing:** `registry` in sentences, `skilld registry` when the owner matters. + +### curated + +**Is:** admitted to the registry by a person, with a reason that person can state. + +**Use for:** the registry and the Skills it lists. + +**Never:** approved, certified, vetted, official. + +**Casing:** `curated` in sentences. + +### author + +**Is:** the GitHub account or person who wrote a Skill in their own Repository. + +**Use for:** the credited writer of one Skill on every surface. + +**Never:** creator, publisher, contributor, owner in customer copy. + +**Casing:** `author` in sentences, `Author` in headings. + +### provenance + +**Is:** the recorded facts about where a Skill came from: Repository, commit, author, Artifact attestation, and source status. + +**Use for:** what `skilld verify` and the source status describe. + +**Never:** trust, safety, reputation, security. + +**Casing:** `provenance` in sentences. + +### lockfile + +**Is:** the `.skills/skilld-lock.yaml` file that records each installed Skill, its source, commit, digest, and source status. + +**Use for:** the file `skilld install` writes and restores. + +**Never:** manifest, lock, state file, config. + +**Casing:** `lockfile` in prose, `skilld-lock.yaml` for the file name. + ## Banned | Never | Use instead | Why | diff --git a/README.md b/README.md index 16273afc..3af2b7e0 100644 --- a/README.md +++ b/README.md @@ -1,17 +1,14 @@ -

skilld

+

skilld

[![npm version](https://img.shields.io/npm/v/skilld?color=yellow)](https://npmjs.com/package/skilld) [![npm downloads](https://img.shields.io/npm/dm/skilld?color=yellow)](https://npm.chart.dev/skilld) [![license](https://img.shields.io/npm/l/skilld?color=yellow)](https://github.com/skilld-dev/skilld/blob/main/LICENSE) -Search, run, install, and keep Agent Skills current. +**Curated agent skills by humans.** -skilld v3 has two products: +Search, run, install, and keep them current. One command, every Agent. -- The native `skilld` CLI manages Skills. -- The JavaScript [`skilld-harness`](./packages/harness) package runs visible Skill generation and review instructions. - -The skilld CLI contains no Skill generation logic or Agent runtime. +skilld is a curated registry of agent Skills real maintainers wrote in their own GitHub repositories, usable with one command in every Agent. ## Install the skilld CLI @@ -22,58 +19,53 @@ npm install --global skilld The npm package selects a native executable for the current system. It has no JavaScript CLI engine or JavaScript fallback. -Ask your Agent to run the skilld-maintained Skill for the current session: - -```sh -skilld run skilld -``` - -Install it only when you want your Agent to keep it across sessions: - -```sh -skilld install skilld --global -``` - -Use `--agent` when you want an explicit Agent target: - -```sh -skilld install skilld --global --agent codex -``` - ## Run a Skill without installing it `skilld run` is the default way to use a Skill. -It prints `SKILL.md` to stdout. +It prints `SKILL.md` to stdout and installs nothing. Ask your Agent to run the command and follow the printed instructions. If you run it yourself, pass the output to your Agent. ```sh -npx skilld run skilld:skilld-dev/skills/vue +npx skilld run skilld:skilld-dev/skills/find-skill ``` A remote run writes no Skill files. It creates no lockfile entry, Agent target, project file, or Skill cache. -The command retains no Skill files after it exits. skilld names the supporting files a Skill carries and prints none of them. Read one when the instructions call for it: ```sh -npx skilld run skilld:skilld-dev/skills/vue --revision --file references/api.md +npx skilld run skilld:skilld-dev/skills/find-skill --revision --file references/api.md ``` Use the revision and file-read command from the initial output. skilld never prints executable or binary files. A Skill that must run its own script needs an install. -Install the Skill when you want it in every session: +## Install a Skill + +Install a Skill when you want it in every session: ```sh -skilld install skilld:skilld-dev/skills/vue +skilld install skilld:skilld-dev/skills/find-skill ``` An install writes files. Ask the user first. +Use `--agent` when you want an explicit Agent target: + +```sh +skilld install skilld:skilld-dev/skills/find-skill --agent codex +``` + +Install the skilld-maintained `skilld` Skill so your Agent knows the CLI: + +```sh +skilld install skilld --global +``` + ## Use the skilld CLI ```sh @@ -81,27 +73,28 @@ An install writes files. Ask the user first. skilld search vue # Run a Skill for this session only -skilld run skilld:skilld-dev/skills/vue +skilld run skilld:skilld-dev/skills/find-skill # Read one supporting file that Skill carries -skilld run skilld:skilld-dev/skills/vue --revision --file references/api.md +skilld run skilld:skilld-dev/skills/find-skill --revision --file references/api.md # Install a Skill in the current project -skilld install skilld:skilld-dev/skills/vue +skilld install skilld:skilld-dev/skills/find-skill # Inspect installed Skills skilld list -skilld view vue +skilld view find-skill # Keep Skills current -skilld verify vue -skilld update vue +skilld verify find-skill +skilld update find-skill +skilld outdated # Check update relations for an Agent or CI skilld update --check --json # Remove a Skill -skilld remove vue +skilld remove find-skill ``` Project installs update `.skills/skilld-lock.yaml` and the selected Agent targets. @@ -110,6 +103,31 @@ Use `--mode copy` or `--mode symlink` to control target writes. Run `skilld install` without a source to restore the lockfile state. +## Why skilld + +- **Every Skill has a human author.** A maintainer wrote it in their own GitHub Repository, and skilld.dev lists it under their name. +- **Read the SKILL.md first.** `skilld run` prints the file before your Agent follows it, and `skilld view` links the source Repository. +- **Know when the source moved.** skilld records the source commit. `skilld update --check` reports each update relation, and `skilld outdated` lists what fell behind. +- **One command, every Agent.** `skilld install` detects your Agent targets. Claude Code, Codex, Cursor, Gemini CLI, and the rest get the same Skill. + +skilld reads `SKILL.md` files in the Agent Skills format ([agentskills.io](https://agentskills.io)). +The CLI checks that `SKILL.md` sits at the Skill root and declares a name. + +See how skilld compares with skills.sh and Context7: https://skilld.dev/vs/skills-sh + +## Author a Skill + +Run the skilld-maintained `generate-package-skill` Skill, or the Harness, to bootstrap a draft Skill for a package you maintain. +Edit the draft, commit it to your Repository, and own it from there. +skilld lists it with your name and a link to the file. + +The skilld-maintained Skills: + +- [`skilld`](./skills/skilld): search, run, and install Skills with the CLI +- [`generate-package-skill`](./skills/generate-package-skill): draft a Skill for a package you maintain +- [`generate-project-skill`](./skills/generate-project-skill): draft a Skill from a project you maintain +- [`review-skill`](./skills/review-skill): review a Skill before you publish it + ## Artifact delivery The skilld CLI resolves remote Skills through the skilld.dev API. @@ -142,9 +160,6 @@ The user reviews the Skill before use. Direct mode never handles private Repositories. It never falls back to skilld.dev. -Generated commands use POSIX shell quoting on Unix. -They use PowerShell quoting on Windows. - ## Source status - `verified`: skilld checked a skilld.dev Artifact and its attestation. @@ -153,6 +168,7 @@ They use PowerShell quoting on Windows. `verified` describes provenance checks. It does not endorse the instructions inside a Skill. +See [SECURITY.md](./SECURITY.md) for what skilld checks and how to report a problem. ## Account and configuration @@ -169,39 +185,10 @@ skilld config list Native builds store account credentials in the operating system keychain. The CLI does not store tokens in environment variables or plain text files. -## Generate or review a Skill - -Skill generation lives outside the skilld CLI. - -Use these skilld-maintained Skills directly with your Agent: - -- [`generate-package-skill`](./skills/generate-package-skill) -- [`generate-project-skill`](./skills/generate-project-skill) -- [`review-skill`](./skills/review-skill) -- [`skilld`](./skills/skilld) - -Direct Skill runs remain user reviewed. -The instructions and changes stay visible to the user. +## Harness Use [`skilld-harness`](./packages/harness) when an application or CI needs strict output checks. The Harness runs the same visible Skill files through an AI SDK Harness. - -```sh -pnpm add skilld-harness @ai-sdk/harness ws zod -``` - -```ts -import { createSkillHarness } from 'skilld-harness' - -const skillHarness = createSkillHarness({ harness, sandbox }) - -const result = await skillHarness.run({ - _tag: 'PackageSkill', - source: { _tag: 'NpmPackage', spec: 'vue' }, - destination: { rootDir: '.agents/skills', name: 'vue' }, -}) -``` - See the [`skilld-harness` guide](./packages/harness/README.md) for its full contract. ## Upgrade from v2 @@ -212,7 +199,7 @@ Back up v2 state before replacing the CLI. Follow the [v2 to v3 migration guide](./docs/migrate-v2-to-v3.md). It maps removed commands and explains rollback limits. -## v3 development +## Development ```sh pnpm install diff --git a/SECURITY.md b/SECURITY.md new file mode 100644 index 00000000..e59e8a21 --- /dev/null +++ b/SECURITY.md @@ -0,0 +1,49 @@ +# Security + +## Report a vulnerability + +Report a vulnerability in the skilld CLI, the Harness, or the skilld.dev API in private. + +- Use [GitHub private vulnerability reporting](https://github.com/skilld-dev/skilld/security/advisories/new) on `skilld-dev/skilld`. +- Or email harlan@harlanzw.com. + +Do not open a public issue for a vulnerability. +Include the CLI version, the command you ran, and the steps to reproduce. + +To report a Skill that misleads or harms users, email the same address with the Skill selector. + +## What skilld checks + +The skilld CLI verifies remote Skills before it installs them. +For every Artifact from skilld.dev, the CLI checks: + +- the exact statement bytes of the Artifact attestation +- the attestation signature against a trusted root key compiled into the CLI +- the SHA-256 digest of the Artifact contents +- the archive structure, including a `SKILL.md` file at the Skill root with a `name` + +If no trusted root key exists, the CLI fails with `TRUSTED_ROOT_UNCONFIGURED`. +If any check fails, the CLI installs nothing. + +The CLI stores account credentials in the operating system keychain. +It never writes tokens to environment variables or plain text files. + +## What the source statuses mean + +The lockfile records one source status for each installed Skill. + +- `verified`: the CLI checked a skilld.dev Artifact and its attestation. The Skill bytes match one exact commit in the source Repository. +- `local`: the Skill came from a local directory or a bundled skilld-maintained Skill. The CLI checked no remote source. +- `unverified`: direct mode fetched the Skill from public GitHub without the skilld.dev API. The CLI checked no attestation. + +## What skilld never claims + +A source status describes provenance. +It states where a Skill came from and that its bytes did not change in transit. + +skilld never claims that a Skill is safe. +skilld does not review the instructions inside a Skill. +Check results from third parties describe their own findings, not an endorsement by skilld. + +Read a Skill before your Agent follows it. +`skilld run` prints `SKILL.md` so you can read it first. diff --git a/crates/skilld-command/src/lib.rs b/crates/skilld-command/src/lib.rs index 82e6fd4b..148a344a 100644 --- a/crates/skilld-command/src/lib.rs +++ b/crates/skilld-command/src/lib.rs @@ -70,9 +70,9 @@ pub struct Cli { enum Command { /// Search for Skills. Search { query: Vec }, - /// Install a Skill, or restore the Skills recorded in your lockfile. + /// Install a Skill, or restore the Skills in your lockfile. #[command( - long_about = "Install a Skill, or restore the Skills recorded in your lockfile.\n\nGive SOURCE as:\n skilld:OWNER/REPOSITORY/SKILL\n Install a hosted Artifact.\n github:OWNER/REPOSITORY/SKILL_PATH\n github:OWNER/REPOSITORY/SKILL_PATH#branch:BRANCH\n github:OWNER/REPOSITORY/SKILL_PATH#tag:TAG\n github:OWNER/REPOSITORY/SKILL_PATH#commit:SHA\n https://github.com/OWNER/REPOSITORY/tree/REF/SKILL_PATH\n Install a hosted Artifact from an explicit GitHub selector.\n Add --direct to fetch a public GitHub Repository instead.\n ./RELATIVE_PATH or ABSOLUTE_PATH\n Install a local Skill.\n skilld\n Install the skilld-maintained Skill with --global.\n\nRun skilld install without SOURCE to restore .skills/skilld-lock.yaml.\nVerified remote Skills restore the exact locked Git commit.", + long_about = "Install a Skill, or restore the Skills in your lockfile.\n\nGive SOURCE as:\n skilld:OWNER/REPOSITORY/SKILL\n Install a hosted Artifact.\n github:OWNER/REPOSITORY/SKILL_PATH\n github:OWNER/REPOSITORY/SKILL_PATH#branch:BRANCH\n github:OWNER/REPOSITORY/SKILL_PATH#tag:TAG\n github:OWNER/REPOSITORY/SKILL_PATH#commit:SHA\n https://github.com/OWNER/REPOSITORY/tree/REF/SKILL_PATH\n Install a hosted Artifact from an explicit GitHub selector.\n Add --direct to fetch a public GitHub Repository instead.\n ./RELATIVE_PATH or ABSOLUTE_PATH\n Install a local Skill.\n skilld\n Install the skilld-maintained Skill with --global.\n\nRun skilld install without SOURCE to restore .skills/skilld-lock.yaml.\nVerified remote Skills restore the exact locked Git commit.", after_long_help = "Examples:\n skilld install skilld:skilld-dev/skills/find-skill --agent codex\n skilld install github:skilld-dev/skilld/skills/skilld --direct --agent codex\n skilld install" )] Install { @@ -135,7 +135,7 @@ enum Command { #[arg(long)] global: bool, }, - /// View Skill details. + /// View Skill details and source. View { skill: String, #[arg(long)] @@ -147,7 +147,7 @@ enum Command { #[arg(long)] global: bool, }, - /// Update installed Skills. + /// Update installed Skills to their current source commit. Update { skill: Option, /// Check update relations without changing files. @@ -163,7 +163,7 @@ enum Command { #[arg(long)] global: bool, }, - /// Verify a Skill source. + /// Verify a Skill source and report its source status. Verify { skill: Option }, /// Report outdated and unmanaged Skills. Outdated { @@ -171,12 +171,12 @@ enum Command { #[arg(long)] all: bool, }, - /// Manage account authentication. + /// Log in, check, or log out of your account. Auth { #[command(subcommand)] command: AuthCommand, }, - /// Manage configuration. + /// Read, set, or list configuration values. Config { #[command(subcommand)] command: ConfigCommand, @@ -1761,7 +1761,10 @@ impl Host for LocalHost { .map_err(CommandError::remote)? { RemoteSourceState::Current => { - lines.push(Line::success(format!("Verified Skill {}.", name.as_str()))); + lines.push(Line::success(format!( + "Verified the source of Skill {}.", + name.as_str() + ))); } RemoteSourceState::Stale { .. } => { return Err(CommandError::operation( diff --git a/crates/skilld-command/tests/remote.rs b/crates/skilld-command/tests/remote.rs index ca8064f4..8ece2d00 100644 --- a/crates/skilld-command/tests/remote.rs +++ b/crates/skilld-command/tests/remote.rs @@ -2256,7 +2256,7 @@ fn remote_install_verify_and_failed_update_use_the_normal_transaction() { .iter() .map(skilld_ui::Line::plain_text) .collect::>(), - ["Verified Skill example."] + ["Verified the source of Skill example."] ); let before = fs::read(project.join(".skills/example/SKILL.md")).unwrap(); *provider.content.lock().unwrap() = b"---\nname: example\ndescription: second\n---\n".to_vec(); diff --git a/crates/skilld-native/src/lib.rs b/crates/skilld-native/src/lib.rs index f7c06b7f..df74e89c 100644 --- a/crates/skilld-native/src/lib.rs +++ b/crates/skilld-native/src/lib.rs @@ -187,7 +187,7 @@ fn transport_error(error: &ureq::Error, request_url: &str) -> RemoteError { ureq::Error::ConnectionFailed => format!("the connection to {host} failed"), ureq::Error::Timeout(_) => format!("the request to {host} timed out"), ureq::Error::Tls(_) | ureq::Error::Rustls(_) | ureq::Error::Pem(_) => { - format!("the secure connection to {host} failed") + format!("the TLS connection to {host} failed") } ureq::Error::Io(io) => match io.kind() { std::io::ErrorKind::TimedOut | std::io::ErrorKind::WouldBlock => { diff --git a/package.json b/package.json index a954896d..858c8abb 100644 --- a/package.json +++ b/package.json @@ -3,7 +3,7 @@ "type": "module", "version": "3.0.0-beta.3", "packageManager": "pnpm@11.24.0", - "description": "Search, run, install, and keep Skills current", + "description": "Search, run, install, and keep curated Agent Skills current", "author": { "name": "Harlan Wilton", "email": "harlan@harlanzw.com", @@ -16,14 +16,23 @@ } ], "license": "MIT", + "homepage": "https://skilld.dev", "repository": { "type": "git", "url": "git+https://github.com/skilld-dev/skilld.git" }, "keywords": [ "agent", + "agents", "skills", + "agent-skills", + "skill", + "claude-code", + "codex", + "cursor", "cli", + "registry", + "provenance", "github" ], "bin": { diff --git a/packages/cli-darwin-arm64/package.json b/packages/cli-darwin-arm64/package.json index 9a001b1d..fda422cb 100644 --- a/packages/cli-darwin-arm64/package.json +++ b/packages/cli-darwin-arm64/package.json @@ -3,6 +3,7 @@ "version": "3.0.0-beta.3", "description": "macOS arm64 executable for the skilld CLI", "license": "MIT", + "homepage": "https://skilld.dev", "repository": "github:skilld-dev/skilld", "publishConfig": { "access": "public", diff --git a/packages/cli-darwin-x64/package.json b/packages/cli-darwin-x64/package.json index 560448b3..5809f06b 100644 --- a/packages/cli-darwin-x64/package.json +++ b/packages/cli-darwin-x64/package.json @@ -3,6 +3,7 @@ "version": "3.0.0-beta.3", "description": "macOS x64 executable for the skilld CLI", "license": "MIT", + "homepage": "https://skilld.dev", "repository": "github:skilld-dev/skilld", "publishConfig": { "access": "public", diff --git a/packages/cli-linux-arm64-gnu/package.json b/packages/cli-linux-arm64-gnu/package.json index 061c5fcd..f0042ed3 100644 --- a/packages/cli-linux-arm64-gnu/package.json +++ b/packages/cli-linux-arm64-gnu/package.json @@ -3,6 +3,7 @@ "version": "3.0.0-beta.3", "description": "Linux arm64 GNU executable for the skilld CLI", "license": "MIT", + "homepage": "https://skilld.dev", "repository": "github:skilld-dev/skilld", "publishConfig": { "access": "public", diff --git a/packages/cli-linux-arm64-musl/package.json b/packages/cli-linux-arm64-musl/package.json index bc2e68b8..78a88a57 100644 --- a/packages/cli-linux-arm64-musl/package.json +++ b/packages/cli-linux-arm64-musl/package.json @@ -3,6 +3,7 @@ "version": "3.0.0-beta.3", "description": "Linux arm64 musl executable for the skilld CLI", "license": "MIT", + "homepage": "https://skilld.dev", "repository": "github:skilld-dev/skilld", "publishConfig": { "access": "public", diff --git a/packages/cli-linux-x64-gnu/package.json b/packages/cli-linux-x64-gnu/package.json index fcea2195..15a013c4 100644 --- a/packages/cli-linux-x64-gnu/package.json +++ b/packages/cli-linux-x64-gnu/package.json @@ -3,6 +3,7 @@ "version": "3.0.0-beta.3", "description": "Linux x64 GNU executable for the skilld CLI", "license": "MIT", + "homepage": "https://skilld.dev", "repository": "github:skilld-dev/skilld", "publishConfig": { "access": "public", diff --git a/packages/cli-linux-x64-musl/package.json b/packages/cli-linux-x64-musl/package.json index 941265b9..bf1a2c33 100644 --- a/packages/cli-linux-x64-musl/package.json +++ b/packages/cli-linux-x64-musl/package.json @@ -3,6 +3,7 @@ "version": "3.0.0-beta.3", "description": "Linux x64 musl executable for the skilld CLI", "license": "MIT", + "homepage": "https://skilld.dev", "repository": "github:skilld-dev/skilld", "publishConfig": { "access": "public", diff --git a/packages/cli-win32-arm64-msvc/package.json b/packages/cli-win32-arm64-msvc/package.json index 16e5fff2..cecdb587 100644 --- a/packages/cli-win32-arm64-msvc/package.json +++ b/packages/cli-win32-arm64-msvc/package.json @@ -3,6 +3,7 @@ "version": "3.0.0-beta.3", "description": "Windows arm64 executable for the skilld CLI", "license": "MIT", + "homepage": "https://skilld.dev", "repository": "github:skilld-dev/skilld", "publishConfig": { "access": "public" }, "os": ["win32"], diff --git a/packages/cli-win32-x64-msvc/package.json b/packages/cli-win32-x64-msvc/package.json index 89c465c0..ec6dcdde 100644 --- a/packages/cli-win32-x64-msvc/package.json +++ b/packages/cli-win32-x64-msvc/package.json @@ -3,6 +3,7 @@ "version": "3.0.0-beta.3", "description": "Windows x64 executable for the skilld CLI", "license": "MIT", + "homepage": "https://skilld.dev", "repository": "github:skilld-dev/skilld", "publishConfig": { "access": "public" }, "os": ["win32"], diff --git a/packages/protocol/README.md b/packages/protocol/README.md index 20552f25..288b8e73 100644 --- a/packages/protocol/README.md +++ b/packages/protocol/README.md @@ -1,6 +1,7 @@ # skilld-protocol -Wire shapes and constants shared between the [skilld CLI](https://github.com/skilld-dev/skilld) and [skilld.dev](https://skilld.dev). The single source of truth for everything that crosses that boundary: telemetry, audit, auth, device flow, collection manifests. +Wire shapes and constants shared between the [skilld CLI](https://github.com/skilld-dev/skilld) and [skilld.dev](https://skilld.dev). +The package is the single source of truth for everything that crosses that boundary. ## Install @@ -8,14 +9,17 @@ Wire shapes and constants shared between the [skilld CLI](https://github.com/ski pnpm add skilld-protocol ``` -ESM-only. Node â‰Ĩ18. One peer-free dep: `zod` v4. +ESM only. Node 22 or newer. One dependency: `zod` v4. ## Subpaths -- `skilld-protocol/wire` — every endpoint shape as a zod schema (suffix `Schema`) and the matching inferred TS type (no suffix). Use `import { FooSchema }` for runtime validation; `import type { Foo }` for the type. -- `skilld-protocol/constants` — readonly tuples backing the closed enums plus their inferred unions. -- `skilld-protocol/test-fixtures` — canonical payloads each consumer round-trips through their schema on CI. +- `skilld-protocol/v1`: TypeScript types generated from `openapi/skilld-v1.yaml`. This is the Artifact delivery contract the v3 CLI uses: source resolution, Skill search, Artifact descriptors, attestations, check results, grants, trusted roots, and problems. +- `skilld-protocol/openapi/skilld-v1.yaml`: the OpenAPI 3.1 document itself. +- `skilld-protocol/wire`: zod schemas (suffix `Schema`) and inferred types (no suffix) for the endpoints skilld.dev still serves to older clients. Use `import { FooSchema }` for runtime validation and `import type { Foo }` for the type. +- `skilld-protocol/constants`: readonly tuples behind the closed enums, plus their inferred unions. +- `skilld-protocol/test-fixtures`: canonical payloads that each consumer round-trips through its schema on CI. -## Repo +## Repository -This package lives inside the [skilld CLI](https://github.com/skilld-dev/skilld) monorepo at `packages/protocol`. The CLI consumes it as a workspace dep; skilld.dev consumes the published npm version. +This package lives in the [skilld CLI](https://github.com/skilld-dev/skilld) monorepo at `packages/protocol`. +The Rust crates mirror the v1 OpenAPI document. skilld.dev consumes the published npm version. diff --git a/skills/generate-package-skill/SKILL.md b/skills/generate-package-skill/SKILL.md index 958c3e11..beb746bd 100644 --- a/skills/generate-package-skill/SKILL.md +++ b/skills/generate-package-skill/SKILL.md @@ -6,6 +6,7 @@ description: Generate or update an Agent Skill for an npm or local package using # Generate a package Skill Create a focused Skill that helps an Agent use one package correctly. +This Skill is for maintainers who author a draft Skill they own. ## Inputs diff --git a/skills/generate-project-skill/SKILL.md b/skills/generate-project-skill/SKILL.md index 4bda8583..573d4505 100644 --- a/skills/generate-project-skill/SKILL.md +++ b/skills/generate-project-skill/SKILL.md @@ -6,6 +6,7 @@ description: Generate or update an Agent Skill from the observed workflows, boun # Generate a project Skill Create a compact, searchable Skill from the project itself. +This Skill is for maintainers who author a draft Skill they own. ## Inputs From f6500b46817b43e926f87da059098b0069506e8f Mon Sep 17 00:00:00 2001 From: Harlan Wilton Date: Wed, 2 Sep 2026 01:31:58 +1000 Subject: [PATCH 2/3] docs(migrate): point examples at the find-skill Skill The migration guide kept run and install examples for a vue Skill that skilld-dev/skills does not publish. Use find-skill, which the README already names. Claude-Session: https://claude.ai/code/session_018T67Ndp8FAjnHWthXABbJW --- README.md | 2 +- docs/migrate-v2-to-v3.md | 6 +++--- 2 files changed, 4 insertions(+), 4 deletions(-) diff --git a/README.md b/README.md index 3af2b7e0..504519c5 100644 --- a/README.md +++ b/README.md @@ -70,7 +70,7 @@ skilld install skilld --global ```sh # Find a Skill -skilld search vue +skilld search find-skill # Run a Skill for this session only skilld run skilld:skilld-dev/skills/find-skill diff --git a/docs/migrate-v2-to-v3.md b/docs/migrate-v2-to-v3.md index cb3e17d3..028082c9 100644 --- a/docs/migrate-v2-to-v3.md +++ b/docs/migrate-v2-to-v3.md @@ -93,8 +93,8 @@ It writes project state to `.skills/skilld-lock.yaml`. Search first, then run the returned selector: ```sh -skilld search vue -skilld run skilld:skilld-dev/skills/vue +skilld search find-skill +skilld run skilld:skilld-dev/skills/find-skill ``` Use the exact selector printed by your search result. @@ -105,7 +105,7 @@ It writes no project files or lockfile state. Install the Skill only when you want to keep it: ```sh -skilld install skilld:skilld-dev/skills/vue +skilld install skilld:skilld-dev/skills/find-skill ``` An install writes project files and records lockfile state. From a30c801be0791d73c0858c3efca12659af88ac5b Mon Sep 17 00:00:00 2001 From: Harlan Wilton Date: Wed, 2 Sep 2026 01:58:34 +1000 Subject: [PATCH 3/3] docs(readme): match the layout of the other harlan-zw packages Header, badges, tagline quote, Features, and What is skilld? now follow the shape of mdream, ripast, and gscdump. Commands use placeholders and a Selectors note explains the skilld:OWNER/REPOSITORY/SKILL form. Claude-Session: https://claude.ai/code/session_018T67Ndp8FAjnHWthXABbJW --- README.md | 145 ++++++++++++++++++++++++++++++------------------------ 1 file changed, 82 insertions(+), 63 deletions(-) diff --git a/README.md b/README.md index 504519c5..248c97e6 100644 --- a/README.md +++ b/README.md @@ -1,121 +1,137 @@ -

skilld

+

skilld

[![npm version](https://img.shields.io/npm/v/skilld?color=yellow)](https://npmjs.com/package/skilld) [![npm downloads](https://img.shields.io/npm/dm/skilld?color=yellow)](https://npm.chart.dev/skilld) -[![license](https://img.shields.io/npm/l/skilld?color=yellow)](https://github.com/skilld-dev/skilld/blob/main/LICENSE) +[![license](https://img.shields.io/github/license/skilld-dev/skilld?color=yellow)](https://github.com/skilld-dev/skilld/blob/main/LICENSE) -**Curated agent skills by humans.** +> ðŸŠķ Curated agent skills by humans. Search, run, install, and keep them current. One command, every Agent. -Search, run, install, and keep them current. One command, every Agent. +skilld logo -skilld is a curated registry of agent Skills real maintainers wrote in their own GitHub repositories, usable with one command in every Agent. +

+ + + + +
+Made possible by my Sponsor Program 💖
Follow me @harlan_zw ðŸĶ â€Ē Join Discord for help
+
+

-## Install the skilld CLI +## Features -```sh -npm install --global skilld -``` +- ðŸ‘Ī **Every Skill has a human author.** A maintainer wrote it in their own GitHub Repository. skilld.dev lists it under their name with a link to the source file. +- 📖 **Read before you run.** `skilld run` prints `SKILL.md` and installs nothing. Your Agent follows it for this session only. +- 🔁 **Know when the source moved.** skilld records the source commit. `skilld update --check` reports each update relation, and `skilld outdated` lists what fell behind. +- ðŸŽŊ **One command, every Agent.** `skilld install` detects your Agent targets. Claude Code, Codex, Cursor, Gemini CLI, and the rest get the same Skill. +- 🔏 **Verified delivery.** skilld.dev builds an immutable Artifact from an exact commit. The CLI checks its digest and attestation before it writes a file. +- ðŸĶ€ **Native binary, no runtime.** The npm package selects a native executable for your system. No JavaScript engine, no fallback. -The npm package selects a native executable for the current system. -It has no JavaScript CLI engine or JavaScript fallback. +## What is skilld? -## Run a Skill without installing it +skilld is a curated registry of agent Skills that real maintainers wrote in their own GitHub repositories, usable with one command in every Agent. -`skilld run` is the default way to use a Skill. -It prints `SKILL.md` to stdout and installs nothing. -Ask your Agent to run the command and follow the printed instructions. -If you run it yourself, pass the output to your Agent. +A Skill is a directory with a `SKILL.md` file in the [Agent Skills](https://agentskills.io) format. +Install-count leaderboards and generated doc dumps tell you a Skill is popular. +skilld tells you who wrote it, links the exact file, and tracks the commit it came from, so you can read it before your Agent follows it. -```sh -npx skilld run skilld:skilld-dev/skills/find-skill -``` +The `skilld` CLI searches, runs, installs, updates, verifies, and removes Skills. +It contains no Skill generation logic and no Agent runtime. +Skill authoring lives in visible [skilld-maintained Skills](#author-a-skill) and the optional [Harness](#harness). -A remote run writes no Skill files. -It creates no lockfile entry, Agent target, project file, or Skill cache. +See how skilld compares with skills.sh and Context7: [skilld.dev/vs/skills-sh](https://skilld.dev/vs/skills-sh). -skilld names the supporting files a Skill carries and prints none of them. -Read one when the instructions call for it: +## Get Started + +Install the CLI: ```sh -npx skilld run skilld:skilld-dev/skills/find-skill --revision --file references/api.md +npm install --global skilld ``` -Use the revision and file-read command from the initial output. -skilld never prints executable or binary files. -A Skill that must run its own script needs an install. +Find a Skill, then run it for this session: -## Install a Skill +```sh +skilld search find-skill +skilld run skilld:skilld-dev/skills/find-skill +``` -Install a Skill when you want it in every session: +`skilld run` prints `SKILL.md` to stdout and writes no file. +Ask your Agent to run the command and follow the printed instructions. +If you run it yourself, pass the output to your Agent. + +Install the Skill when you want it in every session: ```sh skilld install skilld:skilld-dev/skills/find-skill ``` -An install writes files. Ask the user first. +An install writes files. If an Agent runs the install, it asks you first. -Use `--agent` when you want an explicit Agent target: +Teach your Agent the CLI with the skilld-maintained `skilld` Skill: ```sh -skilld install skilld:skilld-dev/skills/find-skill --agent codex +skilld install skilld --global ``` -Install the skilld-maintained `skilld` Skill so your Agent knows the CLI: +### Selectors + +`skilld:OWNER/REPOSITORY/SKILL` names one Skill in the registry. +`skilld search` prints the selector for each result. +`skilld-dev/skills` is the Repository; `find-skill` is the Skill directory inside it. + +### Supporting files + +skilld names the supporting files a Skill carries and prints none of them. +Read one when the instructions call for it: ```sh -skilld install skilld --global +skilld run skilld:skilld-dev/skills/find-skill --revision --file references/api.md ``` -## Use the skilld CLI +Use the revision and file-read command from the initial output. +skilld never prints executable or binary files. +A Skill that must run its own script needs an install. + +## Commands ```sh # Find a Skill -skilld search find-skill +skilld search # Run a Skill for this session only -skilld run skilld:skilld-dev/skills/find-skill +skilld run # Read one supporting file that Skill carries -skilld run skilld:skilld-dev/skills/find-skill --revision --file references/api.md +skilld run --revision --file -# Install a Skill in the current project -skilld install skilld:skilld-dev/skills/find-skill +# Install a Skill in the current project, or restore the lockfile +skilld install +skilld install # Inspect installed Skills skilld list -skilld view find-skill +skilld view # Keep Skills current -skilld verify find-skill -skilld update find-skill skilld outdated - -# Check update relations for an Agent or CI skilld update --check --json +skilld update +skilld verify # Remove a Skill -skilld remove find-skill +skilld remove ``` Project installs update `.skills/skilld-lock.yaml` and the selected Agent targets. Use `--global` for account level Agent targets. +Use `--agent ` to name a target; repeat it for several. Use `--mode copy` or `--mode symlink` to control target writes. +Use `--json` with `search`, `run`, and `update --check` for stable output. -Run `skilld install` without a source to restore the lockfile state. +Run `skilld install --help` for every Agent target value. -## Why skilld - -- **Every Skill has a human author.** A maintainer wrote it in their own GitHub Repository, and skilld.dev lists it under their name. -- **Read the SKILL.md first.** `skilld run` prints the file before your Agent follows it, and `skilld view` links the source Repository. -- **Know when the source moved.** skilld records the source commit. `skilld update --check` reports each update relation, and `skilld outdated` lists what fell behind. -- **One command, every Agent.** `skilld install` detects your Agent targets. Claude Code, Codex, Cursor, Gemini CLI, and the rest get the same Skill. - -skilld reads `SKILL.md` files in the Agent Skills format ([agentskills.io](https://agentskills.io)). -The CLI checks that `SKILL.md` sits at the Skill root and declares a name. - -See how skilld compares with skills.sh and Context7: https://skilld.dev/vs/skills-sh - -## Author a Skill +## Author a Skill Run the skilld-maintained `generate-package-skill` Skill, or the Harness, to bootstrap a draft Skill for a package you maintain. Edit the draft, commit it to your Repository, and own it from there. @@ -128,6 +144,9 @@ The skilld-maintained Skills: - [`generate-project-skill`](./skills/generate-project-skill): draft a Skill from a project you maintain - [`review-skill`](./skills/review-skill): review a Skill before you publish it +Direct Skill runs stay user reviewed. +The instructions and changes stay visible to you. + ## Artifact delivery The skilld CLI resolves remote Skills through the skilld.dev API. @@ -155,12 +174,12 @@ skilld install github:skilld-dev/skilld/skills/skilld --direct --agent codex ``` The installed Skill receives the `unverified` source status. -The user reviews the Skill before use. +Review the Skill before use. Direct mode never handles private Repositories. It never falls back to skilld.dev. -## Source status +### Source status - `verified`: skilld checked a skilld.dev Artifact and its attestation. - `local`: the Skill came from a local directory or a bundled skilld-maintained Skill. @@ -199,7 +218,7 @@ Back up v2 state before replacing the CLI. Follow the [v2 to v3 migration guide](./docs/migrate-v2-to-v3.md). It maps removed commands and explains rollback limits. -## Development +## Development ```sh pnpm install