oma-backend
Implement server APIs, authentication, and application data access. Schema modeling and query tuning use oma-db.
How do I install this agent skill?
npx skills add https://github.com/first-fluke/oh-my-agent --skill oma-backendIs this agent skill safe to install?
- Gen Agent Trust Hubpass
The oma-backend skill is safe, following industry best practices for backend development such as clean architecture, mandatory input validation, and environment-based secret management. It utilizes standard local toolchains for building and testing across multiple languages.
- Socketpass
No alerts
- Snykpass
Risk: LOW · No issues
What does this agent skill do?
Backend Agent - API & Server Specialist
Scheduling
Goal
Implement or review backend APIs, authentication, database integration, server-side business logic, and migrations using the project's existing backend stack and clean architecture boundaries.
Intent signature
- User asks for API, endpoint, REST, GraphQL, auth, server, migration, repository, service, router, or background job work.
- User needs backend code that coordinates validation, business logic, persistence, transactions, and backing services.
When to use
- Building REST APIs or GraphQL endpoints
- Data access code and migrations that an API change needs
- Authentication and authorization
- Server-side business logic
- Background jobs and queues
When NOT to use
- Frontend UI -> use Frontend Agent
- Mobile-specific code -> use Mobile Agent
- Schema modeling, index design, and query tuning -> use
oma-db
Expected inputs
- Target feature, endpoint, migration, auth flow, or server behavior
- Existing backend stack files such as manifests, routes, services, models, and database config
- API contracts, schemas, validation rules, and persistence requirements
- Required verification commands or project conventions
Expected outputs
- Backend code changes in router, service, repository, model, migration, or test files
- Validated inputs, safe queries, transaction boundaries, and error handling
- Verification status: which checks ran, and what was not verified
Dependencies
- Project stack manifests and existing backend conventions
resources/execution-protocol.md,resources/checklist.md, andresources/orm-reference.md
- Optional stack reference (
stack/, or the matchingvariants/<language>/):stack.yaml,tech-stack.md, snippets, and API templates
- The project's own toolchain: ORM or database client, and its test, lint, typecheck, and migration commands
- Database, queue, cache, mail, auth, or external API resources configured through environment or secret managers
Structural Flow
Transitions
- If stack files exist, follow them before generic guidance.
- If ORM performance, relationship loading, transactions, or N+1 risk appears, use
resources/orm-reference.md. - If database schema impact is primary and API work is secondary, coordinate with
oma-db. - If auth server setup touches DB adapters or server libraries, keep it in backend scope.
Failure and recovery
- If stack cannot be determined, ask the user or suggest running
/stack-set. - If a required check fails, fix the root cause before handoff.
- If required secrets or services are unavailable, document the blocker and keep code configurable.
Exit
- Success: backend change is implemented, covered by tests, and aligned with local architecture.
- Partial success: blocker, missing dependency, or verification gap is explicit.
Logical Operations
Canonical workflow path
- Detect the stack (see Stack Detection) and identify the affected router, service, repository, model, migration, and test boundaries.
- Locate files and inspect symbols or content with the configured code-intelligence provider. For Serena, use
find_file,search_for_pattern,get_symbols_overview, andfind_symbol. Native search is limited to the provider exclusions and non-code paths permitted by the project's search policy. - Read the existing routes, services, repositories, models, schemas, and config. Load a stack-specific reference only when the task needs it.
- Implement the change with validation, business logic, persistence, and tests, following the Core Rules.
- Select the project's verification commands (lint, typecheck, tests, and migrations when schema changes are involved), preferring the
verify:commands instack/stack.yamlwhen present. Run them only when the user or the active workflow requires it; otherwise report what was not verified.
- Review the applicable checklist items and report the changed behavior, the verification status, and unresolved risks.
Resource scope and effects
Reads and edits backend source, tests, schemas, and migrations. A change may alter the database schema, API or auth behavior, or a service contract, and may require regenerated clients or migration artifacts. Credentials (DB URLs, API keys, secrets) stay in the environment or a secret manager; external APIs and backing services are called only when the task requires them.
Guardrails
Apply framework, library, architecture, and data-model defaults only when the target project has no established choice. Scoped edits do not authorize a stack migration or unrelated infrastructure.
Architecture Pattern
Router (HTTP) → Service (Business Logic) → Repository (Data Access) → Models
- Router: receives HTTP requests, validates input, calls the Service (injected through the framework's DI), and returns the response
- Service: owns business decisions, Repository composition, and external API calls
- Repository: encapsulates DB CRUD and query logic and returns ORM entities
Core Rules
- Clean architecture: router → service → repository → models
- No business logic in route handlers
- All inputs validated with your stack's validation library
- Parameterized queries only (never string interpolation)
- JWT + Argon2id for auth (bcrypt acceptable for legacy compatibility); rate limit auth endpoints
- Async where supported; type annotations on all signatures
- Custom exceptions via centralized error module (not raw HTTP exceptions)
- Explicit ORM loading strategy: do not rely on default relation loading when query shape matters
- Explicit transaction boundaries: group one business operation into one request/service-scoped unit of work
- Safe ORM lifecycle: do not share mutable ORM session/entity manager/client objects across concurrent work unless the ORM explicitly supports it
- Config from the environment; a fallback is declared, never implied: DB URLs, API keys, secrets, and feature flags come from environment variables or a secret manager, never from source. A missing credential fails with a clear error by default. A deterministic local fallback is written only when the integration is declared key-optional (a key provisioned later, a demo from a clean checkout) or a test/demo mode is explicitly selected: keep the real call and the fallback as separate env-conditional branches, mark the fallback
// TODO(oma-deferred): integrate <vendor> when key is provisioned, and label its output as simulated. A simulated payment, authentication, mail, or other effect is never reported as a completed real operation, and shipping only the fallback leaves the spec unmet. - Stateless services: no in-memory session or user state between requests; use external stores (DB, Redis, cache) for shared state
- Backing services as resources: DB, queue, cache, mail are swappable attached resources connected via config; Repository layer must not assume a specific instance
Stack Detection
- Project files first: Read existing code, package manifests (pyproject.toml, package.json, Cargo.toml, go.mod, pom.xml, etc.) to determine the tech stack
- Stack reference second: Use
stack/when present; otherwise the matchingvariants/<language>/. An installed project with a chosen preset hasstack/and novariants/; the plugin and source layouts havevariants/and nostack/. Treat it as supplementary reference for coding conventions and snippet templates - Neither applies: Ask the user or suggest running
/stack-set
Stack-Specific Reference
File names are relative to the stack reference directory selected above.
<!-- oma-docs:ignore-start -->- Stack manifest (SSOT):
stack.yaml: structured declaration (language,framework,orm) and theverify:contract.oma verify agent backendruns theverify:block ofstack/stack.yaml. The manifest's JSON Schema isvariants/stack.schema.jsonin the plugin and source layouts; an installed project does not carry it. - Tech stack narrative:
tech-stack.md: human-readable reference only;stack.yamlwins on conflict. - Code snippets (copy-paste ready):
snippets.md - API template:
api-template.*
References
-
Stack generation spec:
resources/stack-generation.md(loaded by/stack-setwhen it generates this skill'sstack/) -
Local code tools:
references/_shared/core/code-intelligence.md(code search/navigation) -
Execution steps (follow for the selected task):
resources/execution-protocol.md -
Checklist (check the applicable items before handoff):
resources/checklist.md -
ORM reference:
resources/orm-reference.md -
Error recovery:
resources/error-playbook.md -
Context loading:
references/_shared/core/context-loading.md -
Clarification:
references/_shared/core/clarification-protocol.md -
Context budget:
references/_shared/core/context-budget.md -
Lessons learned:
references/_shared/core/lessons-learned.md(matching prior failure or requested retrospective) -
Observability handoff:
../oma-observability/SKILL.md§Integrations — propagators/baggage, span conventions, log correlation, PII redaction
How can the creator link this skill?
Add the canonical catalog link to the repository README so users can inspect current installs and available audits. The publishing guide covers the complete discovery path.
<a href="https://skillzs.dev/skills/first-fluke/oh-my-agent/oma-backend">View oma-backend on skillZs</a>