code-structure

Separates action orchestration from reusable service-layer mechanics in application code.

Updated Jul 3, 2026
One-click install
npx skills add https://github.com/alex-jordan547/agent-setup --skill code-structure-alex-jordan547
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: code-structure
Source: https://github.com/alex-jordan547/agent-setup/tree/main/archive/2026-09-10/code-structure
Command: npx skills add https://github.com/alex-jordan547/agent-setup --skill code-structure-alex-jordan547

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve? When multiple workflows duplicate the same operational logic, bug fixes in one path fail to propagate to others and behavior drifts. This Skill provides a decision framework for splitting code into an orchestration layer (actions owning domain rules) and a service layer (shared operational mechanics). ## Core Features & Use Cases - Two-layer architecture pattern: Actions own business rules, auth, state transitions, and error classification; services own reusable operations like sandbox creation, email sending, and provider interactions. - Extraction guidance: Rules for when to extract shared logic (repeated across 2+ callers) versus when to keep logic in actions (single-caller, domain-specific code). - Migration checklist: A step-by-step process to extract one block, replace one caller, verify, then migrate the rest without breaking flows. - Use Case: You are adding a feature that sends welcome emails and notice the same email-sending logic exists in two other flows. Use this Skill to extract a shared email service while keeping opt-in policy in the actions. ## Quick Start Ask the agent to review your action files and decide which repeated operational logic should move into a shared service layer.

Frequently Asked Questions about code-structure

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I decide between actions and a service layer?

Keep domain rules in actions: auth, ownership checks, state transitions, failure classification, and user-facing errors. Move reusable operational mechanics into services: provider interactions, command execution, and health checks. Extract only logic repeated across two or more callers.

When should I extract shared logic into a service?

Extract when the same low-level operation appears in two or more callers, when you are copy-pasting operational logic between action files, or when a bug fix in one workflow does not propagate to others. Do not extract logic used by only one caller.

How should service layer functions be designed?

Design services as composable capability blocks, not one monolithic method. Each function accepts explicit parameters, returns structured outputs, never touches the database directly, and surfaces failures as structured results rather than swallowing errors.

What are common service layer anti-patterns?

Four anti-patterns to avoid: the god service hiding all control flow in one function, the leaky service mutating database tables directly, inconsistent APIs with mixed argument and error styles, and over-abstraction from extracting single-caller logic.

How do I migrate duplicated code to a service safely?

Write the flow in action code first, mark repeated operational chunks, extract only repeated non-domain chunks, then replace one caller and verify before migrating the rest. Finish with typecheck and lint to confirm all flows still work.