agentleFS
selamy-labsselamy-labs/agent-skills/skills/instrumented-service-scaffold/SKILL.md

instrumented-service-scaffold

Skill0 starsChanged 7 days agoMITView on GitHub

Use when creating or reviewing a new long-running service so observability, runtime flags, tests, coverage gates, and release controls exist from the first commit.

The file

We split this skill into the rules it gives an agent

5 rules. About 0 are common, 5 are distinctive, and 0 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈5

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 0

    Very specific

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

  • Common
  • Distinctive
  • Very specific
  1. Distinctive:

    Use this workflow when authoring or reviewing a new service, worker, daemon, API, or other long-running software component.

    line 8
  2. Distinctive:

    Do not defer these to a later hardening pass.

    line 38
  3. Distinctive:

    Verify the user/system artifact and the telemetry after the change.

    line 48
  4. Distinctive:

    Before claiming the service is ready, grep the real repository for each item — not the intent, the artifact:

    line 55
  5. Distinctive:

    Do not call the service production-ready while the baseline is missing.

    line 76

≈ “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

Instrumented Service Scaffold

Use this workflow when authoring or reviewing a new service, worker, daemon, API, or other long-running software component.

Baseline

From the first commit, the service must include:

  • OpenTelemetry traces, metrics, and structured logs wired through a real exporter.
  • A runtime flag client (e.g. OpenFeature) backed by a flag source that can be reviewed and rolled back without a redeploy.
  • A formatter, linter, and type/static-analysis gate using the language's standard tools.
  • Complexity and nesting budgets that stop new outliers before they turn into review-time style debates.
  • A test harness: unit tests, contract tests where interfaces matter, at least one feature check for promised behavior, and a coverage gate sized to the service's risk.
  • PR-only delivery with branch protection and required checks for tests, coverage, release policy, and build/deploy validation.
  • State-changing delivery workflows (deploy, apply, image-publish) that serialize per target via a concurrency group with cancel-in-progress: false; read-only CI may cancel superseded runs.
  • Conventional release or changelog metadata when the repo uses automated versioning.
  • For state where change history matters (quotas, balances, membership, config), record changes as replayable events rather than only the latest value; compose with event-sourcing (https://github.com/selamy-labs/agent-skills/tree/main/skills/event-sourcing).

Do not defer these to a later hardening pass. If the service is too small to justify them, document that decision and keep it short-lived or non-production.

Self-Debug Loop

The owner of the service needs the ability to:

  1. Observe its own traces, metrics, and structured logs.
  2. Form a concrete hypothesis from that telemetry.
  3. Change behavior through a reviewed runtime flag or a normal PR.
  4. Verify the user/system artifact and the telemetry after the change.

The loop is incomplete if it depends on a human manually spelunking logs on the owner's behalf.

Conformance Check

Before claiming the service is ready, grep the real repository for each item — not the intent, the artifact:

  • OpenTelemetry init code and at least one meaningful span or metric on a business-critical flow.
  • Runtime flag client init pointing at a reviewed flag source.
  • Formatter, linter, static-analysis, complexity, and coverage config enforced by CI (the config files plus the CI job that runs them).
  • At least one feature-level behavior check for the primary promise, not only line coverage.
  • State-changing workflows (deploy, apply, release, image-publish) that declare queue-not-cancel concurrency scoped to serialize each target environment, state file, or published artifact.
  • Required PR checks and release-policy checks present in the repo settings or IaC source of truth.
  • For any state the service declared history-bearing: an append-only event/change record plus the code path that emits it — not only a latest-value column or gauge.
  • Docs that explain how to observe the service and change a flag.

Record any gap as a blocker or an explicit temporary waiver with a removal date. Do not call the service production-ready while the baseline is missing.

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.