agentleFS
Sign inStart free
theseus-runtheseus-run/theseus/.agents/skills/effect-observability-time/SKILL.md

effect-observability-time

Skill1 starsChanged 6 months agoMITView on GitHub

Use when adding or reviewing Effect time, retry, timeout, Clock/Duration, logging, tracing spans, metrics, Config, ConfigProvider, Redacted secrets, or operational observability in Theseus.

  • Reads credentials

The file

Show its rules and text

We split this skill into the rules it gives an agent

17 rules. About 0 are common, 4 are distinctive, and 13 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈4

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 13

    Very specific

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

  • Common
  • Distinctive
  • Very specific
  1. Distinctive:

    Use this skill for time-based behavior, retries, logs, spans, metrics, and runtime config.

    line 8
  2. Distinctive:

    Use Effect primitives instead of ad hoc timers and raw millisecond math.

    line 12
  3. Very specific:

    Use Clock when code needs current time from the Effect environment.

    line 26
  4. Very specific:

    Use Duration helpers for time units when clarity matters.

    line 27
  5. Very specific:

    Use Effect.sleep for delays, not setTimeout wrapped by hand.

    line 28
  6. Very specific:

    Use Effect.timeout around external calls that can hang.

    line 29
  7. Very specific:

    Use Schedule for retry; gate retry by failure shape when only some errors are retryable.

    line 30
  8. Very specific:

    Use Effect.logInfo, Effect.logDebug, Effect.logError, and Effect.annotateLogs.

    line 35
  9. Very specific:

    Use Effect.withSpan("name", { attributes }) around meaningful runtime boundaries.

    line 36
  10. Very specific:

    Use Metric.counter, Metric.gauge, or Metric.histogram when a value is operationally useful across runs, not just useful for local debugging.

    line 38
  11. Very specific:

    Avoid console.log in Effect runtime code.

    line 39
  12. Very specific:

    Use Effect Config for runtime configuration when code needs typed environment values.

    line 43
  13. Very specific:

    Do not read process.env throughout domain code.

    line 44
  14. Distinctive:

    Read config once through a service/layer, then inject the parsed values.

    line 45
  15. Distinctive:

    Keep secrets redacted in logs and errors.

    line 46
  16. Very specific:

    Use ConfigProvider in tests or alternate runtimes when config should come from a map/object rather than the process environment.

    line 47
  17. Very specific:

    Use Redacted for secrets and unwrap only at the final foreign boundary that needs the raw value.

    line 48

≈ “Common” is an estimate: at least 1 in 5 of the 350,495 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

Effect Observability And Time

Use this skill for time-based behavior, retries, logs, spans, metrics, and runtime config.

Time And Retry

Use Effect primitives instead of ad hoc timers and raw millisecond math.

import { Duration, Effect, Schedule } from "effect"

const guarded = operation.pipe(Effect.timeout(Duration.seconds(5)))

const retryPolicy = Schedule.exponential("200 millis").pipe(
  Schedule.jittered,
)

Rules:

  • Use Clock when code needs current time from the Effect environment.
  • Use Duration helpers for time units when clarity matters.
  • Use Effect.sleep for delays, not setTimeout wrapped by hand.
  • Use Effect.timeout around external calls that can hang.
  • Use Schedule for retry; gate retry by failure shape when only some errors are retryable.
  • Public retry fields should usually accept Schedule.Schedule<unknown> because schedule input is contravariant.

Logging, Tracing, Metrics

  • Use Effect.logInfo, Effect.logDebug, Effect.logError, and Effect.annotateLogs.
  • Use Effect.withSpan("name", { attributes }) around meaningful runtime boundaries.
  • Attach stable IDs and small primitive attributes to logs/spans; avoid dumping large payloads.
  • Use Metric.counter, Metric.gauge, or Metric.histogram when a value is operationally useful across runs, not just useful for local debugging.
  • Avoid console.log in Effect runtime code.

Configuration And Secrets

  • Use Effect Config for runtime configuration when code needs typed environment values.
  • Do not read process.env throughout domain code.
  • Read config once through a service/layer, then inject the parsed values.
  • Keep secrets redacted in logs and errors.
  • Use ConfigProvider in tests or alternate runtimes when config should come from a map/object rather than the process environment.
  • Use Redacted for secrets and unwrap only at the final foreign boundary that needs the raw value.

Checks

  • Does this external call have timeout or cancellation behavior?
  • Are retryable and non-retryable failures separated?
  • Would this log leak secrets or huge payloads?
  • Does the span name describe an operation rather than an implementation detail?
  • Is config read at a boundary and injected afterward?

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.

Check your setup, free