Add effect skill layered on Effect's own skills

CLAUDE.md

@@ -395,6 +395,28 @@ enough, so the next breakage is a prompt to check.
   in the locked input, then the file at that rev) or against
   `~/.agents/skills/<name>/` after a switch, and give the skill a fallback
   for anything that can lag
+- **For a library, look inside the package before writing a skill for it.**
+  Effect v4 ships `AGENTS.md` and `ai-docs/` in its npm tarball, and the
+  Effect team's own `effect-ts` skill is only a pointer to them. A local API
+  reference would restate that content, and it would go stale at each
+  release. The repo's `effect` skill therefore carries what the package
+  cannot: a gate on the *installed* major version (the v3 tarball ships no
+  agent docs, and `effect-ts` starts with `pnpm add effect@latest`, which
+  since v4 GA on 2026-10-01 is an unrequested major upgrade in a v3 project;
+  during the RC the same step said `effect@rc`), plus Alyssa's Rust
+  mapping. Get version-specific claims from a typecheck against the real
+  package, not from memory: typechecking effect-playground against
+  4.0.0-rc.117 found `Schema.Date`, a name that v4 keeps with a different
+  meaning, and a v4 name written from memory (`Schema.TaggedErrorClass`)
+  that did not exist. A source you trust needs the same check. The
+  playground's own comment (a `Data.TaggedError` field cannot be named
+  `cause`) went into the skill as a rule, and it was false: the renamed
+  field typechecks and passes the lesson's tests. Where the guides ship
+  also differs by project. Topcoat embeds its guides in the published crates
+  (`~/.cargo/registry/src/*/topcoat-<ver>/docs/`), but its `AGENTS.md`
+  index exists only in the repo, and `main` drifts from the release. The
+  `topcoat` skill reads the crate at the `Cargo.lock` version and the index
+  at the matching tag
 
 ### When nixpkgs lags: prefer the vendor's own Nix repo over NUR
 
@@ -868,6 +890,8 @@ This document should evolve as patterns emerge. When you:
 
 ---
 *Last updated: 2026-09-29 - The scheduled flake update broke on `nix/build-skill` not existing: nix-skills was renamed to agents.nix, history rewritten and restructured. `lib/skills-sh.nix` now goes through upstream's public overlay, which the restructure made cheap (measured), instead of the internals it used to avoid a then-18s eval; supabase-postgres-best-practices is pinned by hand because the index dropped its repo*
+*Last updated: 2026-09-22 - Added the `topcoat` skill (tokio-rs/topcoat, with the Effect <-> Topcoat pairing), pinned Rhys Sullivan's `effect-client-wrapper`, and reviewed create-epoch-app; corrected a `cause`-field rule the `effect` skill had copied unverified from effect-playground*
+*Last updated: 2026-09-22 - Added the `effect` skill as a layer over the Effect team's pinned `effect-ts` / `effect-v3-to-v4` skills, and recorded the lesson: check whether a library ships its own agent docs in the package (Effect v4 does, v3 does not), gate on the installed version, and verify v3/v4 claims by typechecking against the real package*
 *Last updated: 2026-09-21 - Ghost (#56): ghost.build is shutting down, so venari now runs a server for its OpenAPI contract from the alycda/ghost fork, with the CLI packaged from that fork and driven by an env-setting wrapper; recorded the two client-side assumptions (`tsdb` dbname, viper's empty-env handling) that the "no CLI patch needed" plan missed*
 *Last updated: 2026-09-21 - Added "prebuilt binaries in a persisted `$HOME` are image-scoped state" to Tools Nix Can't Fully Manage, after a rustup toolchain in the devhome volume survived an image rebuild and left `cargo` erroring ENOENT for a loader that no longer existed — with the corollary that an activation step guarded on "is it installed" can never repair state that went bad in place (#80)*
 *Last updated: 2026-09-16 - Verified inspect against a real binary and found its declared install route could never have worked: the ataraxy-labs/tap formula pins a checksum upstream invalidated by moving the v0.1.1 tag, so the brew fails and would abort activation. Replaced it with `lib/inspect.nix` (release binary, tart-style). Two lessons, both already in the tap write-up and both nearly repeated: a tap's risk is its maintenance, so check the formula's age and hash before declaring it, not after; and a prebuilt binary that runs on *this* machine proves little — this one linked Homebrew's openssl by absolute path, so `otool -L` is part of verifying any fetched macOS binary*

home-manager/modules/tools/agent-skills.nix

@@ -36,6 +36,11 @@
 #   brag-doc              - promo-packet impact entries from raw work notes
 #   cf-now                - private file sharing from Cloudflare R2 (pre-signed URLs)
 #   commit-craft          - commit-message craft + jj describe/push workflow
+#   effect                - Effect (TypeScript) with a v3/v4 version gate and
+#                           the effect-playground Rust mapping; carries no v4
+#                           API text, defers to the AGENTS.md the v4 package
+#                           ships and to the external effect-ts /
+#                           effect-v3-to-v4 skills
 #   entity-level-git      - Ataraxy Labs stack: sem (entity diff/blame/impact),
 #                           weave (semantic merge driver), inspect (review triage)
 #   failure-doc           - failures as deliberate-learning records
@@ -50,6 +55,10 @@
 #                           surfaces; carries no rule text, delegates to the
 #                           external asd-ste100-skill and reads CONCEPTS.md as
 #                           the project's technical-name dictionary
+#   topcoat               - tokio-rs/topcoat (server-rendered Rust web apps):
+#                           reads the guides shipped in the crates at the
+#                           locked version, the two contracts the compiler
+#                           does not check, and the Effect <-> Topcoat pairing
 #
 # One of them is vendored rather than authored:
 #   hackmd-cli - upstream's own skill, extracted from the hackmd-cli.skill zip
@@ -90,6 +99,7 @@ let
     "brag-doc"
     "cf-now"
     "commit-craft"
+    "effect"
     "entity-level-git"
     "failure-doc"
     "hackmd-cli"
@@ -98,10 +108,14 @@ let
     "jujutsu"
     "power-of-ten"
     "ste100"
+    "topcoat"
   ];
 
   externalSkills = {
     asd-ste100-skill = pkgs.skills-sh.asd-ste100-skill;
+    effect-client-wrapper = pkgs.skills-sh.effect-client-wrapper;
+    effect-ts = pkgs.skills-sh.effect-ts;
+    effect-v3-to-v4 = pkgs.skills-sh.effect-v3-to-v4;
     here-now = pkgs.skills-sh.here-now;
     supabase-postgres-best-practices = pkgs.skills-sh.supabase-postgres-best-practices;
   };

lib/skills-sh.nix

@@ -26,6 +26,14 @@
 nix-skills: final: prev:
 let
   github = (nix-skills.overlays.default final prev).agent-skills.github;
+
+  # effect-ts/skills, pinned ahead of the index; see effect-ts below.
+  effect-skills = final.fetchFromGitHub {
+    owner = "effect-ts";
+    repo = "skills";
+    rev = "155c50c911f9c99c294ef8a4461981c5bbe6453e"; # 2026-10-09
+    hash = "sha256-GSmGLOQSp4taxckrg7vfMTD/mbkfBYjv7oBsvDJdyck=";
+  };
 in
 {
   skills-sh = {
@@ -63,6 +71,48 @@ in
       name = "asd-ste100-skill";
     };
 
+    # https://www.skills.sh/effect-ts/skills
+    # The Effect team's own skills. Both are deliberately thin: `effect-ts`
+    # tells an agent to read node_modules/effect/AGENTS.md, which the v4 npm
+    # tarball ships alongside ai-docs/ (the v3 tarball ships neither), and
+    # `effect-v3-to-v4` drives a migration from the generated
+    # migration/v3-to-v4.md in Effect-TS/effect. The repo's `effect` skill
+    # (tools/agents/skills/effect) layers on both: a version gate, because
+    # `effect-ts` step 1 is `pnpm add effect@latest`, and in a v3 project that
+    # is an unrequested major upgrade; and the Rust mapping from
+    # effect-playground. effect-v3-to-v4 sets disable-model-invocation, so it
+    # only runs when invoked by name.
+    #
+    # Pinned here by hand, ahead of the index. agents.nix 0b4d80e still has
+    # 2309e6f, written while v4 was a release candidate: its `effect-ts` says
+    # `pnpm add effect@rc`, which now installs 4.0.0-rc.118, older than the
+    # stable 4.0.x on `latest`; and its `effect-v3-to-v4` sends imports to
+    # `effect/unstable/*` paths that v4 GA removed with no compatibility
+    # exports. 155c50c ("align Effect skills with v4 GA", 2026-10-09) fixes
+    # both. One fetch serves both skills, so they cannot drift apart. When
+    # the index reaches 155c50c or later, switch back to
+    # github.effect-ts.skills.<name> and delete the pin. Until then
+    # `nix flake update nix-skills` does not move it; bump rev + hash by hand.
+    # The hash was computed without nix (a NAR serialization of `git archive
+    # <rev>`), a method that reproduced the index's hash for 2309e6f and the
+    # supabase pin below exactly; `nix flake prefetch
+    # github:effect-ts/skills/<rev>` is the normal way.
+    #
+    # Subdirectories, no builder: neither skill has symlinks, and each
+    # SKILL.md name already matches its deploy directory.
+    effect-ts = "${effect-skills}/skills/effect-ts";
+    effect-v3-to-v4 = "${effect-skills}/skills/effect-v3-to-v4";
+
+    # https://www.skills.sh/rhyssullivan/skills/effect-client-wrapper
+    # Wrap a Promise-based SDK as an Effect service behind one `use(fn)` that
+    # maps rejections to a tagged error and opens a span. By the author of
+    # create-epoch-app. Its code is Effect v3 (Context.Tag, a static Default
+    # layer, Schedule.intersect); the repo's `effect` skill says to keep the
+    # pattern and translate the code on v4 rather than copy it. From
+    # rhyssullivan/skills (indexed at ab3a455), not the older standalone
+    # rhyssullivan/effect-client-wrapper-skill repo the index also carries.
+    effect-client-wrapper = github.rhyssullivan.skills.effect-client-wrapper;
+
     # https://www.skills.sh/supabase/agent-skills/supabase-postgres-best-practices
     # Postgres performance/schema/RLS guidance across 8 priority categories.
     #