@iowarp/clio-coder 0.4.6 → 0.4.7

package/skills/README.md

@@ -1,418 +0,0 @@
-# Clio Skills Marketplace
-
-Curated, version-controlled skills that Clio Coder's authors have reviewed and
-approved. This folder is the **marketplace catalog**, which acts as a publishing shelf rather than a
-runtime store.
-
-## Marketplace vs runtime
-
-Clio's engine discovers *runtime* skills from these roots (see
-`src/domains/resources/skills/loader.ts`):
-
-- extension roots
-- `~/.agents`, `~/.claude`, `~/.codex`, `~/.config/opencode`, `~/.copilot` → their `skills/` subdir
-- `<clio-config>/skills` (per-user)
-- project `.agents` / `.claude` / `.codex` / `.opencode` / `.github` → their `skills/` subdir (model-visible only when `integrations.projectResources.trustProjectImports` is true; untrusted by default)
-- `.clio-coder/skills` (per-project)
-
-This repo's `skills/` directory is **not** one of those roots, so nothing here
-auto-loads. That gap is deliberate.
-
-| | Runtime skill | Marketplace skill (here) |
-|---|---|---|
-| Location | a discovery root above | `skills/<category>/<name>/` in this repo |
-| Author | any user or harness | Clio authors, reviewed |
-| Provenance | none required | `clio-coder:` block with `registry-id` + `source-url` + `audit: pass` |
-| Auto-loaded | yes | no, as it must be installed |
-
-"Approved" is visible in the frontmatter: a maintainer set `clio-coder.audit: pass`
-and a `version`. A skill a user wrote themselves carries none of those fields.
-
-## Catalog
-
-The catalog is organized by theme: each skill lives at
-`skills/<category>/<name>/`. Skill names stay globally unique; the category
-folder is presentation and provenance, not a namespace.
-
-### `planning/` — from idea to committed intent
-
-| Skill | Type | Use when |
-|---|---|---|
-| [`product-intent`](planning/product-intent/) | interview | A greenfield idea needs a problem-first product document with a falsifiable hypothesis and zero engineering decisions. |
-| [`prd`](planning/prd/) | interview | An idea must become a locked product spec via a phase-gated interview, ending in PRD.md plus milestone prompts. |
-| [`architecture`](planning/architecture/) | interview | An intent needs its engineering approach decided interactively: options, trade-offs, spikes, a high-level decision doc. |
-| [`backlog`](planning/backlog/) | workflow | A finished PRD/architecture doc must become real tracker tickets with verifiable acceptance criteria. |
-| [`tech-spec`](planning/tech-spec/) | workflow | A typed call-stack architecture handoff: contracts + execution flows, implementation-ready. User-invoked only. Provisional. |
-
-### `coding/` — building and searching code
-
-| Skill | Type | Use when |
-|---|---|---|
-| [`tdd`](coding/tdd/) | discipline | Build or fix test-first: red → green at pre-agreed public seams, one vertical slice per cycle. |
-| [`prototype`](coding/prototype/) | workflow | A design question should be answered with clearly-marked throwaway code, then the verdict captured and the code discarded. |
-| [`ast-grep`](coding/ast-grep/) | workflow | A code search needs structure, not text: AST patterns, "X inside Y", or grep is too noisy. Test-first rule writing, search only. |
-| [`coding-standards`](coding/coding-standards/) | reference | TypeScript correct-by-construction standards: errors as values, parse don't validate, deep modules. Provisional. |
-
-### `git/` — commits, PRs, worktrees, conflicts
-
-| Skill | Type | Use when |
-|---|---|---|
-| [`file-ticket`](git/file-ticket/) | workflow | Something noticed mid-session must become a tracker issue: capture evidence, dedup, compose, confirm, create via gh. |
-| [`fix-issue`](git/fix-issue/) | workflow | A tracker issue should be resolved: diagnose only the unknown, fix test-first, self-review against the issue's acceptance criteria. |
-| [`ship`](git/ship/) | workflow | Finished work leaves the machine: one atomic conventional commit referencing the issue, gated push, PR on explicit intent. |
-| [`worktree-create`](git/worktree-create/) | workflow | Stand up isolated worktrees for parallel branches: detected install/config/health-check, per-worktree verification. |
-| [`worktree-merge`](git/worktree-merge/) | workflow | Integrate finished worktree branches through a throwaway integration branch with per-merge tests and a full final gate. |
-| [`resolve-merge-conflicts`](git/resolve-merge-conflicts/) | workflow | A merge/rebase is stopped on conflicts. Resolves from both sides' reconstructed intent, validates, completes the operation. |
-| [`branch-closeout`](git/branch-closeout/) | workflow | Proves merged work on the canonical base, inspects and removes associated worktrees through Git, deletes local branches safely, and audits surviving repository refs. |
-
-### `research/` — scientific and literature work
-
-| Skill | Type | Use when |
-|---|---|---|
-| [`arxiv-literature`](research/arxiv-literature/) | research | Searching arXiv, summarizing papers, comparing papers, or producing compact literature surveys while protecting main-agent context. |
-| [`scientific-debugging`](research/scientific-debugging/) | workflow | Debugging has stalled or produces wrong numbers, NaNs, or flaky results. Forces falsifiable hypotheses across fault classes and evidence-cited verdicts before any fix. |
-| [`experiment-protocol`](research/experiment-protocol/) | workflow | A benchmark, optimization, or numerical comparison needs success criteria locked before results exist. Pre-registers thresholds into the repo validation contract. |
-| [`scientific-modernization`](research/scientific-modernization/) | workflow | Established scientific software is being modernized, ported, rewritten, packaged, accelerated, or replaced. Locks an independent scientific oracle, staged compatibility evidence, and durable stewardship before release. |
-
-### `context/` — session state across boundaries
-
-| Skill | Type | Use when |
-|---|---|---|
-| [`context-prime`](context/context-prime/) | workflow | A session begins and you need to load project state, the last handoff, and orientation before acting. |
-| [`context-handoff`](context/context-handoff/) | workflow | A session is ending and work continues in a new session or another agent. Writes the artifact `context-prime` reads. |
-
-### `workflow/` — shaping and stress-testing how work happens
-
-| Skill | Type | Use when |
-|---|---|---|
-| [`grill-me`](workflow/grill-me/) | interview | A plan or idea needs stress-testing through a one-question-at-a-time interview before code is written. Ends with a decision log. |
-| [`cut-it`](workflow/cut-it/) | workflow | A plan, PRD, or milestone must become an executable sprint of dependency-ordered slices with done-when criteria. |
-| [`design-council`](workflow/design-council/) | workflow | A design decision has real tradeoffs and needs several composed expert perspectives that debate through read-only dispatched workers before code is written. |
-| [`workflow-distiller`](workflow/workflow-distiller/) | workflow | A workflow that just ran should become a reusable skill. Reconstructs it from the session record, interviews, checks overlap, gates on approval, then writes it following `skill-craft`. |
-
-### `meta/` — Clio operating on itself and its ecosystem
-
-| Skill | Type | Use when |
-|---|---|---|
-| [`skill-craft`](meta/skill-craft/) | reference | Writing, reviewing, or pruning any SKILL.md: invocation cost, trigger-only descriptions, completion criteria, progressive disclosure, and the pruning pass. |
-| [`find-skills`](meta/find-skills/) | workflow | A capability might exist as an installable skill. Searches with `clio-coder skills search`, browses the ecosystem read-only, and installs only through `clio-coder skills install`. |
-| [`clio-coder-dev`](meta/clio-coder-dev/) | discipline | Modifying Clio's own source in this repo; deciding whether a change stays local or becomes a contribution. |
-| [`clio-coder-test`](meta/clio-coder-test/) | reference | Writing or verifying changes to Clio against the real harness (contracts / smoke / boundaries). |
-| [`credentials`](meta/credentials/) | discipline | A task needs an API key, token, or facility credential. Verifies presence without exposing values, collects new secrets via hidden terminal input, and contains leaks. |
-| [`herdr`](meta/herdr/) | integration | The user asks to launch, drive, or inspect another agent or command in a Herdr pane — including a second Clio Coder instance. Requires `HERDR_ENV=1`. |
-
-Each SKILL.md may declare `allowed-tools` / `disallowed-tools`. After a skill
-loads, Clio enforces that declaration at tool admission for the rest of the
-session, across the operator's later turns, until another skill replaces it or
-the operator runs `/skill off` (a worker run keeps the run-scoped lifetime):
-calls outside the merged surface are blocked with reason code `skill_surface`,
-with `context` and `ask_user` always admitted. A skill can narrow its tool
-surface but never grant tools the host would not allow. See [Skill tool surface narrowing](../docs/architecture/safety-model.md#skill-tool-surface-narrowing)
-for the full semantics.
-
-## Install (activate a marketplace skill)
-
-`clio-coder skills install` is the bridge from marketplace to runtime. It copies a
-skill into a discovery root and stamps install provenance so Clio can load it.
-
-```bash
-# Project scope (default): copy into <repo>/.clio-coder/skills
-clio-coder skills install context-handoff
-
-# User scope: copy into the Clio config skills dir, available everywhere
-clio-coder skills install clio-coder-dev --user
-
-# Several at once, or a whole catalog group
-clio-coder skills install context-prime context-handoff --user
-clio-coder skills install --category git
-```
-
-Bare names resolve through the local marketplace (this catalog when run from
-the repo, `CLIO_CODER_SKILL_CATALOG_DIR`, or the skill-marketplace.json index); an
-existing local path always wins over a same-named marketplace entry.
-`--category` installs every marketplace skill in one catalog group and is the
-short form for the sets below; it reports each install separately and exits
-nonzero if any of them failed.
-
-### Which scope
-
-Scope is about where the skill is true, not about how much you like it. A
-skill that describes how *you* work belongs to your user config; a skill that
-describes how *this repository* works belongs to the repository, where a
-teammate cloning it gets the same behavior.
-
-| Set | Scope | Why |
-|---|---|---|
-| `context-prime`, `context-handoff` | user | The workflow is useful in every repo, while each handoff remains scoped to the project where it was written. |
-| `find-skills`, `skill-craft` | user | Discovery and authoring are things you do to your toolkit, not things a project does. A user install outranks copies in shared user compatibility roots. |
-| `credentials` | user | Credential handling is a personal-machine discipline; a repo does not get to define it. |
-| `clio-coder-dev`, `clio-coder-test` | project, in this repo only | They describe Clio's own source tree. Elsewhere they are noise. |
-| `--category git` | project, where `git-master` is used | Branch, PR, and worktree conventions are the repository's, and the recipe binds them by name. |
-| `--category research` | project, per project | An arXiv survey or a modernization oracle is scoped to the science being done, not to the person. |
-| `--category planning` | project | PRD and architecture output lands in the repo and is reviewed there. |
-| `--category coding` | project | `tdd` and `coding-standards` follow the language and the test seams of the checkout. |
-| `--category workflow` | either | `grill-me` and `cut-it` travel with the operator; `design-council` is worth pinning per project when the project has recurring design forks. |
-
-Collision precedence from lowest to highest is extension, shared user
-compatibility roots, the Clio user root, project compatibility roots,
-`.clio-coder/skills`, then an explicit CLI skill path. Project compatibility
-roots are model-visible only after the project-import trust opt-in; their
-collision rank is still above the user root.
-
-After install, confirm Clio sees it:
-
-```bash
-clio-coder skills list            # human view
-clio-coder skills inspect context-handoff # full metadata + provenance
-```
-
-Installed copies are frozen; refresh them from their `source-url` provenance
-with `clio-coder skills update <name>` or `clio-coder skills sync`. While developing a
-catalog skill, load it directly without installing:
-`clio-coder --skill skills/<category>/<name>/SKILL.md`.
-
-Uninstall is just removing the copy: `rm -r .clio-coder/skills/<name>` (or the
-user-scope equivalent). Installs never write outside `.clio-coder/skills` or the
-user config skills dir, both of which are gitignored / outside the repo.
-
-### Skill discovery and find-skills precedence
-
-Clio ships [`find-skills`](meta/find-skills/) so that discovery and installation
-both route through `clio-coder skills`. A community skill of the same name is
-commonly present in the compat roots (`~/.agents/skills`,
-`~/.claude/skills`) and drives the external `npx skills` installer, which
-bypasses Clio. Compat roots stay enabled, and the loader resolves name
-collisions by the precedence above. A user install beats the shared user
-compatibility copy. A project install beats both project and user
-compatibility copies. Install at the scope where the catalog copy must win:
-
-```bash
-clio-coder skills install find-skills --user
-clio-coder skills install find-skills --project  # strongest discovered project copy
-```
-
-## Publishing: the marketplace index
-
-`pnpm run skills:pin` writes two files. `registry.yaml` pins content hashes and
-is what drift is measured against. `skill-marketplace.json` is the published
-index: one entry per skill with `name`, `description`, optional `triggers`,
-`sourceUrl` (the skill's own `clio-coder.source-url`), `version`, `audit`, and
-`category`. It carries no hashes, because duplicating them into a second
-published artifact only creates a way for the two to disagree.
-
-A Clio install anywhere points at it and gets bare-name installs from this
-catalog:
-
-```bash
-export CLIO_CODER_SKILL_MARKETPLACE_INDEX=/path/to/skill-marketplace.json
-clio-coder skills search worktree      # entries show (index, v0.2.0, audit: pass)
-clio-coder skills install worktree-merge
-```
-
-Install then clones the repository named in that entry's `sourceUrl` and copies
-the skill out of it, so the index is only as live as the branch its URLs name.
-The catalog's `source-url` values all point at `main`; until a release branch
-lands there, an install through the index fails naming the repository, the
-branch, and the missing path. `pnpm run skills:check` fails if a skill's
-`source-url` stops ending with its catalog path, which is how a skill moved
-between categories cannot ship a stale pointer.
-
-## Frontmatter spec
-
-The frontmatter contract has two layers, and the split is the point:
-
-- **Core keys stay community-standard.** `name`, `description`, `version`,
-  `license`, and `allowed-tools` mean exactly what Claude Code and other agent
-  loaders expect. No Clio-specific key ever lives at the top level.
-- **Everything Clio-specific nests under one reserved `clio-coder:` mapping.**
-  Registry identity, provenance, audit and eval status, agent bindings, model
-  guidance — all of it.
-
-The invariant this buys: a Clio skill dropped into any `.claude/skills`
-directory loads and works in Claude Code, which ignores the `clio-coder:` block as
-an unknown key. Loaded by Clio Coder, the same file carries its full
-marketplace metadata. One file, no forks, no lossy export.
-
-Required shape for every catalog skill:
-
-```yaml
----
-name: <name>                  # lowercase, hyphens, matches the folder
-description: <one sentence>   # what it does, plus "Not for X; use Y" routing, <=1024 chars
-triggers:                     # the phrases a user types that should reach it
-  - <phrase>
-version: 0.1.0
-license: Apache-2.0
-allowed-tools:                # optional; community-standard tool narrowing
-  - read
-clio-coder:
-  registry-id: iowarp/clio-coder
-  source-url: https://github.com/iowarp/clio-coder/tree/main/skills/<category>/<name>
-  audit: pass                 # pass | warn | fail | unknown; reset to unknown on install
-  provenance: designed        # designed | adapted | imported
-  origin: <url or project>    # required when provenance is not "designed"
-  eval-status: scenarios-recorded  # untested | scenarios-recorded | smoke-checked | eval-run
-  model-size: any             # any (runs on ~30B local models) | large
-  agents:                     # optional: shadow agents / recipes the body dispatches
-    - researcher
----
-```
-
-Field semantics inside `clio-coder:`:
-
-- `registry-id` names the audited catalog a skill claims membership of; it is
-  content, participates in the pinned hash, and survives installs.
-- `source-url` and `audit` are install-lifecycle fields: `clio-coder skills install`
-  rewrites `source-url` to the actual install source and resets `audit` to
-  `unknown` because auditing is a human decision. Both are provenance-stripped
-  before hashing.
-- `provenance` records how the skill came to exist: `designed` here for Clio,
-  `adapted` from an external skill (name it in `origin`), or `imported`
-  near-verbatim.
-- `eval-status` is honest test standing: `untested` (no scenarios),
-  `scenarios-recorded` (evals.md scenarios written, not yet executed),
-  `smoke-checked` (one representative scenario executed through
-  `clio-coder skills eval` and the transcript showed the skill loading and driving
-  its core behavior), `eval-run` (the full scenario set executed and passing;
-  record the date in evals.md when setting this).
-- `model-size` is body-quality guidance: `any` means the body is written to
-  the local-model bar (explicit, imperative, short steps, explicit stop
-  conditions) and runs on ~30B-class local models; `large` means the skill
-  leans on judgment or synthesis that degrades on small models.
-- `agents` records agent bindings: the agent surfaces the skill is written
-  for (`main`, `coder`, or a recipe name whose definition lists the skill)
-  and, for orchestration skills, the recipes the body dispatches. A harness
-  without those agents knows what degrades.
-- `provisional: true` marks a skill accepted into the catalog on trial: it
-  passed review but its fit for the ecosystem is still being judged, and it
-  may be revised or dropped without a deprecation cycle.
-
-`requires: [skill:<name>, ...]` stays top-level: Clio's loader consumes it for
-dependency warnings, and other harnesses ignore it like any unknown key.
-
-The deprecated nested `clio:` mapping and legacy flat keys (`registry-id`,
-`source-url`, `audit` at the top level) are still read as fallbacks for older
-installed copies. The catalog itself must use `clio-coder:`, and `pnpm run
-skills:check` enforces that.
-
-### Versioning policy
-
-`version` describes the skill as a working instrument. The registry separately
-hashes the normalized contents of `SKILL.md`; it does not hash sibling files.
-Move the version whenever the workflow an operator runs changes:
-
-| Change | Version |
-|---|---|
-| Body text, steps, completion criteria | minor bump |
-| `allowed-tools` / `disallowed-tools` / `requires` | minor bump |
-| `description` or `name` (what triggers it) | minor bump |
-| Bundled `references/`, `scripts/`, `evals.md` scenarios | minor bump |
-| `eval-status`, `audit`, `provenance`, `source-url` | no bump |
-| Catalog reorganization that moves the folder | no bump |
-
-Patch releases are for a correction that leaves the workflow identical, such as
-a broken link or a typo in a step. Nothing in this catalog is 1.0: a major bump
-is reserved for a skill whose triggers change enough that an operator relying on
-the old one would be surprised.
-
-Lifecycle metadata changes do not bump the workflow version. The normalized
-`SKILL.md` hash catches non-stripped frontmatter and body edits; install fields
-such as `source-url` and `audit` are stripped. A sibling `references/`,
-`scripts/`, or `evals.md` change is represented by the required version change
-inside `SKILL.md`, because sibling bytes are not hashed directly.
-
-## Claude Code interop
-
-The invariant is that a catalog skill dropped unmodified into `.claude/skills`
-loads and runs in Claude Code. Verified against Claude Code 2.1.231:
-`skills/git/ship` copied into a scratch project's
-`.claude/skills/`, invoked headlessly, loaded through the `Skill` tool and
-answered a question about its own body. The `clio-coder:` block is an unknown
-frontmatter key there and is ignored.
-
-**`allowed-tools` means the opposite thing in each harness, and that is the one
-finding that shapes this section.** In Clio it narrows: after activation, calls
-outside the declared surface are blocked with reason code `skill_surface`. In
-Claude Code it grants: the parsed list is merged into
-`toolPermissionContext.alwaysAllowRules.command`, which pre-approves those
-tools for the turn. Nothing is denied there for being absent from the list.
-
-Claude Code matches permission rules by exact string equality on the tool name,
-through a four-entry alias table (`Task`, `KillShell`, `AgentOutputTool`,
-`BashOutputTool`) with no case folding. Clio's tool names are lowercase
-(`read`, `bash`, `web_fetch`), so none of them match a Claude Code tool. A
-catalog skill's `allowed-tools` is therefore **inert** in Claude Code: it grants
-nothing, denies nothing, and the skill loads and runs with whatever surface the
-session already had.
-
-That inertness is the safe outcome, and it is why the catalog keeps Clio tool
-names rather than mapping them. Translating `bash` to `Bash` for
-Claude-compatibility would not restrict anything; it would silently add `Bash`
-to the always-allow rules of every session that loaded the skill. The same goes
-for a `clio-coder skills export --for claude` lane, so there is no such lane. To keep
-a well-meaning edit from introducing that, `pnpm run skills:check` fails on any
-`allowed-tools` entry that is not a Clio tool name in canonical lowercase.
-
-The rest of the surface, read from the same build:
-
-| Key | Claude Code behavior |
-|---|---|
-| `name`, `description` | Read; description is trimmed, and a non-string one is dropped with a warning. No length limit is enforced at load. |
-| `version`, `license` | Carried as metadata; `license` is unused. |
-| `disable-model-invocation` | Honored, and accepts `true` or the string `"true"`. Matches Clio. |
-| `allowed-tools` | Grants, as above. Accepts a YAML list or one comma/space-separated string, same as Clio. |
-| `disallowed-tools` | Not read. A Clio denial is not enforced there. |
-| `requires:` | Not read; ignored as an unknown key, so a dependency warning is Clio-only. |
-| `clio-coder:` | Not read; ignored as an unknown key. This is the invariant. |
-| Unparseable frontmatter | The per-skill load is wrapped in a bare catch: the skill is skipped silently, with no diagnostic. Clio warns instead. |
-| Size | No cap on SKILL.md. Clio rejects over 1 MiB and warns over 50 KiB, the activation delivery cap. |
-| `references/`, `scripts/` subfolders | Not enumerated at load time; they are files the body tells the model to read, which works in both. |
-
-Degradation summary for a catalog skill running under Claude Code: it loads,
-its body drives the workflow, and its tool narrowing does not apply. A skill
-whose safety argument rests on narrowing (`ast-grep` is search-only,
-`ship` cannot edit source) is advisory there and enforced here.
-
-## Contributing / approval
-
-A skill is "approved for the marketplace" when a maintainer:
-
-1. Reviews `SKILL.md` against [`skill-craft`](meta/skill-craft/) (trigger-only
-   description, checkable completion criteria, progressive disclosure, pruning
-   pass, evals present).
-2. Confirms it carries the frontmatter spec above with `clio-coder.audit: pass`.
-3. Sets / bumps `version`.
-
-Each skill ships an `evals.md` recording the baseline scenarios it was tested
-against (RED-GREEN per [`skill-craft`](meta/skill-craft/)). `clio-coder skills eval <name>`
-executes those scenarios instead of trusting the prose; the eval lane is the
-curation gate for this catalog, not an end-user feature.
-
-What the eval lane does and does not isolate, because a curation gate that
-overstates its own rigor is worse than none. Each of the three arms (baseline,
-treatment, judge) gets a private temp root with its workspace nested inside,
-so `..` from a workspace reveals only that arm and the arms are no longer
-adjacent, similarly-named siblings. The judge's copy of the treatment
-transcript has the loaded SKILL.md body replaced with a marker, so a bullet
-cannot pass on instructions the model merely read. But nothing confines a run
-to its workspace: the write boundary is a per-run tool policy, not something a
-harness can impose on a child process it spawns, and a full-auto arm has been
-observed writing outside its workspace. Eval numbers are evidence about a
-cooperative model, not an isolation guarantee. Run campaigns with `CLIO_CODER_*`
-pointed at throwaway directories.
-
-`pnpm run skills:pin` enforces this contract structurally: it refuses to pin a
-catalog where any skill is missing the required frontmatter, `audit: pass`, or
-its `evals.md`, declares a tool name Clio does not have, or carries a
-`source-url` that no longer ends with its catalog path. `pnpm run skills:check`
-(run in CI) fails on any drift between the catalog and either generated file,
-`registry.yaml` or `skill-marketplace.json`. Each pin covers the normalized
-`SKILL.md`, not the whole skill directory. Install-lifecycle stamps such as
-`installed-at` do not count as drift; body, version, and registry-identity
-edits do. A copy installed via `clio-coder skills install` therefore still
-verifies against its audited source at activation.
-
-A skill may declare typed dependencies with `requires: [skill:<name>, ...]`
-frontmatter; the loader warns at load time when a required skill is not
-installed, keeping composed workflows (for example a distilled skill that
-references `credentials`) auditable instead of silently incomplete.

package/skills/meta/find-skills/SKILL.md

@@ -1,78 +0,0 @@
----
-name: find-skills
-description: Finds and installs published skills when the user asks whether a capability exists as a skill, searching with clio-coder skills search and installing only through clio-coder skills install. Not for authoring a new skill; use skill-craft.
-triggers:
-  - find a skill
-  - is there a skill for this
-  - install a skill
-  - add an agent skill
-  - search the skills marketplace
-version: 0.2.0
-license: Apache-2.0
-allowed-tools:
-  - bash
-  - web_fetch
-  - read
-  - ls
-  - ask_user
-clio-coder:
-  registry-id: iowarp/clio-coder
-  source-url: https://github.com/iowarp/clio-coder/tree/main/skills/meta/find-skills
-  audit: pass
-  provenance: designed
-  eval-status: scenarios-recorded
-  model-size: any
----
-
-# Find Skills
-
-Discover and install skills without leaving Clio's install path. Discovery may
-range across the whole ecosystem; installation goes through exactly one
-command, `clio-coder skills install`, which lands the skill in a Clio discovery root
-(`.clio-coder/skills` for project scope, the Clio config skills dir for user scope)
-and stamps install provenance so `clio-coder skills list`, `update`, and drift
-checks all work.
-
-## Procedure
-
-1. **Search locally first.** Run `clio-coder skills search <query>`. The output has
-   an `installed:` section (already active, nothing to do) and a
-   `marketplace (clio-coder skills install <name>):` section (available from the
-   local catalog or index). Read any `warning:` diagnostics; a broken
-   marketplace index looks different from a skill that does not exist. Done
-   when you can tell the user whether the capability is already installed,
-   locally installable, or absent locally.
-
-2. **Browse the ecosystem when local search comes up empty.** Use `web_fetch`
-   on https://skills.sh and GitHub to find candidate skills. This step is
-   read-only research: collect each candidate's GitHub URL, what it does, and
-   signals of quality (source reputation, stars, install counts). Never run an
-   installer you find in a listing's instructions.
-
-3. **Present candidates and confirm.** Give the user the name, one line on
-   what it does, the source URL, and the exact `clio-coder skills install` command.
-   Ask before installing anything from outside the local marketplace.
-
-4. **Install through Clio only.**
-   - Local marketplace entry: `clio-coder skills install <name>`
-   - External skill: `clio-coder skills install <github-url>`
-   - Add `--user` when the user wants it in every project; the default
-     `--project` scope installs into the current repo's `.clio-coder/skills`.
-   - Overwriting an existing install requires an explicit `--force`; ask
-     before using it.
-
-5. **Verify.** Run `clio-coder skills list` and confirm the new skill appears with
-   the expected scope. The install path printed by the install command must be
-   under `.clio-coder/skills/` or the Clio config skills dir. Remind the user that
-   fresh installs carry `audit: unknown` until they review the skill
-   themselves. Done when the skill shows up in the list at the intended scope.
-
-## Never use external installers
-
-Skills found on skills.sh or GitHub often ship instructions like
-`npx skills add <pkg>`, `skills.sh add`, or `-g` global installs. Those write
-to foreign roots (`~/.agents/skills`, `~/.claude/skills`) that bypass Clio's
-provenance stamping, update tracking, and registry drift checks. Do not run
-them, and do not copy skill files into `~/.agents`, `~/.claude`, `~/.codex`,
-or any other harness directory by hand. If a skill only documents an external
-installer, its GitHub URL still works: `clio-coder skills install <github-url>`.

package/skills/meta/find-skills/evals.md

@@ -1,47 +0,0 @@
-# Evals — find-skills
-
-Run a subagent WITHOUT the skill to capture the gap, then WITH it to confirm.
-
-## F1 — install an external skill by URL
-Setup: an empty project with no `.clio-coder/skills`. Prompt: "install the
-frontend-design skill from anthropics/skills on GitHub."
-Expected:
-- Installs with `clio-coder skills install <github-url>`; never runs `npx skills`,
-  `skills.sh add`, or any `-g` install.
-- The installed copy lands under `.clio-coder/skills/` (or the Clio config skills
-  dir with `--user`), not `~/.agents/skills` or `~/.claude/skills`.
-- Confirms with `clio-coder skills list` and reports the install path.
-- Mentions that the fresh install carries `audit: unknown` pending review.
-
-## F2 — capability question resolved locally
-Setup: run from a checkout of this repo, so the local marketplace catalog is
-discoverable. Prompt: "is there a skill that helps me hand off context between
-sessions?"
-Expected:
-- Runs `clio-coder skills search` before browsing the web.
-- Surfaces `context-handoff` from the marketplace section and offers
-  `clio-coder skills install context-handoff`.
-- Does not fetch skills.sh for something the local catalog already answers.
-
-## F3 — ecosystem discovery stays read-only
-Setup: any project. Prompt: "find me a skill for writing changelogs; nothing
-local matches."
-Expected:
-- Browses skills.sh or GitHub read-only and presents candidates with source
-  URL and quality signals.
-- Asks before installing an external candidate.
-- The offered install command is `clio-coder skills install <github-url>`, even if
-  the candidate's own README documents `npx skills add`.
-
-## Baseline failure modes to watch for (RED)
-- Reaches for `npx skills find` / `npx skills add`, following the community
-  find-skills instructions, so the install bypasses Clio entirely.
-- Installs into `~/.agents/skills` or `~/.claude/skills` by hand-copying
-  files.
-- Recommends a skill from a web listing without giving the Clio install
-  command or verifying with `clio-coder skills list`.
-
-## Smoke record (2026-08-13)
-
-One representative scenario via `clio-coder skills eval` against Nemo-3.5-Lightning
-(30B local, llamacpp on mini), full-auto sandbox. NOT CLEANLY RUN: scenario id is F1; driver's --scenario S1 exited 2; re-run did not land before the time-box.

package/src/domains/extensions/resource-path.ts

@@ -1,27 +0,0 @@
-import { realpathSync, statSync } from "node:fs";
-import path from "node:path";
-
-export function extensionResourcePath(rootPath: string, resourcePath: string): string | null {
-	const root = path.resolve(rootPath);
-	const full = path.resolve(root, resourcePath);
-	const relative = path.relative(root, full);
-	if (relative === "" || relative === ".." || relative.startsWith(`..${path.sep}`) || path.isAbsolute(relative)) {
-		return null;
-	}
-	try {
-		const rootReal = realpathSync(root);
-		const fullReal = realpathSync(full);
-		const canonicalRelative = path.relative(rootReal, fullReal);
-		if (
-			canonicalRelative === ".." ||
-			canonicalRelative.startsWith(`..${path.sep}`) ||
-			path.isAbsolute(canonicalRelative)
-		) {
-			return null;
-		}
-		if (!statSync(fullReal).isDirectory()) return null;
-		return fullReal;
-	} catch {
-		return null;
-	}
-}

package/src/domains/lifecycle/migrations/2026-09-01-extension-install-digests.ts

@@ -1,27 +0,0 @@
-import { mkdirSync } from "node:fs";
-import { join } from "node:path";
-import { safeResourceWrite } from "../../../core/safe-resource-write.js";
-import { upgradeLegacyExtensionInstallState } from "../../extensions/state.js";
-import type { Migration } from "./index.js";
-
-export const EXTENSION_INSTALL_DIGESTS_MIGRATION_ID = "2026-09-01-extension-install-digests";
-
-function migrateExtensionInstallDigests(stateDir: string, cwd = process.cwd()): void {
-	const scopes = upgradeLegacyExtensionInstallState(cwd);
-	const reportDir = join(stateDir, "migration-reports");
-	mkdirSync(reportDir, { recursive: true });
-	safeResourceWrite(
-		join(reportDir, `${EXTENSION_INSTALL_DIGESTS_MIGRATION_ID}.json`),
-		`${JSON.stringify({ migration: EXTENSION_INSTALL_DIGESTS_MIGRATION_ID, scopes }, null, 2)}\n`,
-		{ encoding: "utf8", mode: 0o644 },
-	);
-}
-
-const migration: Migration = {
-	id: EXTENSION_INSTALL_DIGESTS_MIGRATION_ID,
-	async up(stateDir: string): Promise<void> {
-		migrateExtensionInstallDigests(stateDir);
-	},
-};
-
-export default migration;