SE

services-layer

Services-layer enforces a consistent architecture using namespace exports and Result types to manage domain-specific error handling.

Install

mkdir -p .claude/skills/services-layer && curl -L -o skill.zip "https://agentskills.codes/api/skills/download/2304" && unzip -o skill.zip -d .claude/skills/services-layer && rm skill.zip

Installs to .claude/skills/services-layer

Activation

This is the description your AI agent reads to decide when to run this skill — the better it matches your request, the more reliably it fires.

Service layer patterns: defineErrors, namespace exports, Result types. Use when: "create a service", "service layer", creating services, defining domain-specific errors.
169 chars✓ has a “when” trigger
Advanced

Key capabilities

  • →Define domain-specific error namespaces
  • →Implement Result type return patterns
  • →Create pure, testable business logic services
  • →Extract error messages from unknown causes

How it works

It uses namespace exports and Result types to ensure business logic remains pure and error handling is consistent.

Inputs & outputs

You give it
Business logic requirements
You get back
Service layer implementation with Result types

When to use services-layer

  • →Create a new business logic service
  • →Define domain-specific error types
  • →Implement uniform error handling
  • →Decouple business logic from the UI

About this skill

Services Layer

Grounded in Whispering (apps/whispering/src/lib/app.ts and whispering.svelte.ts) and @epicenter/ai's customEndpoints() (connection-keys.ts). Read the app's app.ts and the capability package's entry before changing a service.

Product Sentence

A service owns a UI-free capability; the app passes in what it decides, fallible operations return Results, and the package that owns a capability picks its browser or desktop implementation when the page runs.

Boundary

Services may perform I/O and own service-local state. They stay free of UI and app policy:

  • no reads of Svelte state, settings notes, toasts, or reporting;
  • credentials, endpoints, models, paths, and the store come in as inputs;
  • domain data and tagged errors come out, not presentation copy;
  • a capability's browser and desktop implementations share one type.

A service never chooses or opens the store. It is made over the folder src/lib/app.ts opened: Whispering's createMicrophoneDevice({ files: folder.audio, recorder }) and createWhispering (whispering.svelte.ts), so a recording lands in the same store the pages read.

Where the page runs

One build serves the web and the desktop (see the platform-seams skill). The capability package picks its implementation: it decides presence with isTauri() when its module loads, and loads its desktop code with import() in its asynchronous step. The app imports one name (recorder from @epicenter/recorder, customEndpoints() from @epicenter/ai), and a capability a surface lacks is null there (localSpeech() in a browser). App code never checks isTauri().

On the desktop, a service reaches native code only through the app's shell and the shared crates, never through a credential in the page:

  • Secrets live in the app's credentials.json in AppData (mode 0600), which only epicenter-account reads and writes and no page reaches (ADR-0740). A connection's key is handed to the shell once (connectionKey in @epicenter/ai's tauri.ts, over connection_key_set and connection_key_move) and read by the request that uses it; connections.md in this computer's settings records which endpoint it was entered for, never the key. Never put a key in a settings file, the data folder, or WebView storage.
  • The account is a relay: requests go through account.fetch, which the shell sends with account_fetch and a token the page never sees.
  • Other requests to a custom endpoint or a server on this computer leave through the shell (connection_fetch, and shellFetch with no key), so no endpoint needs a CORS rule for the window's origin.
  • A root-scoped native command (the recorder, local transcription) names the data folder's root by name ('Data'), never by path; the shell refuses a root the window did not open.

Read service organization and platform variants when adding or moving a service.

Model Fallibility Honestly

Use Result<T, E> for an operation that can fail in ordinary use. Adapt throwing platform or library calls with the error-handling skill.

Do not fake a Result for an infallible in-memory action or a cleanup. Errors belong to the layer that understands the failure: pass lower-layer tagged errors through (TranscriptionError, RecorderError), and define a service-local variant only for a failure the service owns. Use error-handling for variant shape, message rules, adaptation, and propagation.

Direct Object Or Factory

Default to a plain object when construction has no input or lifecycle. Use a factory when it owns real construction inputs or a lifecycle: Whispering's capture device (createMicrophoneDevice, over the folder's audio and the package's recorder) owns one recording session at a time with its stop and recovery. Do not add create* only to call it once at module load. See service implementation patterns.

Runtime choices stay at the call

Which connection or provider a request uses is run-time state, not a build choice. Whispering's transcribe and transform read the selected connection (account, custom, or local on the desktop) when the request is sent, and send only while it is still the connection the request was prepared for. Keep that dispatch inside the one service method, not spread across callers.

Final Check

  • The service imports no UI and reads no settings; every app choice is an input.
  • It is made over the folder app.ts opened, and opens no store.
  • Fallible operations return Results; infallible ones stay plain.
  • A factory owns construction or a lifecycle, not convention.
  • The capability package picks the implementation where the page runs, with one shared type, and its desktop code loads on demand.
  • On the desktop, secrets stay in the shell's credentials file, account requests go through the relay, and no token or key reaches the page's storage.

When not to use it

  • →When importing UI code or reactive stores
  • →When throwing exceptions instead of returning Results

Prerequisites

Wellcrafted library

Limitations

  • →Services cannot import settings directly
  • →Requires specific error variant naming conventions

How it compares

It mandates explicit Result types and pure functions instead of relying on standard throw-catch exception handling.

Compared to similar skills

services-layer side by side with the closest alternatives in the catalog.

SkillInstallsUpdatedSafetyDifficulty
services-layer (this skill)75moNo flagsAdvanced
software-architecture3339moNo flagsIntermediate
codex325moReviewAdvanced
game-development709moNo flagsIntermediate

Try saying

Example prompts that trigger this skill in your AI assistant.

You might also like

software-architecture

davila7

Guide for quality focused software architecture. This skill should be used when users want to write code, design architecture, analyze code, in any case that relates to software development.

333868

codex

Lucklyric

Invoke Codex CLI for complex coding tasks requiring high reasoning capabilities. This skill should be invoked when users explicitly mention "Codex", request complex implementation challenges, advanced reasoning, or need high-reasoning model assistance. Automatically triggers on codex-related requests and supports session continuation for iterative development.

32238

game-development

davila7

Game development orchestrator. Routes to platform-specific skills based on project needs.

70195

senior-fullstack

davila7

Comprehensive fullstack development skill for building complete web applications with React, Next.js, Node.js, GraphQL, and PostgreSQL. Includes project scaffolding, code quality analysis, architecture patterns, and complete tech stack guidance. Use when building new projects, analyzing code quality, implementing design patterns, or setting up development workflows.

35110

command-name

anthropics

This skill should be used when the user asks to "create a plugin", "scaffold a plugin", "understand plugin structure", "organize plugin components", "set up plugin.json", "use ${CLAUDE_PLUGIN_ROOT}", "add commands/agents/skills/hooks", "configure auto-discovery", or needs guidance on plugin directory layout, manifest configuration, component organization, file naming conventions, or Claude Code plugin architecture best practices.

697

python-project-structure

wshobson

Python project organization, module architecture, and public API design. Use when setting up new projects, organizing modules, defining public interfaces with __all__, or planning directory layouts.

860

Search skills

Search the agent skills registry