{"id":"c8ba1c58-fac2-4c19-a619-b9c84a731dd4","shortId":"psqEYc","kind":"skill","title":"effect-ts","tagline":"Effect-TS (Effect) comprehensive development guide for TypeScript. Use when building, debugging, reviewing, or generating Effect code. Covers typed error modeling (expected errors vs defects), structured concurrency (fibers), dependency injection (ServiceMap/Context + Layers), re","description":"# Effect-TS\n\nEffect is a TypeScript library for building production-grade software with typed errors, structured concurrency, dependency injection, and built-in observability.\n\n## Version Detection\n\nBefore writing Effect code, detect which version the user is on:\n\n```bash\n# Check installed version\ncat package.json | grep '\"effect\"'\n```\n\n- **v3.x** (stable, most production codebases): `Context.Tag`, `Effect.catchAll`, `Effect.fork`, `Data.TaggedError`\n- **v4.x** (beta, Feb 2026+): `ServiceMap.Service`, `Effect.catch`, `Effect.forkChild`, `Schema.TaggedErrorClass`\n\nIf the version is unclear, ask the user. Default to v3 patterns for existing codebases, v4 for new projects.\n\n## Primary Documentation Sources\n\n- https://effect.website/docs (v3 stable docs)\n- https://effect.website/llms.txt (LLM topic index)\n- https://effect.website/llms-full.txt (full docs for large context)\n- https://tim-smart.github.io/effect-io-ai/ (concise API list)\n- https://github.com/Effect-TS/effect-smol (v4 source + migration guides)\n- https://github.com/Effect-TS/effect-smol/blob/main/LLMS.md (v4 LLM guide)\n\n## AI Guardrails: Critical Corrections\n\nLLM outputs frequently contain incorrect Effect APIs. Verify every API against the reference docs before using it.\n\n**Common hallucinations (both versions):**\n\n| Wrong (AI often generates)                   | Correct                                                       |\n|----------------------------------------------|---------------------------------------------------------------|\n| `Effect.cachedWithTTL(...)`                  | `Cache.make({ capacity, timeToLive, lookup })`                |\n| `Effect.cachedInvalidateWithTTL(...)`        | `cache.invalidate(key)` / `cache.invalidateAll()`             |\n| `Effect.mapError(effect, fn)`                | `Effect.mapError(fn)` in pipe, or use `Effect.catchTag`       |\n| `import { Schema } from \"@effect/schema\"`    | `import { Schema } from \"effect\"` (v3.10+ and all v4)         |\n| `import { JSONSchema } from \"@effect/schema\"`| `import { JSONSchema } from \"effect\"` (v3.10+)                |\n| JSON Schema Draft 2020-12                    | Effect Schema generates **Draft-07**                          |\n| \"thread-local storage\"                       | \"fiber-local storage\" via `FiberRef` (v3) / `ServiceMap.Reference` (v4) |\n| fibers are \"cancelled\"                       | fibers are \"interrupted\"                                      |\n| all queues have back-pressure                | only **bounded** queues; sliding/dropping do not               |\n| `new MyError(\"message\")`                     | `new MyError({ message: \"...\" })` (Schema errors take objects) |\n\n**v3-specific hallucinations:**\n\n| Wrong                              | Correct (v3)                                        |\n|------------------------------------|-----------------------------------------------------|\n| `Effect.Service` (function call)   | `class Foo extends Effect.Service<Foo>()(\"id\", {})` |\n| `Effect.match(effect, { ... })`    | `Effect.match(effect, { onSuccess, onFailure })`    |\n| `Effect.provide(layer1, layer2)`   | `Effect.provide(Layer.merge(layer1, layer2))`       |\n\n**v4-specific hallucinations (AI may mix v3/v4):**\n\n| Wrong (v3 API used in v4 code)    | Correct (v4)                                         |\n|-----------------------------------|------------------------------------------------------|\n| `Context.Tag(\"X\")`               | `ServiceMap.Service<X>(id)` or class syntax           |\n| `Effect.catchAll(fn)`            | `Effect.catch(fn)`                                    |\n| `Effect.fork(effect)`            | `Effect.forkChild(effect)`                            |\n| `Effect.forkDaemon(effect)`      | `Effect.forkDetach(effect)`                           |\n| `Data.TaggedError`               | `Schema.TaggedErrorClass`                             |\n| `FiberRef.get(ref)`              | `yield* References.X` (ServiceMap.Reference)          |\n| `yield* ref` (Ref as Effect)     | `yield* Ref.get(ref)` (Ref is no longer an Effect)    |\n| `yield* fiber` (Fiber as Effect) | `yield* Fiber.join(fiber)` (Fiber is no longer Effect) |\n| `Logger.Default` / `Logger.Live` | `Logger.layer` (v4 naming convention)                 |\n| `Schema.TaggedError`             | `Schema.TaggedErrorClass`                             |\n\n**Read `references/llm-corrections.md` for the exhaustive corrections table.**\n\n## Progressive Disclosure\n\nRead only the reference files relevant to your task:\n\n- Error modeling or typed failures → `references/error-modeling.md`\n- Services, DI, or Layer wiring → `references/dependency-injection.md`\n- Retries, timeouts, or backoff → `references/retry-scheduling.md`\n- Fibers, forking, or parallel work → `references/concurrency.md`\n- Streams, queues, or SSE → `references/streams.md`\n- Resource lifecycle or cleanup → `references/resource-management.md`\n- Schema validation or decoding → `references/schema.md`\n- Logging, metrics, or tracing → `references/observability.md`\n- HTTP clients or API calls → `references/http.md`\n- HTTP API servers → `references/http.md` (covers both client and server)\n- LLM/AI integration → `references/effect-ai.md`\n- Testing Effect code → `references/testing.md`\n- Migrating from async/await → `references/migration-async.md`\n- Migrating from v3 to v4 → `references/migration-v4.md`\n- Core types, gen, pipe, running → `references/core-patterns.md`\n- Full wrong-vs-correct API table → `references/llm-corrections.md`\n\n## Core Workflow\n\n1. **Detect version** from `package.json` before writing any code\n2. **Clarify boundaries**: identify where IO happens, keep core logic as `Effect` values\n3. **Choose style**: use `Effect.gen` for sequential logic, pipelines for simple transforms. In v4, prefer `Effect.fn(\"name\")` for named functions\n4. **Model errors explicitly**: type expected errors in the `E` channel; treat bugs as defects\n5. **Model dependencies** with services and layers; keep interfaces free of construction logic\n6. **Manage resources** with `Scope` when opening/closing things (files, connections, etc.)\n7. **Provide layers** and run effects only at program edges (`NodeRuntime.runMain` or `ManagedRuntime`)\n8. **Verify APIs exist** before using them - consult https://tim-smart.github.io/effect-io-ai/ or source docs\n\n## Starter Function Set\n\nStart with these ~20 functions (the official recommended set):\n\n**Creating effects:** `Effect.succeed`, `Effect.fail`, `Effect.sync`, `Effect.tryPromise`\n\n**Composition:** `Effect.gen` (+ `Effect.fn` in v4), `Effect.andThen`, `Effect.map`, `Effect.tap`, `Effect.all`\n\n**Running:** `Effect.runPromise`, `NodeRuntime.runMain` (preferred for entry points)\n\n**Error handling:** `Effect.catchTag`, `Effect.catchAll` (v3) / `Effect.catch` (v4), `Effect.orDie`\n\n**Resources:** `Effect.acquireRelease`, `Effect.acquireUseRelease`, `Effect.scoped`\n\n**Dependencies:** `Effect.provide`, `Effect.provideService`\n\n**Key modules:** `Effect`, `Schema`, `Layer`, `Option`, `Either` (v3) / `Result` (v4), `Array`, `Match`\n\n## Import Patterns\n\nAlways use barrel imports from `\"effect\"`:\n\n```typescript\nimport { Effect, Schema, Layer, Option, Stream } from \"effect\"\n```\n\nFor companion packages, import from the package name:\n\n```typescript\nimport { NodeRuntime } from \"@effect/platform-node\"\nimport { NodeSdk } from \"@effect/opentelemetry\"\n```\n\nAvoid deep module imports (`effect/Effect`) unless your bundler requires it for tree-shaking.\n\n## Output Standards\n\n- Show imports in every code example\n- Prefer `Effect.gen` (imperative) for multi-step logic; pipelines for transforms\n- In v4, use `Effect.fn(\"name\")` instead of bare `Effect.gen` for named functions\n- Never call `Effect.runPromise` / `Effect.runSync` inside library code - only at program edges\n- Use `NodeRuntime.runMain` for CLI/server entry points (handles SIGINT gracefully)\n- Use `ManagedRuntime` when integrating Effect into non-Effect frameworks (Hono, Express, etc.)\n- Always `return yield*` when raising an error in a generator (ensures TS understands control flow)\n- Avoid point-free/tacit usage: write `Effect.map((x) => fn(x))` not `Effect.map(fn)` (generics get erased)\n- Keep dependency graphs explicit (services, layers, tags)\n- State the `Effect<A, E, R>` shape when it helps design decisions\n\n## Agent Quality Checklist\n\nBefore outputting Effect code, verify:\n\n- [ ] Every API exists (check against tim-smart API list or source docs)\n- [ ] Imports are from `\"effect\"` (not `@effect/schema`, `@effect/io`, etc.)\n- [ ] Version matches the user's codebase (v3 vs v4 syntax)\n- [ ] Expected errors are typed in `E`; unexpected failures are defects\n- [ ] `run*` is called only at program edges, not inside library code\n- [ ] Resources opened with `acquireRelease` are wrapped in `Effect.scoped`\n- [ ] Layers are provided before running (no missing `R` requirements)\n- [ ] Generator bodies use `yield*` (not `yield` without `*`)\n- [ ] Error raises in generators use `return yield*` pattern","tags":["effect","skills","tenequm","agent-skills","ai-agents","claude-code","claude-skills","clawhub","erc-8004","mpp","openclaw","solana"],"capabilities":["skill","source-tenequm","skill-effect-ts","topic-agent-skills","topic-ai-agents","topic-claude-code","topic-claude-skills","topic-clawhub","topic-erc-8004","topic-mpp","topic-openclaw","topic-skills","topic-solana","topic-x402"],"categories":["skills"],"synonyms":[],"warnings":[],"endpointUrl":"https://skills.sh/tenequm/skills/effect-ts","protocol":"skill","transport":"skills-sh","auth":{"type":"none","details":{"cli":"npx skills add tenequm/skills","source_repo":"https://github.com/tenequm/skills","install_from":"skills.sh"}},"qualityScore":"0.461","qualityRationale":"deterministic score 0.46 from registry signals: · indexed on github topic:agent-skills · 23 github stars · SKILL.md body (8,970 chars)","verified":false,"liveness":"unknown","lastLivenessCheck":null,"agentReviews":{"count":0,"score_avg":null,"cost_usd_avg":null,"success_rate":null,"latency_p50_ms":null,"narrative_summary":null,"summary_updated_at":null},"enrichmentModel":"deterministic:skill-github:v1","enrichmentVersion":1,"enrichedAt":"2026-04-22T01:01:39.327Z","embedding":null,"createdAt":"2026-04-18T23:05:13.289Z","updatedAt":"2026-04-22T01:01:39.327Z","lastSeenAt":"2026-04-22T01:01:39.327Z","tsv":"'-07':242 '-12':237 '/docs':126 '/effect-io-ai/':146,603 '/effect-ts/effect-smol':152 '/effect-ts/effect-smol/blob/main/llms.md':159 '/llms-full.txt':138 '/llms.txt':132 '/tacit':799 '1':499 '2':508 '20':613 '2020':236 '2026':97 '3':521 '4':541 '5':556 '6':569 '7':580 '8':593 'acquirereleas':894 'agent':831 'ai':163,189,316 'alway':670,780 'api':148,173,176,322,454,458,494,595,840,847 'array':666 'ask':107 'async/await':475 'avoid':702,795 'back':266 'back-pressur':265 'backoff':423 'bare':742 'barrel':672 'bash':77 'beta':95 'bodi':909 'bound':269 'boundari':510 'bug':553 'build':15,47 'built':61 'built-in':60 'bundler':709 'cache.invalidate':199 'cache.invalidateall':201 'cache.make':194 'call':293,455,748,882 'cancel':258 'capac':195 'cat':81 'channel':551 'check':78,842 'checklist':833 'choos':522 'clarifi':509 'class':294,334 'cleanup':439 'cli/server':761 'client':452,463 'code':21,69,326,471,507,722,753,837,890 'codebas':89,116,865 'common':184 'companion':686 'composit':625 'comprehens':8 'concis':147 'concurr':31,56 'connect':578 'construct':567 'consult':600 'contain':170 'context':143 'context.tag':90,329 'control':793 'convent':387 'core':483,497,516 'correct':166,192,289,327,395,493 'cover':22,461 'creat':619 'critic':165 'data.taggederror':93,348 'debug':16 'decis':830 'decod':444 'deep':703 'default':110 'defect':29,555,879 'depend':33,57,558,653,813 'design':829 'detect':65,70,500 'develop':9 'di':415 'disclosur':398 'doc':129,140,180,606,851 'document':122 'draft':235,241 'e':550,823,875 'edg':589,757,886 'effect':2,5,7,20,39,41,68,84,172,203,219,231,238,300,302,341,343,345,347,359,368,373,381,470,519,585,620,658,675,678,684,771,775,821,836,855 'effect-t':1,4,38 'effect.acquirerelease':650 'effect.acquireuserelease':651 'effect.all':633 'effect.andthen':630 'effect.cachedinvalidatewithttl':198 'effect.cachedwithttl':193 'effect.catch':99,338,646 'effect.catchall':91,336,644 'effect.catchtag':211,643 'effect.fail':622 'effect.fn':536,627,738 'effect.fork':92,340 'effect.forkchild':100,342 'effect.forkdaemon':344 'effect.forkdetach':346 'effect.gen':525,626,725,743 'effect.map':631,802,807 'effect.maperror':202,205 'effect.match':299,301 'effect.ordie':648 'effect.provide':305,308,654 'effect.provideservice':655 'effect.runpromise':635,749 'effect.runsync':750 'effect.scoped':652,898 'effect.service':291,297 'effect.succeed':621 'effect.sync':623 'effect.tap':632 'effect.trypromise':624 'effect.website':125,131,137 'effect.website/docs':124 'effect.website/llms-full.txt':136 'effect.website/llms.txt':130 'effect/effect':706 'effect/io':858 'effect/opentelemetry':701 'effect/platform-node':697 'effect/schema':215,227,857 'either':662 'ensur':790 'entri':639,762 'eras':811 'error':24,27,54,281,408,543,547,641,786,871,915 'etc':579,779,859 'everi':175,721,839 'exampl':723 'exhaust':394 'exist':115,596,841 'expect':26,546,870 'explicit':544,815 'express':778 'extend':296 'failur':412,877 'feb':96 'fiber':32,248,256,259,370,371,376,377,425 'fiber-loc':247 'fiber.join':375 'fiberref':252 'fiberref.get':350 'file':403,577 'flow':794 'fn':204,206,337,339,804,808 'foo':295 'fork':426 'framework':776 'free':565,798 'frequent':169 'full':139,489 'function':292,540,608,614,746 'gen':485 'generat':19,191,240,789,908,918 'generic':809 'get':810 'github.com':151,158 'github.com/effect-ts/effect-smol':150 'github.com/effect-ts/effect-smol/blob/main/llms.md':157 'grace':766 'grade':50 'graph':814 'grep':83 'guardrail':164 'guid':10,156,162 'hallucin':185,287,315 'handl':642,764 'happen':514 'help':828 'hono':777 'http':451,457 'id':298,332 'identifi':511 'imper':726 'import':212,216,224,228,668,673,677,688,694,698,705,719,852 'incorrect':171 'index':135 'inject':34,58 'insid':751,888 'instal':79 'instead':740 'integr':467,770 'interfac':564 'interrupt':261 'io':513 'json':233 'jsonschema':225,229 'keep':515,563,812 'key':200,656 'larg':142 'layer':36,417,562,582,660,680,817,899 'layer.merge':309 'layer1':306,310 'layer2':307,311 'librari':45,752,889 'lifecycl':437 'list':149,848 'llm':133,161,167 'llm/ai':466 'local':245,249 'log':446 'logger.default':382 'logger.layer':384 'logger.live':383 'logic':517,528,568,731 'longer':366,380 'lookup':197 'manag':570 'managedruntim':592,768 'match':667,861 'may':317 'messag':276,279 'metric':447 'migrat':155,473,477 'miss':905 'mix':318 'model':25,409,542,557 'modul':657,704 'multi':729 'multi-step':728 'myerror':275,278 'name':386,537,539,692,739,745 'never':747 'new':119,274,277 'noderuntim':695 'noderuntime.runmain':590,636,759 'nodesdk':699 'non':774 'non-effect':773 'object':283 'observ':63 'offici':616 'often':190 'onfailur':304 'onsuccess':303 'open':892 'opening/closing':575 'option':661,681 'output':168,716,835 'packag':687,691 'package.json':82,503 'parallel':428 'pattern':113,669,922 'pipe':208,486 'pipelin':529,732 'point':640,763,797 'point-fre':796 'prefer':535,637,724 'pressur':267 'primari':121 'product':49,88 'production-grad':48 'program':588,756,885 'progress':397 'project':120 'provid':581,901 'qualiti':832 'queue':263,270,432 'r':824,906 'rais':784,916 're':37 'read':390,399 'recommend':617 'ref':351,356,357,362,363 'ref.get':361 'refer':179,402 'references.x':353 'references/concurrency.md':430 'references/core-patterns.md':488 'references/dependency-injection.md':419 'references/effect-ai.md':468 'references/error-modeling.md':413 'references/http.md':456,460 'references/llm-corrections.md':391,496 'references/migration-async.md':476 'references/migration-v4.md':482 'references/observability.md':450 'references/resource-management.md':440 'references/retry-scheduling.md':424 'references/schema.md':445 'references/streams.md':435 'references/testing.md':472 'relev':404 'requir':710,907 'resourc':436,571,649,891 'result':664 'retri':420 'return':781,920 'review':17 'run':487,584,634,880,903 'schema':213,217,234,239,280,441,659,679 'schema.taggederror':388 'schema.taggederrorclass':101,349,389 'scope':573 'sequenti':527 'server':459,465 'servic':414,560,816 'servicemap.reference':254,354 'servicemap.service':98,331 'servicemap/context':35 'set':609,618 'shake':715 'shape':825 'show':718 'sigint':765 'simpl':531 'skill' 'skill-effect-ts' 'sliding/dropping':271 'smart':846 'softwar':51 'sourc':123,154,605,850 'source-tenequm' 'specif':286,314 'sse':434 'stabl':86,128 'standard':717 'start':610 'starter':607 'state':819 'step':730 'storag':246,250 'stream':431,682 'structur':30,55 'style':523 'syntax':335,869 'tabl':396,495 'tag':818 'take':282 'task':407 'test':469 'thing':576 'thread':244 'thread-loc':243 'tim':845 'tim-smart':844 'tim-smart.github.io':145,602 'tim-smart.github.io/effect-io-ai/':144,601 'timeout':421 'timetol':196 'topic':134 'topic-agent-skills' 'topic-ai-agents' 'topic-claude-code' 'topic-claude-skills' 'topic-clawhub' 'topic-erc-8004' 'topic-mpp' 'topic-openclaw' 'topic-skills' 'topic-solana' 'topic-x402' 'trace':449 'transform':532,734 'treat':552 'tree':714 'tree-shak':713 'ts':3,6,40,791 'type':23,53,411,484,545,873 'typescript':12,44,676,693 'unclear':106 'understand':792 'unexpect':876 'unless':707 'usag':800 'use':13,182,210,323,524,598,671,737,758,767,910,919 'user':74,109,863 'v3':112,127,253,285,290,321,479,645,663,866 'v3-specific':284 'v3.10':220,232 'v3.x':85 'v3/v4':319 'v4':117,153,160,223,255,313,325,328,385,481,534,629,647,665,736,868 'v4-specific':312 'v4.x':94 'valid':442 'valu':520 'verifi':174,594,838 'version':64,72,80,104,187,501,860 'via':251 'vs':28,492,867 'wire':418 'without':914 'work':429 'workflow':498 'wrap':896 'write':67,505,801 'wrong':188,288,320,491 'wrong-vs-correct':490 'x':330,803,805 'yield':352,355,360,369,374,782,911,913,921","prices":[{"id":"7053fc77-36e4-4366-abbd-fade4b06812f","listingId":"c8ba1c58-fac2-4c19-a619-b9c84a731dd4","amountUsd":"0","unit":"free","nativeCurrency":null,"nativeAmount":null,"chain":null,"payTo":null,"paymentMethod":"skill-free","isPrimary":true,"details":{"org":"tenequm","category":"skills","install_from":"skills.sh"},"createdAt":"2026-04-18T23:05:13.289Z"}],"sources":[{"listingId":"c8ba1c58-fac2-4c19-a619-b9c84a731dd4","source":"github","sourceId":"tenequm/skills/effect-ts","sourceUrl":"https://github.com/tenequm/skills/tree/main/skills/effect-ts","isPrimary":false,"firstSeenAt":"2026-04-18T23:05:13.289Z","lastSeenAt":"2026-04-22T01:01:39.327Z"}],"details":{"listingId":"c8ba1c58-fac2-4c19-a619-b9c84a731dd4","quickStartSnippet":null,"exampleRequest":null,"exampleResponse":null,"schema":null,"openapiUrl":null,"agentsTxtUrl":null,"citations":[],"useCases":[],"bestFor":[],"notFor":[],"kindDetails":{"org":"tenequm","slug":"effect-ts","github":{"repo":"tenequm/skills","stars":23,"topics":["agent-skills","ai-agents","claude-code","claude-skills","clawhub","erc-8004","mpp","openclaw","skills","solana","x402"],"license":"mit","html_url":"https://github.com/tenequm/skills","pushed_at":"2026-04-14T16:24:57Z","description":"Agent skills for building, shipping, and growing software products","skill_md_sha":"13063cdfd282937e0c3594789769b133590f6107","skill_md_path":"skills/effect-ts/SKILL.md","default_branch":"main","skill_tree_url":"https://github.com/tenequm/skills/tree/main/skills/effect-ts"},"layout":"multi","source":"github","category":"skills","frontmatter":{"name":"effect-ts","description":"Effect-TS (Effect) comprehensive development guide for TypeScript. Use when building, debugging, reviewing, or generating Effect code. Covers typed error modeling (expected errors vs defects), structured concurrency (fibers), dependency injection (ServiceMap/Context + Layers), resource management (Scope), retry/scheduling (Schedule), streams, Schema validation, observability (OpenTelemetry), HTTP client/server, Effect AI (LLM integration), and MCP servers. Critical for AI code generation: includes exhaustive wrong-vs-correct API tables preventing hallucinated Effect code. Supports both Effect v3 (stable) and v4 (beta). Use this skill whenever code imports from 'effect', '@effect/platform', '@effect/ai', or the user mentions Effect-TS, typed errors with Effect, functional TypeScript with Effect, ServiceMap, Layer, or Schema from Effect. Also trigger when generating new TypeScript projects that could benefit from Effect patterns, even if the user doesn't explicitly name the library."},"skills_sh_url":"https://skills.sh/tenequm/skills/effect-ts"},"updatedAt":"2026-04-22T01:01:39.327Z"}}