Skip to main content
skill CX Codex

service-layer-extractor — Claude Code skill: how it works

service-layer-extractor refactors bloated route handlers into dedicated services and repositories. Separates business logic from HTTP transport and simplifies unit testing.

MIT 255 installs ★ 64 updated 2026-01-12

Install into Claude Code · Skills CLI (Vercel) All methods and platforms ↓
npx skills add patricio0312rev/skills --skill service-layer-extractor -a claude-code
Open on GitHub

What service-layer-extractor does

This skill reorganizes backend routes into clean architecture layers. Controllers keep input validation and HTTP responses, services handle orchestration, and repositories manage database queries. Heavy tasks like password hashing, email delivery, or raw database queries get pulled out of router callbacks.

The blueprint includes dependency injection setups and an eight-week migration strategy. You start by extracting services without breaking API contracts, cover them with isolated Jest tests, and then decouple queries into repositories. Splitting layers requires introducing explicit DTO interfaces, otherwise dependency injection fails to clean up controller bloat.

What it helps with

  • Extract SQL queries and external API calls from HTTP route handlers
  • Set up dependency injection to run unit tests without HTTP mocking
  • Restructure project directories into routes, controllers, services, and repositories
  • Plan multi-phase refactoring milestones without breaking live endpoints

Example prompts for the agent

  • Extract business logic from the user registration route into a dedicated service
  • Refactor order controller into separate service and repository classes with DI
  • Generate Jest unit tests mocking repository dependencies for UserService

How to install service-layer-extractor

1Skills CLI (Vercel)

npx skills add patricio0312rev/skills --skill service-layer-extractor -a claude-code

2Manually: put the files in place

~/.claude/skills/service-layer-extractor/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/service-layer-extractor/

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

Questions about service-layer-extractor

How to install service-layer-extractor in Claude Code?

Run npx skills add patricio0312rev/skills --skill service-layer-extractor -a claude-code. Alternatively, place the skill definition file into ~/.claude/skills/service-layer-extractor/SKILL.md.

What does service-layer-extractor do?

It extracts business logic from bloated controller functions into isolated service and repository classes. It also provides folder structure templates, DI container examples, and test mocks.

What phases does the migration plan include?

The migration covers four sequential phases: creating service classes, adding unit tests with 80%+ coverage, separating database queries into repositories, and configuring the DI container.

Source text

SKILL.md · MIT
---
name: service-layer-extractor
description: Refactors route handlers into service layer with clean boundaries, dependency injection, testability, and separation of concerns. Provides service interfaces, folder structure, testing strategy, and migration plan. Use when refactoring "fat controllers", "business logic", "service layer", or "architecture cleanup".
---

# Service Layer Extractor

Extract business logic from controllers into a testable service layer.

## Architecture Layers

```
routes/          → Define endpoints, parse requests
controllers/     → Validate input, call services, format responses
services/        → Business logic, orchestration
repositories/    → Database queries
models/          → Data structures
```

## Before: Fat Controller

```typescript
// ❌ Business logic mixed with HTTP concerns
router.post("/users", async (req, res) => {
  try {
    // Validation
    if (!req.body.email) {
      return res.status(400).json({ error: "Email required" });
    }

    // Check duplicate
    const existing = await db.query("SELECT * FROM users WHERE email = $1", [
      req.body.email,
    ]);
    if (existing.rows.length > 0) {
      return res.status(409).json({ error: "Email already exists" });
    }

    // Hash password
    const hashedPassword = await bcrypt.hash(req.body.password, 10);

    // Create user
    const result = await db.query(
      "INSERT INTO users (email, password, name) VALUES ($1, $2, $3) RETURNING *",
      [req.body.email, hashedPassword, req.body.name]
    );

    // Send welcome email
    await sendEmail(req.body.email, "Welcome!", "Thanks for joining");

    res.status(201).json(result.rows[0]);
  } catch (err) {
    res.status(500).json({ error: err.message });
  }
});
```

## After: Service Layer

```typescript
// ✅ Separated concerns

// services/user.service.ts
export class UserService {
  constructor(
    private userRepository: UserRepository,
    private emailService: EmailService
  ) {}

  async createUser(dto: CreateUserDto): Promise<User> {
    // Business logic only
    const existing = await this.userRepository.findByEmail(dto.email);
    if (existing) {
      throw new ConflictError("Email already exists");
    }

    const hashedPassword = await bcrypt.hash(dto.password, 10);

    const user = await this.userRepository.create({
      ...dto,
      password: hashedPassword,
    });

    await this.emailService.sendWelcome(user.email);

    return user;
  }
}

// controllers/user.controller.ts
export class UserController {
  constructor(private userService: UserService) {}

  create = asyncHandler(async (req, res) => {
    const user = await this.userService.createUser(req.body);
    res.status(201).json({ success: true, data: user });
  });
}

// repositories/user.repository.ts
export class UserRepository {
  async create(data: CreateUserData): Promise<User> {
    const result = await db.query(
      "INSERT INTO users (email, password, name) VALUES ($1, $2, $3) RETURNING *",
      [data.email, data.password, data.name]
    );
    return result.rows[0];
  }

  async findByEmail(email: string): Promise<User | null> {
    const result = await db.query("SELECT * FROM users WHERE email = $1", [
      email,
    ]);
    return result.rows[0] || null;
  }
}
```

## Dependency Injection

```typescript
// container.ts (using tsyringe or manual)
import { UserService } from "./services/user.service";
import { UserRepository } from "./repositories/user.repository";
import { EmailService } from "./services/email.service";

export class Container {
  private static instances = new Map();

  static get<T>(constructor: new (...args: any[]) => T): T {
    if (!this.instances.has(constructor)) {
      // Create dependencies
      const deps = this.resolveDependencies(constructor);
      this.instances.set(constructor, new constructor(...deps));
    }
    return this.instances.get(constructor);
  }

  private static resolveDependencies(constructor: any): any[] {
    // Resolve constructor dependencies
    return [];
  }
}

// Usage
const userService = Container.get(UserService);
```

## Testing Services

```typescript
// user.service.test.ts
describe("UserService", () => {
  let service: UserService;
  let mockRepository: jest.Mocked<UserRepository>;
  let mockEmailService: jest.Mocked<EmailService>;

  beforeEach(() => {
    mockRepository = {
      create: jest.fn(),
      findByEmail: jest.fn(),
    } as any;

    mockEmailService = {
      sendWelcome: jest.fn(),
    } as any;

    service = new UserService(mockRepository, mockEmailService);
  });

  it("creates user successfully", async () => {
    mockRepository.findByEmail.mockResolvedValue(null);
    mockRepository.create.mockResolvedValue({
      id: "1",
      email: "[email protected]",
    });

    const user = await service.createUser({
      email: "[email protected]",
      password: "password123",
      name: "Test User",
    });

    expect(user.id).toBe("1");
    expect(mockEmailService.sendWelcome).toHaveBeenCalled();
  });

  it("throws error if email exists", async () => {
    mockRepository.findByEmail.mockResolvedValue({ id: "1" } as User);

    await expect(
      service.createUser({
        email: "[email protected]",
        password: "pass",
        name: "Test",
      })
    ).rejects.toThrow(ConflictError);
  });
});
```

## Folder Structure

```
src/
├── routes/
│   └── users.routes.ts
├── controllers/
│   └── user.controller.ts
├── services/
│   ├── user.service.ts
│   ├── email.service.ts
│   └── payment.service.ts
├── repositories/
│   └── user.repository.ts
├── models/
│   └── user.model.ts
├── types/
│   └── user.types.ts
└── middleware/
    └── validate.ts
```

## Migration Strategy

```markdown
## Phase 1: Create Service Layer (Week 1-2)

- [ ] Create service classes
- [ ] Move business logic to services
- [ ] Keep controllers thin
- [ ] No breaking changes

## Phase 2: Add Tests (Week 3-4)

- [ ] Write service unit tests
- [ ] Mock dependencies
- [ ] Achieve 80%+ coverage

## Phase 3: Extract Repositories (Week 5-6)

- [ ] Create repository layer
- [ ] Move DB queries from services
- [ ] Services depend on repositories

## Phase 4: Dependency Injection (Week 7-8)

- [ ] Set up DI container
- [ ] Remove manual instantiation
- [ ] Wire up dependencies
```

## Benefits

- **Testability**: Services testable without HTTP
- **Reusability**: Logic reused across endpoints
- **Separation**: Clear boundaries between layers
- **Maintainability**: Easier to locate and modify logic

## Output Checklist

- [ ] Service classes created
- [ ] Business logic extracted from controllers
- [ ] Repository layer for data access
- [ ] Dependency injection setup
- [ ] Unit tests for services
- [ ] Folder structure reorganized
- [ ] Migration plan documented
- [ ] Team trained on new patterns

© patricio0312rev · MIT · patricio0312rev/skills

Similar skills

All skills for Backend and APIs →

From the same set148

The whole set →
llm-debugger llm-debugger diagnoses LLM output failures, patches faulty prompts, refines tool schemas, and generates regression test cases. CX Codex +1 259installs tool-function-schema-designer tool-function-schema-designer turns a rough tool idea into a JSON schema, a typed interface, a validation layer and example calls the model can actually follow. CX Codex +1 258installs test-reporting-triage-skill test-reporting-triage-skill sorts test failures into categories, suggests likely owners and lists next steps. Useful when you need a structured readout of a test run. CX Codex +1 257installs mocking-assistant mocking-assistant generates reliable mock setups for APIs, services, and UI components using MSW conventions and Vitest testing patterns. CX Codex +1 256installs rag-pipeline-builder rag-pipeline-builder designs a retrieval-augmented pipeline for a document assistant: chunking, metadata, hybrid search, reranking and a way to measure retrieval quality. CX Codex +1 251installs preview-environments-builder preview-environments-builder sets up ephemeral preview environments for pull requests with automated deployments, unique URLs, and automatic cleanup once a PR closes. CX Codex +1 250installs load-test-scenario-builder load-test-scenario-builder generates load testing plans, k6 automation scripts, traffic models, and threshold criteria to check service capacity. CX Codex +1 236installs graphql-schema-designer graphql-schema-designer is a Claude Code skill for shaping GraphQL APIs with types, queries, mutations, subscriptions, and resolvers. It activates for requests about schema design, GraphQL setup, or Apollo Server. CX Codex +1 230installs

Project sponsors

Companies that keep this analytics open