Skip to main content
skill CX Codex

opencode-ts — Claude Code skill for TypeScript and installation

The opencode-ts skill guides TypeScript implementation, tests, and refactoring in Effect-based projects. It gives the agent a workflow tied to the project’s architecture and conventions.

MIT 240 installs ★ 227 updated 2026-08-15

Install into Claude Code · Skills CLI (Vercel) All methods and platforms ↓
npx skills add pproenca/dot-skills --skill opencode-ts -a claude-code
Open on GitHub

What opencode-ts does

For a feature, bug fix, or test, the skill directs the agent to references covering architecture, services, tools, schemas, and test writing. It starts by locating the right module and checking whether the project already has a suitable helper. Refactoring follows a separate set of patterns, including moves to Effect services and removal of unnecessary abstractions.

The checks cover style, change scope, and tool choices. Services must use Context.Service and Layer; DTOs and tool parameters use Effect Schema. State-changing writes go through SyncEvent.run and projectors to SQLite, while tests use real services rather than mocks. This is a stack-specific guide, not a general set of TypeScript conventions.

What it helps with

  • add an Effect service that follows the project structure
  • check for an existing helper before writing another
  • review TypeScript changes against project style
  • write tests using real services
  • refactor code with a matching pattern

Example prompts for the agent

  • Add an Effect service for this feature and follow the project’s architecture.
  • Refactor this module using an existing helper where one fits.
  • Write tests for this behavior using real services.

How to install opencode-ts

1Skills CLI (Vercel)

npx skills add pproenca/dot-skills --skill opencode-ts -a claude-code

2Manually: put the files in place

~/.claude/skills/opencode-ts/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/opencode-ts/

Step by step, with commands for each platform: How to install skills in Claude Code: five ways

Questions about opencode-ts

How do I install opencode-ts in Claude Code?

Run npx skills add pproenca/dot-skills --skill opencode-ts -a claude-code. The skill file will be available at ~/.claude/skills/opencode-ts/SKILL.md.

What does opencode-ts do?

It guides TypeScript implementation, testing, and refactoring in Effect-based projects. Its workflow checks architecture, existing helpers, and project conventions.

Which Effect conventions does opencode-ts enforce?

Services use Context.Service and Layer, while DTOs and tool parameters use Effect Schema. State-changing writes follow an event-and-projector path to SQLite.

Source text

SKILL.md · MIT
---
name: opencode-ts
description: Write and refactor TypeScript code in repos that use Effect-TS services, Effect Schema, event-sourced persistence, and barrel-module architecture. Use this skill when implementing features, fixing bugs, writing tests, or refactoring in opencode or any TypeScript codebase built on the same stack (Effect DI via Context.Service, Drizzle ORM, Hono routes, Bun runtime). Triggers on tasks involving Effect services, Context.Service / Layer modules, Effect Schema definitions, SyncEvent patterns, tool implementations, test writing, or code review in Effect-based TypeScript projects.
---

# Opencode TypeScript

Code like the opencode core team. This skill contains real code extracted from the repo — complete implementations, not abstract rules. Follow the workflow below based on your task.

---

## Implement (new code)

Follow these phases in order:

### 1. Orient — where does this go?

Load [architecture.md](references/architecture.md). Find:
- Which module owns this behavior
- What the dependency direction allows
- What file naming convention to follow
- Whether this is a new module or an addition to an existing one

### 2. Gather — what already exists?

Load [helpers-deep-dive.md](references/helpers-deep-dive.md). Before writing ANY utility:
- Check if it already exists in `util/`, `effect/`, `bus/`, `sync/`
- Check the usage matrix to see how other modules use it
- If it exists, use it. If it doesn't, inline first — extract only when awkwardness repeats.

For quick lookups: [primitives.md](references/primitives.md) (shorter, import paths + signatures only)

### 3. Build — write the code

Load the reference that matches what you're building:

| Building... | Load this |
|---|---|
| Service module (namespace + Effect service + schemas + events) | [service-module.md](references/service-module.md) |
| Tool or modifying tool behavior | [tool-module.md](references/tool-module.md) |
| Database tables, schemas, events, error types | [schemas-and-state.md](references/schemas-and-state.md) |
| Server routes, config, plugins, project lifecycle | [server-and-routes.md](references/server-and-routes.md) |
| Tests | [test-writing.md](references/test-writing.md) |

### 4. CHECK GATE — code MUST pass all of these before proceeding

Load [style-dna.md](references/style-dna.md). **If ANY of the following fail, fix the code before proceeding to Review:**

- [ ] Single-word variable names where clear
- [ ] No `try`/`catch`, no `else`, no `any`, no unnecessary destructuring
- [ ] `const` + ternary over `let` + mutation
- [ ] snake_case Drizzle fields, `.annotate({ identifier })` on boundary schemas, `.annotate({ description })` on fields
- [ ] Effect Schema (`Schema.Struct`/`Schema.Schema.Type`) for DTOs, events, tool params — not Zod
- [ ] Effect is used for services, not plain async classes
- [ ] Module ends with `export * as X from "."` — no in-file `export namespace X {}`
- [ ] No patterns from Section 7 ("Things That Compile But Get Rejected") present in the diff

**DO NOT proceed if any check fails.** Go back to phase 3 and fix.

### 5. REVIEW GATE — REJECT the diff if any of these apply

Load [review-voice.md](references/review-voice.md). **The diff MUST NOT contain any of the following. If it does, fix before submitting:**

- [ ] Changes to files outside the scope of the task
- [ ] `as any` or `as unknown as` casts
- [ ] Custom utilities that duplicate community primitives or `@/util/*` helpers
- [ ] Provider-specific code that should live in models.dev
- [ ] Code removal without a clear reason documented in the commit
- [ ] Unexplained variable renames or structural changes
- [ ] Abstraction the core team would ask to remove (check refactoring-patterns.md)

---

## Refactor (changing existing code)

### 1. Orient — what touches what?

Load [architecture.md](references/architecture.md). Map the blast radius before changing anything.

### 2. Study — which pattern applies here?

Load [refactoring-patterns.md](references/refactoring-patterns.md). **Start with the Decision Matrix at the top** — match the code smell you see to the correct pattern. Then read the specific pattern section for real before/after diffs:
- Simplification patterns (removing unnecessary abstraction)
- Consolidation patterns (Bun → Node migration)
- Extraction patterns (pulling reusable utilities)
- Migration patterns (moving to Effect services)
- Deletion patterns (removing dead code)
- Stabilization patterns (fixing ordering/race conditions)
- Variant elimination (removing special cases)

### 3. Gather — can an existing utility replace this code?

Load [helpers-deep-dive.md](references/helpers-deep-dive.md). The best refactor often replaces 20 lines with one utility call.

### 4. Check + Review

Same as implement phases 4-5: [style-dna.md](references/style-dna.md) then [review-voice.md](references/review-voice.md).

---

## Key decisions (always apply)

- **Effect is mandatory** — all services use `Context.Service` / `Layer` / `makeRuntime`. No plain async classes.
- **One module, one self-barrel** — write flat top-level exports (schemas, `Interface`, `Service`, `layer`, `defaultLayer`), then close the file with `export * as X from "."`. Consumers still write `import { X } from "@/x"` → `X.Service`; the barrel *is* the namespace. opencode dropped in-file `export namespace X {}`.
- **Effect Schema everywhere** — `Schema.Struct` + `Schema.Schema.Type<typeof X>` for DTOs, events, and tool params; `.annotate({ identifier })` on boundary schemas, `.annotate({ description })` on fields. `Schema.TaggedErrorClass` for Effect errors. `Newtype<Self>()("Name", Schema.String.check(...))` (from `@opencode-ai/core/schema`) for branded IDs. Zod is no longer the boundary tool.
- **Event-sourced writes** — mutations go through `SyncEvent.run` → projectors → SQLite. Direct DB writes only for non-event-sourced features.
- **No mocks in tests** — use `tmpdir` + `Instance.provide` + real services. Mocks only for external SDKs.
- **Single-word variables** — `state`, `pending`, `info`, `row`, `cfg`, `tx`. Multi-word only when genuinely ambiguous.

---

## Reference index

| File | Size | What it contains |
|------|------|-----------------|
| [style-dna.md](references/style-dna.md) | 18K | Mandatory style rules, naming, control flow, 14 review traps |
| [primitives.md](references/primitives.md) | 22K | Quick-lookup: every utility with import path + signature |
| [helpers-deep-dive.md](references/helpers-deep-dive.md) | ~40K | Full deep-dive: every utility, every usage site, when NOT to use |
| [architecture.md](references/architecture.md) | ~30K | Module map, dependency graph, data flow, file conventions |
| [service-module.md](references/service-module.md) | 27K | Complete Question + Permission implementations |
| [tool-module.md](references/tool-module.md) | 28K | Full tool implementations, registry, prompt loop |
| [test-writing.md](references/test-writing.md) | 42K | 5 complete test files with all fixture patterns |
| [schemas-and-state.md](references/schemas-and-state.md) | 36K | SQL tables, Effect Schema (Struct/annotate/Newtype), SyncEvent flow, errors |
| [server-and-routes.md](references/server-and-routes.md) | 32K | Routes, config, plugins, project lifecycle |
| [review-voice.md](references/review-voice.md) | ~25K | Real PR review comments from Dax + Aiden |
| [refactoring-patterns.md](references/refactoring-patterns.md) | ~25K | Real before/after diffs from cleanup commits |

© pproenca · MIT · pproenca/dot-skills

Similar skills

All skills for Programming languages →

From the same set139

The whole set →
rust-implement rust-implement enforces a four-pass discipline for Rust development, moving from strict type design to implementation, simplification, and automated linting. CX Codex +1 254installs domain-architect domain-architect identifies business domains in a Swift codebase by tracing user capabilities, not folder names. Maps each domain's vertical slice from types to UI. CX Codex +1 249installs app-planner app-planner creates a structured Markdown design plan using Apple Design DNA patterns before coding starts. Organizes screens into buildable milestones for ios-taste. CX Codex +1 244installs threat-model threat-model maps attack surfaces and trust boundaries across a codebase by tracing untrusted inputs directly to execution sinks. CX Codex +1 243installs exec-plan exec-plan manages self-contained Markdown execution plans across agent sessions for tasks touching more than three files or taking over an hour. CX Codex +1 239installs graph-schema graph-schema is a Claude Code skill for designing, reviewing, and refactoring graph database schemas. It activates for node and relationship modeling or when mapping a domain into a graph. CX Codex +1 239installs clean-code-ts-react clean-code-ts-react adapts Robert C. Martin's Clean Code principles for TypeScript 5.x and React 19. Guides code reviews, component architecture, and refactoring sessions. CX Codex +1 238installs cli-for-agents cli-for-agents is a Claude Code skill for designing and reviewing CLIs used by AI agents and automation. It applies to work on subcommands, flags, help text, and error messages. CX Codex +1 237installs

Project sponsors

Companies that keep this analytics open