Agent skill

Effect TS

by mattiacerutti in mattiacerutti/supernova

Write idiomatic Effect v4 TypeScript following official best practices from effect-solutions and the Effect source.

MITAuto-check passedDevelopment

Install Effect TS

skills CLI
$ npx skills add mattiacerutti/supernova --skill effect-ts -a claude-code

Project install by default; add -g for ~/.claude/skills/.

GitHub CLI
$ gh skill install mattiacerutti/supernova effect-ts --agent claude-code

Project scope by default; add --scope user for a personal install. Needs GitHub CLI 2.90.0 or later (public preview).

Manual copy
$ git clone --depth 1 https://github.com/mattiacerutti/supernova.git skills-src && mkdir -p .claude/skills && cp -r skills-src/.agents/skills/effect-ts .claude/skills/effect-ts && rm -rf skills-src

Use ~/.claude/skills/ instead of .claude/skills for a personal install. The folder must contain SKILL.md.

Claude Code skills documentation · loads skills from .claude/skills/

Facts

Skill name
effect-ts
GitHub stars
186
Token cost
~2.8k tokens
SKILL.md length
543 words
Files
10 (incl. references)
Skills in repo
2
Repo updated
First seen
Licence
MIT

At a glance

Write idiomatic Effect v4 TypeScript following official best practices from effect-solutions and the Effect source.

  • Refactoring Effect code: services (ServiceMap.Service)
  • SKILL.md covers Source-First Rule, References, Effect.gen and Effect.fn and ServiceMap.Service, plus 7 more sections
  • Instructions only: no scripts, shell commands, URLs or credentials in SKILL.md
  • Layers and dependency injection

What it does

Effect TS is an agent skill from mattiacerutti/supernova. Write idiomatic Effect v4 TypeScript following official best practices from effect-solutions and the Effect source. Use when writing, reviewing, or refactoring Effect code: services (ServiceMap.Service), layers and dependency injection, error handling (Schema.TaggedErrorClass), data modeling (Schema.Class, branded types, variants), testing (@effect/vitest), HTTP clients (effect/unstable/http), CLI tools (effect/unstable/cli), config, observability, and project setup. Triggers on: 'Effect', 'effect-ts'…

Its SKILL.md is about 2.8k tokens, which your agent loads only when the skill is triggered. The skill folder holds 10 other files, including reference files (for example `references/cli.md`, `references/config.md` and `references/data-modeling.md`).

It sits in Development, covering Database schema design, Design patterns and Unit testing. It works with Vitest and TypeScript. The repository describes itself as: A fast, opinionated development environment for Pi. The licence is MIT.

When your agent uses it

  • Refactoring Effect code: services (ServiceMap.Service)
  • Layers and dependency injection
  • Error handling (Schema.TaggedErrorClass)
  • Data modeling (Schema.Class

Example prompts

  • “Effect”
  • “effect-ts”
  • “@effect/”
  • “/effect-ts”

What it can do on your machine

Read from SKILL.md and the folder at commit a8577b9. It shows what the files ask for, not the result of running them.

  • Tool permissions

    Pre-approves nothing: there is no allowed-tools line, so your agent's usual permission prompts apply.

    From allowed-tools in the SKILL.md frontmatter.

  • Runs code

    No scripts in the folder and no shell commands in SKILL.md (its code samples are typescript).

    From the folder's file list and the shell code blocks in SKILL.md.

  • Network

    Links to these hosts (documentation or services it may open):

    • github.com

    From URLs in SKILL.md, links to its own repository left out.

  • Credentials

    Names no API keys, tokens, secrets or passwords.

    From names ending in _API_KEY, _TOKEN, _SECRET, _KEY or _PASSWORD in SKILL.md.

Context cost

Effect TS loads about 2.8k tokens when it runs, and up to ~19k if it reads all its reference files. Until then it costs about 163 tokens; SKILL.md has 543 words of instructions outside code blocks.

Always · name and description, kept in context so the agent knows when to use it
~163
When it runs · the whole SKILL.md, loaded when a task matches
~2.8k
With references · SKILL.md plus every file in references/, read only if the agent opens them
~19k

Estimates: characters ÷ 4, the usual rule of thumb; real counts depend on the model's tokenizer. Scripts and assets cost tokens only if the agent reads them.

Safety

Auto-check passed

The automated check found no risky patterns in SKILL.md.

Automated static check — not a guarantee. Review scripts before installing. It scans the text of SKILL.md for risky patterns (piping downloads into a shell, reading credential files, hidden Unicode, destructive commands); files beside SKILL.md are not scanned.

SKILL.md

The full file from mattiacerutti/supernova at commit a8577b9, republished under its MIT licence (© mattiacerutti). 543 words, ~2,821 tokens.

Download SKILL.mdSave it as .claude/skills/effect-ts/SKILL.md (or your agent's skills folder). This skill also uses 9 other files; get the full folder from GitHub.
name
effect-ts
description
Write idiomatic Effect v4 TypeScript following official best practices from effect-solutions and the Effect source. Use when writing, reviewing, or refactoring Effect code: services (ServiceMap.Service), layers and dependency injection, error handling (Schema.TaggedErrorClass), data modeling (Schema.Class, branded types, variants), testing (@effect/vitest), HTTP clients (effect/unstable/http), CLI tools (effect/unstable/cli), config, observability, and project setup. Triggers on: 'Effect', 'effect-ts', '@effect/', 'Schema', 'ServiceMap', 'Layer', 'Effect.gen', 'Effect.fn', 'TaggedError', 'branded types', or any Effect-TS related code.

Effect-TS (v4)

Patterns from effect-solutions and the Effect source. This covers the latest v4 APIs.

Source-First Rule

When working in any repo that uses Effect (effect or @effect/* in package/dependency files), reference the official Effect source before writing, reviewing, or refactoring Effect code. Do not rely on stale memory, blog posts, or high-level docs alone.

  • First check for the effect source mirror at .context/effect-smol/ and the effect-solutions code code mirror at .context/effect-solutions/.
  • If any of them are missing, return an error to the user with details and end the conversation. Do not attempt to answer from memory.

References

  • Effect mirror (canonical for current work): .context/effect-smol/
  • effect-solutions mirror (best practices, docs, examples): .context/effect-solutions/
  • Search the mirrors for current patterns and APIs, especially under .context/effect-smol/packages/effect/src/ and package tests/examples, before calling something an Effect best practice.

Effect.gen and Effect.fn

Effect.gen provides sequential, readable composition (like async/await for Effect):

typescript
import {Effect} from "effect";

const program = Effect.gen(function* () {
  const data = yield* fetchData;
  yield* Effect.logInfo(`Processing: ${data}`);
  return yield* processData(data);
});

Effect.fn adds call-site tracing and named spans. Use for all service methods:

typescript
const processUser = Effect.fn("processUser")(function* (userId: string) {
  yield* Effect.logInfo(`Processing user ${userId}`);
  const user = yield* getUser(userId);
  return yield* processData(user);
});

// Second argument for cross-cutting concerns (retry, timeout)
const fetchWithRetry = Effect.fn("fetchWithRetry")(
  function* (url: string) {
    const data = yield* fetchData(url);
    return yield* processData(data);
  },
  flow(Effect.retry(Schedule.recurs(3)), Effect.timeout("5 seconds"))
);

ServiceMap.Service

Define services as classes with a unique tag and typed interface:

typescript
import {Effect, ServiceMap} from "effect";

class Database extends ServiceMap.Service<
  Database,
  {
    readonly query: (sql: string) => Effect.Effect<unknown[]>;
    readonly execute: (sql: string) => Effect.Effect<void>;
  }
>()("@app/Database") {}

Implement with Layer.effect or Layer.sync, using Effect.fn for all methods:

typescript
import {Effect, Layer} from "effect";

class Users extends ServiceMap.Service<
  Users,
  {
    readonly findById: (id: UserId) => Effect.Effect<User, UserNotFoundError>;
    readonly all: () => Effect.Effect<readonly User[]>;
  }
>()("@app/Users") {
  static readonly layer = Layer.effect(
    Users,
    Effect.gen(function* () {
      const http = yield* HttpClient.HttpClient;
      const findById = Effect.fn("Users.findById")(function* (id: UserId) {
        const response = yield* http.get(`/users/${id}`);
        return yield* HttpClientResponse.schemaBodyJson(User)(response);
      });
      const all = Effect.fn("Users.all")(function* () {
        const response = yield* http.get("/users");
        return yield* HttpClientResponse.schemaBodyJson(Schema.Array(User))(response);
      });
      return {findById, all};
    })
  );
}

Rules:

  • Tag identifiers must be unique. Use @app/ServiceName pattern
  • Service methods should have R = never (dependencies via Layer, not method signatures)
  • Use readonly properties

See references/services-and-layers.md for service-driven development, test layers, layer memoization, and full composition patterns.

Schema.Class and Branded Types

Use Schema.Class for domain records. Brand all entity IDs and domain primitives:

typescript
import {Schema} from "effect";

const UserId = Schema.String.pipe(Schema.brand("UserId"));
type UserId = typeof UserId.Type;

const Email = Schema.String.pipe(Schema.brand("Email"));
type Email = typeof Email.Type;

class User extends Schema.Class("User")({
  id: UserId,
  name: Schema.String,
  email: Email,
  createdAt: Schema.Date,
}) {
  get displayName() {
    return `${this.name} (${this.email})`;
  }
}

// Construct with makeUnsafe for brands
const userId = UserId.makeUnsafe("user-123");

Use Schema.TaggedClass + Schema.Union for variants (OR types):

typescript
import {Match, Schema} from "effect";

class Success extends Schema.TaggedClass("Success")("Success", {
  value: Schema.Number,
}) {}
class Failure extends Schema.TaggedClass("Failure")("Failure", {
  error: Schema.String,
}) {}
const Result = Schema.Union([Success, Failure]);
type Result = typeof Result.Type;

// Exhaustive pattern matching
const render = (r: Result) =>
  Match.valueTags(r, {
    Success: ({value}) => `Got: ${value}`,
    Failure: ({error}) => `Error: ${error}`,
  });

See references/data-modeling.md for JSON encoding, Schema.Literals, validation, and full patterns.

Schema.TaggedErrorClass

Define domain errors with Schema.TaggedErrorClass. They are yieldable (no Effect.fail needed):

typescript
import {Schema} from "effect";

class UserNotFoundError extends Schema.TaggedErrorClass("UserNotFoundError")("UserNotFoundError", {userId: UserId, message: Schema.String}) {}

// Yieldable: yield directly in generators
const getUser = Effect.fn("getUser")(function* (id: UserId) {
  const user = yield* findUser(id);
  if (!user) yield* new UserNotFoundError({userId: id, message: "Not found"});
  return user;
});

Recover with catchTag / catchTags:

typescript
// Single tag
const recovered = program.pipe(Effect.catchTag("UserNotFoundError", (e) => Effect.succeed(`User ${e.userId} missing`)));

// Multiple tags
const recovered2 = program.pipe(
  Effect.catchTags({
    UserNotFoundError: (e) => Effect.succeed("not found"),
    ValidationError: (e) => Effect.succeed("invalid"),
  })
);

See references/error-handling.md for defects, Schema.Defect, and recovery patterns.

Layer Composition

Compose layers with Layer.provideMerge (incremental, flat types) and Layer.merge (parallel):

typescript
import {Effect, Layer} from "effect";

// Compose layers for the app
const appLayer = UserService.layer.pipe(Layer.provideMerge(DatabaseLayer), Layer.provideMerge(LoggerLayer), Layer.provideMerge(ConfigLayer));

// Provide once at the entry point
const main = program.pipe(Effect.provide(appLayer));
Effect.runPromise(main);

Key rules:

  • Store parameterized layers in constants (layer memoization by reference identity)
  • Provide once at app entry, not scattered throughout code
  • Use Layer.sync for synchronous implementations, Layer.effect for effectful ones
Show full SKILL.md (228 more words)Show less

Testing Quick Start

typescript
import {describe, expect, it} from "@effect/vitest";
import {Effect, Layer} from "effect";

it.effect("queries database", () =>
  Effect.gen(function* () {
    const db = yield* Database;
    const results = yield* db.query("SELECT *");
    expect(results.length).toBe(2);
  }).pipe(Effect.provide(Database.testLayer))
);
  • Use it.effect for Effect-based tests (provides TestContext with TestClock)
  • Use it.live for real time / real clock
  • Provide fresh layers per test to prevent state leakage
  • Use it.layer only when sharing expensive resources across a suite

See references/testing.md for the full worked example and advanced patterns.

Pipe for Instrumentation

typescript
const program = fetchData.pipe(
  Effect.timeout("5 seconds"),
  Effect.retry(Schedule.exponential("100 millis").pipe(Schedule.compose(Schedule.recurs(3)))),
  Effect.tap((data) => Effect.logInfo(`Fetched: ${data}`)),
  Effect.withSpan("fetchData")
);

Anti-Patterns

Do NotDo Instead
console.log(...)Effect.log(...) with structured data
process.env.KEYConfig.string("KEY") or Config.redacted("KEY")
throw new Error() inside Effect.genyield* new TaggedError({...}) or Effect.fail(...)
Effect.runSync(...) inside servicesKeep everything effectful
Effect.catchAll(() => ...) losing type infoEffect.catchTag / Effect.catchTags
null / undefined in domain typesOption<T> with Option.match
Option.getOrThrow(...)Option.match({ onNone, onSome }) or Option.getOrElse
Effect.Service (v3)ServiceMap.Service (v4)
Schema.TaggedError<T>() (v3)Schema.TaggedErrorClass("Tag")("Tag", {...}) (v4)
Scatter Effect.provide callsProvide once at app entry
Call parameterized layer constructors inlineStore layers in constants (memoization)

Reference Files

Load these as needed for deeper patterns:

  • Services & Layers: ServiceMap.Service, service-driven development, test layers, layer memoization, provide vs provideMerge
  • Data Modeling: Schema.Class, branded types, variants, Match.valueTags, JSON encoding
  • Schema Decisions: Schema.Class vs Struct vs TaggedClass decision flowchart, migration patterns
  • Error Handling: Schema.TaggedErrorClass, catch/catchTag/catchTags, defects, Schema.Defect, TypeId/refail patterns
  • Testing: @effect/vitest setup, it.effect/it.live/it.layer, TestClock, Effect.flip, FiberRef isolation, worked example
  • HTTP Clients: HttpClient, request building, response decoding, middleware, retries, typed API service
  • CLI: Command.make, Arguments, Flags, subcommands, worked task manager example
  • Config: Config module, schema validation, ConfigProvider, Redacted, config layers
  • Processes & Scopes: Fork types, Scope.extend, Command for child processes, killable background tasks

© mattiacerutti, MIT. Rendered from Markdown: HTML in the file is shown as text, images as links, and headings moved down two levels. Raw file

Files

SKILL.md and 9 other files (references) in .agents/skills/effect-ts of mattiacerutti/supernova.

  • SKILL.md
  • references/cli.md
  • references/config.md
  • references/data-modeling.md
  • references/error-handling.md
  • references/http-clients.md
  • references/processes.md
  • references/schema-decisions.md
  • references/services-and-layers.md
  • references/testing.md

Open the folder on GitHubat commit a8577b9

Compare with similar skills

Effect TS next to the 5 skills that share the most tags, products or categories with it. Stars are the repository's; “used in” counts other GitHub owners with a copy.

Effect TS compared with similar skills
SkillStarsUsed inTokensAuto-checkLicenceRepo updated
Effect TS this skillmattiacerutti/supernova186—~2.8kAutomated safety check: PassMIT
Effect TStellahq/opensession392—~3.7kAutomated safety check: PassMIT
Effect TSpproenca/dot-skills215—~2kAutomated safety check: PassMIT
Tabler Shared Lib Helperstabler/tabler42k—~1.2kAutomated safety check: PassMIT
Typescript Idiomsirahardianto/awesome-agv157—~6.1kAutomated safety check: PassMIT
Vue Idiomsirahardianto/awesome-agv157—~6kAutomated safety check: PassMIT

Similar skills

  • Effect TS

    tellahq/opensession

    Write idiomatic Effect v4 TypeScript verified against the pinned effect@4.0.0-rc.112 source.

    392 GitHub stars~3.7k tokensUpdated today
    Testing & QAAuto-check passed
  • Effect TS

    pproenca/dot-skills

    Effect-TS library usage in TypeScript — Effect.gen generators, Schema.Struct/Schema.Class definitions, Layer/Context.Tag/Service patterns, Effect.pipe pipelines, Data.TaggedError/Data.Class error…

    215 GitHub stars~2k tokensUpdated 1 mo ago
    DevelopmentAuto-check passed
  • Moves logic out of Astro frontmatter into tested helper modules under shared/lib, with rules for naming, typing, deterministic demo data and sibling test files.

    42k GitHub stars~1.2k tokensUpdated today
    DevelopmentAuto-check passed
  • Typescript Idioms

    irahardianto/awesome-agv

    TypeScript strict typing: type narrowing, discriminated unions, Zod runtime validation, generic utility types, and Vitest testing.

    157 GitHub stars~6.1k tokensUpdated 4 days ago
    Testing & QAAuto-check passed
  • Vue Idioms

    irahardianto/awesome-agv

    Vue 3 Composition API patterns: <script setup syntax, reactive state with Pinia stores, reusable composables, and Vitest component testing.

    157 GitHub stars~6k tokensUpdated 4 days ago
    Testing & QAAuto-check passed
  • Console Testing

    synnaxlabs/synnax

    Rules for writing and editing unit tests in the Console (console/src//.spec.ts[x]).

    128 GitHub stars~5.4k tokensUpdated today
    Testing & QAAuto-check passed

More from mattiacerutti/supernova

  • No Use Effect

    mattiacerutti/supernova

    Enforce the no-useEffect rule when writing or reviewing React code.

    186 GitHub starsUsed in 2 repos~1.7k tokens
    Auto-check passed

Questions about Effect TS

What does Effect TS do?

Write idiomatic Effect v4 TypeScript following official best practices from effect-solutions and the Effect source. Effect TS is an agent skill from mattiacerutti/supernova. Write idiomatic Effect v4 TypeScript following official best practices from effect-solutions and the Effect source.

When should I use Effect TS?

Effect TS fits situations like: refactoring Effect code: services (ServiceMap.Service); layers and dependency injection; error handling (Schema.TaggedErrorClass); data modeling (Schema.Class.

How do I install Effect TS in Claude Code?

Run `npx skills add mattiacerutti/supernova --skill effect-ts -a claude-code`. Or copy the skill folder (.agents/skills/effect-ts in mattiacerutti/supernova) into .claude/skills/effect-ts in your project. Claude Code loads it when a task matches its description.

How do I install Effect TS in Codex?

Run `npx skills add mattiacerutti/supernova --skill effect-ts -a codex`. Or copy the skill folder (.agents/skills/effect-ts in mattiacerutti/supernova) into .agents/skills/effect-ts in your project. Codex loads it when a task matches its description.

Can I use Effect TS in Cursor, Gemini CLI or GitHub Copilot?

Cursor, Gemini CLI, GitHub Copilot and OpenCode also load SKILL.md folders. With the skills CLI, run `npx skills add mattiacerutti/supernova --skill effect-ts -a cursor` (or -a gemini-cli, github-copilot or opencode for the others). To copy it by hand, put the folder in .cursor/skills/effect-ts, .gemini/skills/effect-ts, .github/skills/effect-ts and .opencode/skills/effect-ts in your project.

What does Effect TS need to run?

SKILL.md names no scripts, command-line tools or credentials: Effect TS is instructions for the agent only.

Does Effect TS access the network?

SKILL.md names 1 domain. As links in the text: github.com. This is read from the text; nothing was executed.

Is Effect TS safe to install?

Our automated static check of SKILL.md found no risky patterns, such as piping downloads into a shell, reading credential files or hidden Unicode. It is not a guarantee. Review the folder before installing.

What licence does Effect TS use?

Effect TS is published under the MIT licence (the repository's licence). It allows redistribution, so the full SKILL.md is shown on this page.

How many tokens does Effect TS use?

About 2.8k tokens (SKILL.md is roughly 11k characters). Agents keep only the skill's name and description in context until a task matches; then they load SKILL.md in full. Its references folder adds about 17k tokens, read only when the agent opens those files.

What are the alternatives to Effect TS?

Skills that share tags, products or a category with Effect TS: Effect TS (tellahq/opensession, 392 stars), Effect TS (pproenca/dot-skills, 215 stars), Tabler Shared Lib Helpers (tabler/tabler, 42k stars) and Typescript Idioms (irahardianto/awesome-agv, 157 stars). The comparison table on this page puts their stars, adoption, token cost, safety result and licence side by side.

Who maintains Effect TS?

mattiacerutti (a GitHub user) maintains it in mattiacerutti/supernova, which has 186 GitHub stars. The repository holds 2 skills in this directory. The repository was last updated on October 7, 2026.

Source: mattiacerutti/supernova on GitHub. Facts on this page come from the repository at the commit we read; the author's words are quoted as theirs.