agentleFS
openclosed-orgopenclosed-org/axum-harness/.agents/skills/service-agent/SKILL.md

service-agent

Skill48 starsChanged 6 months agoApache-2.0View on GitHub

Maintains services, domain logic, application layer, policies, ports, and service-local distributed semantics in services/<name>/model.yaml. Owns services/**, fixtures/**, verification/** (service-level). Services are pure libraries — no main.rs, no HTTP server, no message consumer loops. Use when changing services/**, service-owned commands/events/queries, domain rules, ports, policies, service-local tests, or service-local declared semantics. Never implements infrastructure adapters or process entry points.

The file

We split this skill into the rules it gives an agent

4 rules. About 0 are common, 3 are distinctive, and 1 is very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈3

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 1

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Distinctive:

    Ensure domain logic accesses the external world only through ports

    line 24
  2. Very specific:

    Ensure services are pure libraries (no main.rs, no HTTP server, no consumer loops)

    line 25
  3. Distinctive:

    Every service model must declare:

    line 90
  4. Distinctive:

    When adding a new service, prefer copying the nearest matching reference pattern instead of inventing a new structure.

    line 108

≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

Service Agent

You maintain business capability libraries and their service-local distributed semantics.


Responsibility

  1. Own all services/*/ directories — domain service libraries
  2. Maintain domain logic, use cases, policies, port definitions
  3. Maintain services/<name>/model.yaml as the declared index for service-local distributed semantics
  4. Ensure domain logic accesses the external world only through ports
  5. Ensure services are pure libraries (no main.rs, no HTTP server, no consumer loops)
  6. Coordinate with contract-agent when service interfaces change protocol

Read Before Editing

AGENTS.md                                     → global protocol
agent/codemap.yml                             → module constraints (services layer)
.agents/skills/backend-engineering/SKILL.md   → backend quality kernel
platform/model/README.md                      → platform vs service boundary
services/<name>/model.yaml                    → service-local declared semantics index
Individual service Cargo.toml and README.md

Writable Directories

DirectoryScope
services/**Service source code and model.yaml
fixtures/**Test data and seed data
verification/**Service-level validation tests
packages/contracts/**When service interfaces change need protocol updates

Forbidden Directories

DirectoryReason
infra/**Owned by platform-ops-agent
platform/model/**Platform-level model owned by platform-ops-agent
packages/**/adapters/**Concrete adapter implementations
servers/**Owned by server-agent
workers/**Owned by worker-agent
Another service's directoryServices must not import each other

Gate Candidates

Select gates from agent/manifests/gate-matrix.yml based on changed paths, risk, and evidence level. Common service signals include:

GateCommand
Service build checkcargo check -p <service-package>
Service testscargo test -p <service-package>
Typecheckjust typecheck
Boundary checkjust boundary-check

Hard Rules

Workflow skills, including backend-engineering, may guide process; this skill's ownership boundaries still apply.

  1. Services are libraries — no main.rs, no HTTP server, no consumer loops
  2. Services must NOT import other services (services/*)
  3. Services must NOT import concrete adapters (packages/**/adapters/**)
  4. Services must NOT import infra/** or ops/**
  5. External access only through ports/
  6. Service-local distributed semantics belong in services/<name>/model.yaml
  7. Every service model must declare:
    • owns_entities
    • accepted_commands
    • published_events
    • served_queries
    • cross_service_reads
    • spec_completeness
  8. Non-owner direct writes are forbidden; cross-service mutation must go through command or workflow

Reference Modules

These services are the reference set and should be treated as learning templates:

  1. counter-service → minimal end-to-end chain, CAS, event publication
  2. tenant-service → multi-tenant, multi-entity, workflow, compensation

When adding a new service, prefer copying the nearest matching reference pattern instead of inventing a new structure.


Service Structure Convention

Each service should have:

  1. model.yaml
  2. Cargo.toml, src/lib.rs
  3. src/domain/, src/application/, src/policies/, src/ports/
  4. src/events/, src/contracts/
  5. tests/, migrations/, README.md

When to Escalate

  1. Service needs to import another service (extract to shared package or change model)
  2. Service needs concrete adapter (must go through ports → adapters pattern)
  3. Service contains main.rs or process entry point
  4. Service change breaks contracts used by servers/workers/apps
  5. A service requires workflow semantics but no workflow model exists yet
  6. A cross-service read cannot be expressed as query-api, projection, or forbidden

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.