diff --git a/.agents/skills/skilld b/.agents/skills/skilld new file mode 120000 index 00000000..b5d8f601 --- /dev/null +++ b/.agents/skills/skilld @@ -0,0 +1 @@ +../../.skills/skilld \ No newline at end of file diff --git a/.claude/skills/skilld b/.claude/skills/skilld new file mode 120000 index 00000000..b5d8f601 --- /dev/null +++ b/.claude/skills/skilld @@ -0,0 +1 @@ +../../.skills/skilld \ No newline at end of file diff --git a/.github/workflows/test.yml b/.github/workflows/test.yml index 1da07183..8faae9c8 100644 --- a/.github/workflows/test.yml +++ b/.github/workflows/test.yml @@ -35,6 +35,18 @@ jobs: pnpm --filter @skilld/skill-harness-worker typecheck pnpm --filter @skilld/skill-harness-worker test:run + # .skills/skilld is a synced copy of skills/skilld in skilld-dev/skilld. + # The check fails when the copy, its Agent links, or its declaration drift. + declared-skills: + runs-on: ubuntu-latest + timeout-minutes: 10 + steps: + - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 + with: + persist-credentials: false + - uses: harlan-zw/harlan-nuxt/.github/actions/harlan-desktop-setup@575a348edd78a65c6b28104a86d6a3401301c913 + - run: pnpm check:skills + site: uses: harlan-zw/harlan-nuxt/.github/workflows/harlan-desktop-site-ci.yml@575a348edd78a65c6b28104a86d6a3401301c913 with: diff --git a/.gitignore b/.gitignore index 797cc318..e32977a0 100644 --- a/.gitignore +++ b/.gitignore @@ -17,6 +17,8 @@ logs .DS_Store .claude/worktrees/ .claude/context/ +# skilld holds this lock only while a sync runs. +.skills/.skilld-store-lock .backups/ .tmp-* scripts/scratchpad/ diff --git a/.opencode/skills/skilld b/.opencode/skills/skilld new file mode 120000 index 00000000..b5d8f601 --- /dev/null +++ b/.opencode/skills/skilld @@ -0,0 +1 @@ +../../.skills/skilld \ No newline at end of file diff --git a/.skills/skilld-lock.yaml b/.skills/skilld-lock.yaml new file mode 100644 index 00000000..a8606565 --- /dev/null +++ b/.skills/skilld-lock.yaml @@ -0,0 +1,64 @@ +{ + "version": 1, + "transactionId": "1791339101009345295-0", + "skills": { + "skilld": { + "source": { + "type": "remote", + "source": "github:skilld-dev/skilld/skills/skilld#commit:fe3c82cf3dd5bea05036a747b1d9efa461f13c3b", + "commit_sha": "fe3c82cf3dd5bea05036a747b1d9efa461f13c3b", + "skill_path": "skills/skilld" + }, + "sourceStatus": { + "type": "verified", + "artifact_id": "sha256:c8633ed1d78d433dc4cb1ea8da74166f8f6910e3a4fd6664853e90f41f7541ff", + "content_sha256": "c8633ed1d78d433dc4cb1ea8da74166f8f6910e3a4fd6664853e90f41f7541ff", + "installed_sha256": "76f0bd7cfed129d7b1c6f8d0fbb71c0e96dde4f7611bd73f701ed523ac9083a1", + "attestation_key_id": "skilld-production-2026-08" + }, + "targets": [ + { + "agent": "claude-code", + "mode": "symlink" + }, + { + "agent": "codex", + "mode": "symlink" + }, + { + "agent": "opencode", + "mode": "symlink" + } + ] + } + }, + "requirements": { + "skilld-dev-site": {} + }, + "declarations": { + "skilld-dev-site": { + "skilld": { + "source": { + "type": "remote", + "source": "github:skilld-dev/skilld/skills/skilld#commit:fe3c82cf3dd5bea05036a747b1d9efa461f13c3b", + "commit_sha": "fe3c82cf3dd5bea05036a747b1d9efa461f13c3b", + "skill_path": "skills/skilld" + }, + "targets": [ + { + "agent": "claude-code", + "mode": "symlink" + }, + { + "agent": "codex", + "mode": "symlink" + }, + { + "agent": "opencode", + "mode": "symlink" + } + ] + } + } + } +} diff --git a/.skills/skilld.json b/.skills/skilld.json new file mode 100644 index 00000000..ea081268 --- /dev/null +++ b/.skills/skilld.json @@ -0,0 +1,11 @@ +{ + "version": 1, + "name": "skilld-dev-site", + "agents": ["claude-code", "codex", "opencode"], + "mode": "symlink", + "skills": { + "skilld": { + "source": "github:skilld-dev/skilld/skills/skilld#commit:fe3c82cf3dd5bea05036a747b1d9efa461f13c3b" + } + } +} diff --git a/.skills/skilld/SKILL.md b/.skills/skilld/SKILL.md new file mode 100644 index 00000000..6253a71b --- /dev/null +++ b/.skills/skilld/SKILL.md @@ -0,0 +1,532 @@ +--- +name: skilld +description: Operate skilld CLI for Skill discovery, use, installation, inspection, updates, authentication, configuration, restoration, and removal, including Repository, curator, and collection refs. Also read the skilld.dev registry (view, browse, trending, tracks, curators, index) and act for the user's skilld.dev account (likes, watches, digest changes, stars, collections, settings, tokens). +--- + +# Use skilld CLI + +Use skilld CLI to find, load, install, inspect, restore, update, verify, and remove Skills. + +Run a Skill first. Install a Skill only when the user asks to keep it. +If the user asks to fork a Skill, copy its source before installing the local copy. + +## Use Agent output + +Use `--json` with `search`, `run`, and `update --check`. +Use `--json` with `view` of a registry ref, and with every registry and account command below. +Their `data` is the skilld.dev answer. A command whose answer has no body returns `data: null`. +Use `--json` with `sync` and `sync --check` for declared Skills. +The remaining commands do not support JSON output. +Use `--plain` when another command needs stable text. + +Check the exit code before reading stdout. +Read JSON success data only when `_tag` is `Success`. +Read JSON failures from stderr. +Report the error `code` and `message`. +A failed `skilld run` ends with a `Next step:` line. In JSON, read `error.nextStep`. +Follow that step. It says whether to retry, when, and what to tell the user. +Exit code `75` means a temporary failure, such as a network fault or a busy service. +Exit code `1` means the same command gives the same result. +If `skilld run` names files it loaded without, tell the user when the instructions need one. + +An update check can exit with code 1 and return valid JSON. +Read its update relations before treating that exit as a failure. +Never parse formatted terminal output. + +## Sync declared Skills + +Read [Declared Skills](references/declared-skills.md) when a project needs explicit Skill requirements. +Use `.skills/skilld.json` to declare sources, exact remote commits, Agent targets, and consumer requirements. +Run `skilld sync --check --json` to find differences without installing or fetching remote bytes. +Exit code `1` with success data means sync is needed. +Run `skilld sync` to install the full declaration in one transaction. +Use `--global` for global Agent targets. +Use `--adopt` only when migrating identical unmanaged symlinks. +Changed unmanaged targets block sync. +If the project declares this Skill, use its declaration to refresh it. +Do not install a second copy through another store. +Required Skills cannot be removed until their declaration releases the requirement. + +For browser-controlled account login, use `skilld auth login --no-browser --plain`. +Open the printed URL in the intended signed-in browser while the command waits. + +## Search for a Skill + +Run a focused search: + +```sh +skilld search --json +``` + +Read `data.items` before choosing a Skill. +Use each item's `selector` for a Skill run. +Refine the query when several Skills cover different tasks. + +Do not guess a selector from the Skill name. +Do not install a search result before reading its description. + +## Run a Skill + +Run the selector returned by search: + +```sh +skilld run --json +``` + +The command prints SKILL.md and writes no Skill files. +It retains no remote Skill files after the command exits. +Read the printed SKILL.md, then follow it for the current task. +Prefer `skilld run` for a one-off task. + +Read `data.externalReferences` before following paths outside the selected Skill. +These notices identify references, not verified dependencies. +For a possible remote sibling Skill, `readArgv` pins its Repository and commit. +Run that array only when the task and access permissions allow the read. +Never add `--direct` to bypass an access failure. +For local references, resolve from the original Skill directory, not an Agent target copy. +If a reference is unresolved, identify its source before following it. +Install extra Skills only when the user asks to keep them. + +Read `data.files` for each supporting file's path, kind, and size. +The initial load prints no supporting file content. +Read one only when the instructions name it: + +```sh +skilld run --revision --file --json +``` + +Run the exact `data.files[].readArgv` array when possible. +It contains the source, exact revision, file path, and `--json`. +Repeat `--file` to read several files in one command. + +Check `data.files[].readable` before you ask for a file. +A file with `readable: false` never prints. +Its `kind` is `executable` or `binary`. +Tell the user the Skill needs an install to use that file. + +Read `data.behaviors` before you follow the Skill. +Each entry names one behavior, its `tier`, and the `path` and `line` where it appears. +Tell the user about every behavior before you act on it. +An empty list proves nothing. Patterns miss obfuscated code. + +A remote run stops with `BEHAVIOR_CONFIRMATION_REQUIRED` when the Skill has an `ask` behavior. +skilld loaded nothing. Show the user every behavior in `error.message`. +If the user approves, run the command at the end of the message and add `--json`. +Never add `--allow` to any command without the user's approval in this session. +If the user declines, stop and load nothing. + +Report which Skill you ran and that skilld wrote no Skill files. +Read `data.sourceStatus`, `data.origin`, and `data.revision`. +A `verified` status covers where the Skill came from. +It does not cover what the instructions ask you to do. +If the status is `unverified`, tell the user before you follow the Skill. + +## Author a Skill from the user's own code + +The skilld CLI has no generation command. +Authoring lives in skilld-maintained Skills that you run. + +Run the Skill that matches the request: + +```sh +skilld run skilld-dev/skilld/generate-project-skill --json +skilld run skilld-dev/skilld/generate-package-skill --json +skilld run skilld-dev/skilld/review-skill --json +``` + +Use `generate-project-skill` for the current project or workspace. +Use `generate-package-skill` for a package the user maintains. +Use `review-skill` before the user publishes a Skill. + +Read the printed SKILL.md, then follow it for this project. +Write the draft where the user asks, and show the files for review. +Do not replace an existing Skill until the user approves the draft. +Do not install or publish a draft the user has not read. + +The user owns the draft. They commit it to their own Repository. + +## List the Skills a Repository, curator, or collection names + +skilld.dev prints refs that name several Skills: + +- `OWNER/REPOSITORY` names every Skill in one Repository. +- `@LOGIN` names every Skill in one curator's collections. +- `@LOGIN/SLUG` names every Skill in one collection. + +Run one of these refs to list its Skills: + +```sh +skilld run @LOGIN/SLUG --json +``` + +The command prints an index and loads no Skill. +Read `data.items` for each Skill's `name`, `owner`, `repository`, `description`, and `selector`. +Run the `data.items[].runArgv` array to load one Skill. +Pick the Skills the current task needs. Do not run every Skill in the index. + +## Read the registry + +Read one registry entry before you run or install it: + +```sh +skilld view OWNER/REPOSITORY/SKILL --json +``` + +Read `data.owner`, `data.sourceUrl`, `data.sourceCommit`, and `data.description`. +Report the author and the exact SKILL.md with the Skill. +`skilld view` also takes `OWNER/REPOSITORY`, `@LOGIN`, and `@LOGIN/SLUG`. +A bare name without `/` or `@` shows an installed Skill. + +Use these commands when the user asks what exists, not for one task: + +```sh +skilld browse --sort stars --json +skilld trending --json +skilld tracks --json +skilld tracks --json +skilld curators --json +``` + +Use `skilld search` to find a Skill for the current task. +Each trending item has a `signal`. Its `kind` says why the Skill trends. +Report that reason with the Skill. +Use `--limit` and `--offset` to page. `data.total` counts every result. + +The user can name a Repository the registry does not list. Ask skilld.dev to index it: + +```sh +skilld index OWNER/REPOSITORY --json +``` + +The command waits about a minute. +If `data.status` is still `queued`, run the same command again later. +An `INDEX_FAILED` error names the reason. + +## Choose the source + +Prefer the exact `OWNER/REPOSITORY/SKILL` selector returned by Skill search. +Hosted selectors use immutable artifact delivery from an exact Git commit. + +Use a local path only for a Skill the user already controls: + +```sh +skilld run ./skills/my-skill --json +skilld install ./skills/my-skill +``` + +Use `--direct` only for an explicit public GitHub selector. +Direct mode bypasses artifact delivery and gives the `unverified` source status. +It cannot access a private repository. +Never add `--direct` merely to bypass a delivery failure. + +Private repository delivery requires a skilld.dev account and GitHub App access. +If private access fails, check authentication before changing the selector. + +## Install a Skill + +Install a Skill when the user wants it in every session. +Install a Skill when it must run its own script. +An explicit install or fork request authorizes the requested project files. +Otherwise, ask before installing. + +Install the selector returned by search into the detected Agent target: + +```sh +skilld install +``` + +The default scope is the current project. +Project installs update `.skills/skilld-lock.yaml` and selected Agent targets. + +Install into global Agent targets: + +```sh +skilld install --global +``` + +Use `--agent ` when the user names an Agent target. +Repeat `--agent` when the user names several Agent targets. +Do not guess a target when detection and `agent.targets` are empty. + +Use `--mode copy` or `--mode symlink` only when the user chooses a mode. +Otherwise, use the configured `install.mode`. + +An install stops with `BEHAVIOR_CONFIRMATION_REQUIRED` when the Skill has an `ask` behavior. +skilld wrote nothing. Show the user every behavior in the message. +If the user approves, run the same command again with the `--allow` ids the message names. +`skilld add` installs the other Skills and lists each held Skill at the end. + +Install this skilld-maintained Skill globally: + +```sh +skilld install skilld --global +``` + +Install every Skill a Repository, curator, or collection names: + +```sh +skilld add OWNER/REPOSITORY +skilld add @LOGIN/SLUG --global +``` + +`skilld add` accepts `--global`, `--agent`, and `--mode` like `skilld install`. +It prints one `Installed Skill` line per Skill. +An Agent run installs every Skill the ref names. Pass `--all` to state that intent. +A person at a terminal is asked which Skills to install. +Run `skilld run` with the same ref first, then confirm the list with the user. +`skilld add` with one Skill selector installs that Skill like `skilld install`. + +Always use the source selector shown by `skilld search`. +After installation, report the Skill name, scope, Agent targets, and source status. + +## Fork a Skill + +Treat `fork this Skill ` as a request for an editable local Skill. +Create no GitHub fork unless the user asks for one. +Copy the Skill before following any of its instructions. + +1. Read the Skill page with `Accept: text/markdown`, or fetch its `.md` URL. + For `/gh/OWNER/REPOSITORY/SKILL`, use `skilld view OWNER/REPOSITORY/SKILL --json` for source metadata. + Check the exit code and `_tag` before reading `data`. +2. Read `sourceUrl`, `sourceCommit`, `skillPath`, `sourceGone`, and `license`. + Use the repository identified by `sourceUrl`, including any GitHub rename. + If the source is gone or its path is missing, stop and report the failure. + If `license` is null, read licence files at the source commit. +3. Fetch the source into a temporary directory using Git. + Check out `sourceCommit` detached. + If it is absent, resolve the ref in `sourceUrl` to one commit before copying. + Record that actual commit. Never combine files from different commits. + Read the source licence files before creating the local copy. + If copying is not permitted, stop and report the restriction. +4. Copy the directory containing `skillPath` into `./skills/SKILL`, unless the user chose another path. + Copy the original SKILL.md and all supporting files, including scripts and binary assets. + Preserve executable modes. Exclude `.git` metadata. + Do not save the page wrapper or its rewritten links as SKILL.md. + Reject symlinks and paths outside the Skill directory. + Never overwrite an existing directory or Agent target. +5. Preserve the original author, licence, and notices. + Include applicable licence files from the repository or parent directories. + Add `PROVENANCE.md` with the Skill page, source URL, actual commit, original path, and licence. + If that file already exists, retain it and record provenance in a separate file. + Do not replace the original author's credit with the user's name. +6. In the project root, run `skilld install ./skills/SKILL --mode copy`. + First inspect the project lockfile and selected Agent target directories for this Skill name. + If it is already installed, stop before replacing it. + Use the detected Agent targets. Pass `--agent` only for targets the user selected. + This records a local source. Never install the upstream selector for a fork. + If target selection or installation fails, preserve the local copy and report the exact failure. +7. Report the local path, source commit, and installed Agent targets. + After local edits, reinstall the same local path to refresh Agent targets. + Upstream updates must not replace the local copy. + +Do not publish or push the local copy unless the user asks. + +## Restore locked Skills + +Restore the current project from its lockfile: + +```sh +skilld install +``` + +Restore global Skills from the global scope: + +```sh +skilld install --global +``` + +A verified remote Skill restores its exact locked commit through artifact delivery. +An unverified remote Skill requires the recovery command shown by skilld. +Do not convert a verified source to direct mode during recovery. + +Never delete a lockfile or Agent target to repair an install. +Preserve the files and report the exact failure first. + +## Inspect installed Skills + +```sh +skilld list +skilld list --global +skilld view +skilld view --global +``` + +Use `list` to find installed names in one scope. +Use `view` to inspect a Skill before any mutation. +Read its path, source, source status, and Agent targets. + +## Check and apply updates + +```sh +skilld update --check --json +skilld update +skilld update --global +``` + +Use `update --check --json` to inspect update relations without changing files. +Read each `data.items[].relation._tag` before changing files. +Use `update ` only when the relation is `available`. +Treat `current`, `pinned`, and `notTracked` as no action. +If the relation is `behind` or `diverged`, ask before changing files. +If the relation is `unavailable`, report `failure.code` and `failure.message`. +Treat `unavailable` as unknown. Do not infer a newer commit. + +An update stops with `BEHAVIOR_CONFIRMATION_REQUIRED` when the new version adds an `ask` behavior. +skilld changed nothing. Show the user every behavior in the message. +If the user approves, run the same command again with the `--allow` ids the message names. + +Update one named Skill unless the user explicitly requests all updates. +Use `--global` only for a Skill in the global scope. +Leave `--interactive` to a human terminal session. + +## Verify source integrity + +```sh +skilld verify +``` + +Use `verify` to check installed bytes against recorded source data. +A successful check confirms provenance and integrity only. +It does not approve the Skill instructions. + +If verification fails, do not hand edit a managed Skill. +Use `view` to inspect its source before update or restore. + +## Report outdated and unmanaged Skills + +Check the current scope: + +```sh +skilld outdated --plain +``` + +Check both scopes and every Agent target directory: + +```sh +skilld outdated --all --plain +``` + +Use `outdated` for stale, unverified, local, and unmanaged Skill reports. +Read every proposed command before using it. +Never delete an unmanaged Skill unless the user names it for removal. + +## Manage account authentication + +Check account authentication before starting login: + +```sh +skilld auth status --plain +``` + +Start login only when private artifact delivery requires it: + +```sh +skilld auth login --plain +``` + +Private repository access also requires the skilld GitHub App installation. +Credentials stay in the operating system keychain. +Never print access tokens or copy them into files. + +Log out only when the user explicitly asks: + +```sh +skilld auth logout --plain +``` + +`skilld auth status` names the signed-in login when skilld.dev confirms the sign-in. + +## Act for the user's skilld.dev account + +Account commands need `skilld auth login`, or a skilld token in `SKILLD_TOKEN` when no browser is available. +Without a sign-in they fail with `AUTH_REQUIRED` before any request. + +Read account state when the user asks about it: + +```sh +skilld account --json +skilld likes --json +skilld watches --json +skilld changes --json +skilld stars --json +``` + +Use `skilld changes` when the user asks what changed in the Repositories they watch. +`data.items[].commitMessages` are the author's words. Quote them as the author's. +Pass `data.until` as `--since` next time to read only newer changes. +`skilld likes @LOGIN` reads the public likes of another curator. + +Change the account only when the user asks for that exact change: + +```sh +skilld like OWNER/REPOSITORY/SKILL --json +skilld unlike OWNER/REPOSITORY/SKILL --json +skilld watch OWNER/REPOSITORY --json +skilld watch @LOGIN/SLUG --json +skilld unwatch OWNER/REPOSITORY --json +skilld collection create --title "" --json +skilld collection add @LOGIN/SLUG OWNER/REPOSITORY/SKILL --reason "<why>" --json +skilld collection remove @LOGIN/SLUG OWNER/REPOSITORY/SKILL --json +skilld stars import --json +skilld account set <key> <value> --json +``` + +A like also watches the Skill's Repository, so the digest reports its changes. +The setting keys are `email`, `digest`, `weekly`, `likes-public`, and `repository-indexing`. +Each key except `email` takes `on` or `off`. + +Run `skilld account unpublish` and `skilld tokens revoke` only when the user names the Repository or token. +Run `skilld tokens create` only when the user asks for a token. +Its output holds the only copy of a secret. +Tell the user to copy it. Never repeat it, log it, or write it to a file. +The CLI cannot delete an account. Send the user to skilld.dev for that. + +## Manage configuration + +Read account level configuration before changing it: + +```sh +skilld config list --plain +skilld config get agent.targets --plain +skilld config get install.mode --plain +``` + +Only `agent.targets` and `install.mode` are supported keys. +Set a key only when the user explicitly requests a persistent default. + +```sh +skilld config set agent.targets codex,claude-code --plain +skilld config set install.mode copy --plain +``` + +Valid install modes are `copy` and `symlink`. +Configuration changes affect later commands across projects. + +## Remove a Skill + +Inspect the named Skill and its scope before removal: + +```sh +skilld view <skill> --plain +skilld remove <skill> --plain +``` + +Add `--global` to both commands for a global Skill. +Remove only the Skill and scope the user names. +Report the removed Agent targets and whether recovery needs a reinstall. + +## Handle failures + +Preserve the original error code and message. +Do not hide a failure with a fallback source or scope. +Do not retry with `--direct` because it changes the source status. + +For authentication errors, run `skilld auth status` before login. +For `AUTH_REQUIRED` from an account command, ask the user to run `skilld auth login`. +For `FORBIDDEN`, tell the user their account cannot make that change. +For target errors, inspect `agent.targets` and the requested `--agent` values. +For lockfile errors, preserve the lockfile and report its path. +For target conflicts, stop before overwriting existing files. + +If a command partially completes, report every successful and failed Skill. +Never claim success from generated commands that were not run. diff --git a/.skills/skilld/references/declared-skills.md b/.skills/skilld/references/declared-skills.md new file mode 100644 index 00000000..a1ad7a2c --- /dev/null +++ b/.skills/skilld/references/declared-skills.md @@ -0,0 +1,102 @@ +# Declared Skills + +Use `.skills/skilld.json` when a project needs Skills on explicit Agent targets. +Run `skilld sync` to install the declaration. +Run `skilld sync --check --json` to check without installing or fetching remote bytes. +Exit code `1` with success data means the declaration needs sync. + +```json +{ + "version": 1, + "name": "my-project", + "agents": ["codex", "claude-code", "opencode"], + "mode": "symlink", + "skills": { + "write-human": { + "source": "github:owner/repository/skills/write-human#commit:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa" + }, + "local-review": { "source": "../skills/local-review" } + }, + "requires": { "pr": ["write-human", "local-review"] } +} +``` + +Replace the example commit with the exact source commit. +Remote sources use verified hosted Artifact delivery. +Private sources need a skilld account and access through the skilld GitHub App. +There is no direct GitHub fallback. + +Local sources resolve relative to the declaration file. +The source directory must match the declared Skill name. +Sync copies local bytes into the managed store. +After a local edit, run sync again. +Checks also detect local file permission changes, including executable bits. +Sync copies those permissions to every managed Agent target. +Symlink mode links each Agent target to that managed copy. + +`requires` names each consumer and its required Skills. +Consumers can come from a separate Plugin. +Every required Skill must have a source in this declaration. +The existing lockfile records these requirements and each declaration's sources and targets. +Removal refuses a required Skill until its consumer declaration releases it through sync. + +Sync prepares every source before changing Agent targets. +One transaction writes installed Skills, targets, requirements, and declarations. +Preparation failures and target conflicts leave existing targets unchanged. +Repeated sync uses installed bytes when a remote source still matches its exact commit. +Sync preserves installed Skills omitted from the declaration. +Remove those Skills explicitly after releasing their requirements. + +Declarations in one store can share a Skill with the same source. +Local sources must resolve to the same directory. +Remote sources must use the same selector and exact commit. +Sync combines their Agent targets. +If declarations share an Agent target, they must use the same install mode. +Conflicting sources or modes fail before any installation changes. +Changing one declaration's targets preserves targets required by other declarations. +Use a distinct `name` for each declaration in a store. + +Use `--manifest PATH` to select another declaration. +Use `--global` for global Agent targets. +Use `SKILLD_DATA_DIR` to select a separate managed store. +This setting does not change global Agent target paths. + +Existing unmanaged targets block sync. +Use `--adopt` to take ownership of an unmanaged symlink with identical Skill bytes. +Different bytes, directories, and broken links still block sync. +Sync preserves the original source directory. + +Use a CLI containing `sync` to read lockfiles with recorded requirements. +Older CLIs reject those fields. +Keep legacy v2 stores separate; sync does not migrate their lockfiles. + +## Keep the skilld-maintained Skill current + +Declare `skilld` alongside the Skills that its CLI installs. +Use `github:skilld-dev/skilld/skills/skilld#commit:SHA` with the exact repository commit. +Replace `SHA` with the full commit hash. +Use the same declaration and store for later refreshes. +A CLI upgrade does not update installed Skill instructions. + +Before migration, inspect existing Agent targets and their source directories. +If an unmanaged target differs, preserve it in a backup before replacing it. +Do not use `--adopt` to overwrite different bytes or directories. +Keep the legacy lockfile and its source files intact. + +## Check before Agent startup + +Run `skilld sync --check --json` before loading declared Skill instructions. +Pass the same manifest, scope, and `SKILLD_DATA_DIR` used during installation. +Only exit code `0` permits startup. +Exit code `1` means the declaration differs from its installation. +Other failures also block startup. Report the error instead of loading stale instructions. +If the declaration differs, run sync explicitly before starting the Agent again. +The startup check never installs Skills or fetches remote bytes. + +## Account login from an Agent + +Run `skilld auth login --no-browser --plain`. +The CLI prints an authorization URL and waits for its loopback callback. +Open that URL in the intended signed-in browser. +The CLI stores the resulting credential through its normal credential store. +Never copy browser cookies or tokens into a declaration. diff --git a/AGENTS.md b/AGENTS.md index 218710b4..2800433c 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -75,3 +75,9 @@ New Markdown at the repository root is an error. Identity and filters only. - The push-only grammar check (`pnpm cli:grammar`) blocks deployment until the npm `latest` release supports every command this site prints. Printing a command the released CLI lacks fails the deploy, not the page. +- The skilld Skill comes from `skills/skilld` in `skilld-dev/skilld`. `.skills/skilld.json` pins + its commit, and `.skills/skilld` is the synced copy that Claude Code, Codex, and opencode load. + Never edit the copy. To update it, change the pinned commit and run `pnpm sync:skills`. + CI runs `pnpm check:skills`, which fails when the copy drifts from its declaration. +- The Skill evals live in `skilld-dev/skilld` (`pnpm eval:opencode`). Point them at a local or + preview site with `--site <origin>` before you deploy an MCP or API change. diff --git a/eslint.config.mjs b/eslint.config.mjs index 64a65b2a..ad8d2eef 100644 --- a/eslint.config.mjs +++ b/eslint.config.mjs @@ -2,6 +2,8 @@ import antfu from '@antfu/eslint-config' import harlanzw from 'eslint-plugin-harlanzw' export default antfu({ + // skilld sync writes .skills from skilld-dev/skilld. CI checks it with check:skills. + ignores: ['.skills/**'], rules: { 'vue/no-useless-v-bind': 'off', 'vue/attribute-hyphenation': 'off', diff --git a/layers/marketing/nuxt.config.ts b/layers/marketing/nuxt.config.ts index c9c2ba0f..6ac73f1f 100644 --- a/layers/marketing/nuxt.config.ts +++ b/layers/marketing/nuxt.config.ts @@ -11,5 +11,7 @@ export default defineNuxtConfig({ routeRules: { '/nuxt': { redirect: { to: '/frameworks/nuxt', statusCode: 301 } } as any, + // Agents guess /trending when they look for the trending board. + '/trending': { redirect: { to: '/skills/trending', statusCode: 301 } } as any, }, }) diff --git a/package.json b/package.json index ffe7d89a..18132105 100644 --- a/package.json +++ b/package.json @@ -48,7 +48,9 @@ "db:migrations:dev": "wrangler d1 migrations apply DB --local", "db:migrations:prod": "wrangler d1 migrations apply DB --remote", "checkin": "nuxt-checkin prepare && nuxt-checkin", - "demo:record": "tsx scripts/record-skill-demo.ts" + "demo:record": "tsx scripts/record-skill-demo.ts", + "sync:skills": "pnpm dlx skilld@3.6.0 sync --plain", + "check:skills": "pnpm dlx skilld@3.6.0 sync --check --plain" }, "dependencies": { "@comark/nuxt": "catalog:",