# Skiller Dev

> Apply the preferred Skiller coding style when refactoring or adding code in this repository. Use when editing runtime services, use cases, ports, or supporting tests and you need code that is flat, explicit, contract-driven, and easy to read.

- Skill: `fredycampino/skiller-dev` (Agent Skill, multi-file: 6 files)
- Install (CLI): `npx skillmds@latest add fredycampino/skiller-dev`
- Raw SKILL.md: https://api.skillmd.com/api/skills/fredycampino/skiller-dev/raw
- Safety review: pending (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: fredycampino (https://skillmd.com/u/fredycampino)
- Updated: 2026-09-22
- Page: https://skillmd.com/skills/fredycampino/skiller-dev

---


# Skiller Dev

Use this skill to keep Skiller code flat, explicit, and easy to maintain.

## Core Rules

- Follow the dependency rule: `interfaces -> application -> domain <- infrastructure`.
- Infrastructure may implement domain ports and use domain models, but must not orchestrate
  other domain ports or coordinate business flows.
- Put ports in `domain` under their feature directory, never in `application`.
- Keep services thin. Orchestrate; do not persist state directly from the service.
- Put state changes and side effects in dedicated use cases.
- Prefer closed contracts with enums for finite domains like statuses and step types.
- Keep result objects minimal. Prefer `status + payload + error` over many optional fields.
- Prefer typed contracts at port boundaries. Do not model stable operations as long scalar
  parameter lists or generic `dict[str, object]` bags when the domain concept is known.
- Prefer predictive flow over defensive flow. If a case is expected in normal execution,
  model it in the contract or result type instead of rediscovering it through scattered
  `None` checks or generic exceptions.
- Do not make dependencies or fields optional by default. Use `| None` only when absence is
  a real domain state or a boundary genuinely may not provide the value.
- Avoid adding `__init__.py` files by default. Use namespace packages unless a package needs
  real initialization logic, explicit re-exports, or tooling compatibility that requires it.
- Trust the contract of a use case. Do not add defensive checks for states that should be impossible.
- Prefer one clear error message over many overly specific status variants.
- Do not hide non-trivial preparation inside constructor or function-call parameters. Use explicit
  local variables; do not create private helpers for one or two simple statements unless asked.
- Do not put architectural responsibility in large top-level functions. If a function coordinates
  dependencies, owns a workflow, parses a whole external contract, or keeps growing, model it as an
  object with a clear role such as adapter, mapper, resolver, manager, use case, store, or tool.

## Read By Need

- For readability and control-flow rules, read `packages/skiller/docs/architecture/code-style.md`.
- For architecture boundaries and allowed dependencies, read `packages/skiller/docs/architecture/architecture.md`.
- For port, datasource, mapper, and infrastructure implementation names, read
  `packages/skiller/docs/architecture/naming-style.md`.
- For runtime patterns used in this repo, read `SKILL.md -> references/runtime-patterns.md`.
- For test taxonomy and what counts as unit/integration/e2e here, read `SKILL.md -> references/testing-rules.md`.
- For the general pre-commit checklist used in this repo, read `SKILL.md -> references/pre-commit-checklist.md`.
- For the documented feature and release branch flow of this repo, read `SKILL.md -> references/workflow.md`.
- For functional runtime rules around waiting, resume, and persisted external events, prefer `SKILL.md -> references/runtime-patterns.md`.

## Sandbox Execution

- Do not assume `pytest` is available in the global `PATH`.
- In this repo, run tests with `./.venv/bin/pytest ...`.
- If you prefer activation first, use `source .venv/bin/activate` and then `pytest ...`.
- For ad hoc Python commands with local imports, use `PYTHONPATH=src python3 ...`.
- When reporting verification, include the exact command so the next agent can repeat it without rediscovering the environment.

## Release Workflow

Use the documented repo flow in `references/workflow.md` unless the user says otherwise.
- Treat the `[Agent]`, `[User]`, `[Admin]`, and `[Workflow]` labels in `references/workflow.md` as the source of truth for responsibilities.

## Default Checklist

- Is the control flow flat?
- Are statuses and types modeled as enums when appropriate?
- Does each use case have one clear responsibility?
- Is the service only coordinating use cases?
- Would a new reader understand the happy path first?
- Are constructor and function-call parameters simple names instead of inline transformations?
- Are invalid cases reported with one clear message?
- If behavior or step contracts changed, did you review the affected docs, especially `docs/steps/*` and `docs/guia_creacion_skills.md`?
- If the task involves integration or release prep, did you follow `references/workflow.md` instead of an older manual flow?