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.zipInstalls 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.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
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.jsonin AppData (mode0600), which onlyepicenter-accountreads and writes and no page reaches (ADR-0740). A connection's key is handed to the shell once (connectionKeyin@epicenter/ai'stauri.ts, overconnection_key_setandconnection_key_move) and read by the request that uses it;connections.mdin 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 withaccount_fetchand a token the page never sees. - Other requests to a custom endpoint or a server on this computer
leave through the shell (
connection_fetch, andshellFetchwith 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.tsopened, 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
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.
| Skill | Installs | Updated | Safety | Difficulty |
|---|---|---|---|---|
| services-layer (this skill) | 7 | 5mo | No flags | Advanced |
| software-architecture | 333 | 9mo | No flags | Intermediate |
| codex | 32 | 5mo | Review | Advanced |
| game-development | 70 | 9mo | No flags | Intermediate |
Try saying
Example prompts that trigger this skill in your AI assistant.
More by EpicenterHQ
View all by EpicenterHQ →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.
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.
game-development
davila7
Game development orchestrator. Routes to platform-specific skills based on project needs.
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.
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.
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.