[alycda]

Effect v4 is at 4.0.0-rc.117 and npm latest is still 3.22.2. The v4
npm tarball ships AGENTS.md and ai-docs/, and the Effect team's
effect-ts/skills repo is already in the pinned nix-skills index.
Its effect-ts skill only points at that AGENTS.md. So this follows
the ste100 layer-not-fork pattern: pin the upstream skills and write a
thin local skill that holds only what upstream lacks.

What the layer adds:

• A gate on the installed major version. v3 code and v4 code do not
  compile against each other, and the v3 tarball ships no agent docs.
  Upstream effect-ts starts with pnpm add effect@rc, which in a v3
  project (effect-playground is one) is an unrequested major upgrade.
• The effect-playground Rust translation table, with a v4 column.
• The v3/v4 traps found by typechecking effect-playground against
  rc.117: Schema.Date keeps its name with a different meaning
  (v3 string->Date is now DateFromString, and v4 Schema.Date rejects
  the string at runtime); Schedule.intersect -> Schedule.max takes an
  array and cannot be piped; Cause guards moved to cause.reasons; and
  the misleading TS2379 "add undefined" cascade under
  exactOptionalPropertyTypes.

Each v4 entry was resolved against migration/v3-to-v4.md on
Effect-TS/effect main. The entries marked "checked" were also
typechecked and run against rc.117, including a v4 port of lesson
06's backoff (5 attempts transient, 1 permanent, same as v3). One name
written from memory, Schema.TaggedErrorClass, turned out not to exist.
That is why CLAUDE.md now says to verify version claims with a
typecheck against the real package.

Specific changes:

• lib/skills-sh.nix: pin effect-ts and effect-v3-to-v4
  (effect-ts/skills @ 2309e6f, which is also upstream HEAD)
• home-manager/modules/tools/agent-skills.nix: deploy both, plus the
  repo skill effect
• tools/agents/skills/effect/SKILL.md: the layer
• CLAUDE.md: "look inside the package before writing a skill for a
  library" lesson

Not verified here: this sandbox has no nix, so statix, deadnix and
flake evaluation are left to CI.

Co-Authored-By: Claude Opus 5.5 [email protected]
Claude-Session: https://claude.ai/code/session_01Tw8tuRUyKtkcjmN4upeawF

[github-actions]

⊕ Entity-level changes

CLAUDE.md

Status	Type	Name
Δ	heading	External agent skills (lib/skills-sh.nix)
Δ	heading	Meta: Updating This Document

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

Status	Type	Name
~	orphan	module-level
Δ	binding	repoSkills
Δ	binding	externalSkills

lib/skills-sh.nix

Status	Type	Name
+	orphan	module-level
+	binding	effect-skills
Δ	binding	skills-sh

tools/agents/skills/effect/SKILL.md

Status	Type	Name
+	preamble	(preamble)
+	heading	Effect
+	heading	Step 0: find the installed version
+	heading	Rust translation
+	heading	v3 → v4 traps that a rename table hides
+	heading	Writing rules for both versions
+	heading	Verify
+	heading	Hand-offs
+	heading	Reference projects, and what not to take from them

tools/agents/skills/topcoat/SKILL.md

Status	Type	Name
+	preamble	(preamble)
+	heading	Topcoat
+	heading	Step 0: version and docs
+	heading	Contracts the compiler does not check
+	heading	Coming from Effect: the pairing
+	heading	Tooling
+	heading	Unsafe
+	heading	Hand-offs

Summary: 19 added, 6 modified across 5 files (1 added orphan, 1 modified orphan)

_{functions and classes, not lines · sem}