Index of every page on this site: llms.txt
All skills
microsoft avatar

/resilience

@e4b5866
by microsoftmicrosoft/scope89 stars
32
Run it yourself

Apply resilience patterns (retry, backoff, circuit breaking) when writing or reviewing code that makes outbound HTTP/REST calls, database operations, or any I/O that can experience transient failures. Use this skill when: (1) writing new code that calls external services or APIs, (2) reviewing code that uses fetch, HTTP clients, or service-to-service calls, (3) adding queue consumers or workers that interact with remote systems, (4) debugging intermittent failures in production.

  • 1 file
  • 4.3 KB
  • Updated 5 months ago
  • GitHub
Use this Skill: https://skilld.dev/gh/microsoft/scope/resilience

Nothing lands on disk. Nothing to clean up.

Fork this Skill

Edit a local copy. It keeps the author and licence.

SKILL.md

≈124 tokens for metadata: the name and description. ≈950 when used: this file.

Description uses 6.2% of example budget

Before choosing a Skill, your Agent reads its name and description. All available Skills share that space.

  • A shorter description leaves more room for other Skills. This entry exceeds our 1% size suggestion.

In our Claude Code example, all Skill names and descriptions share 8,000 characters. This Skill uses ≈496 characters, or 6.2%.

The 1% threshold is a size suggestion. Longer descriptions can still fit.

Your model, settings, and other Skills decide how much text your Agent can read.

Example settings and source

The example uses a 200k-token context and default Claude Code settings. The count includes the name, description, separators, and when_to_use when present. Codex also counts local file paths.

Skit's source and limits: Codex 0.160.1, Claude Code 2.1.292.

Resilience Patterns

When writing or reviewing code that makes outbound calls (REST APIs, database operations, queue interactions), always consider transient failure handling.

Core Principle

Every outbound HTTP call should have a retry strategy unless there's a specific reason not to. Network blips, temporary 503s, and connection resets are normal in distributed systems. Code without retry is fragile by default.

Available Tools

This repo provides retry utilities in packages/shared/src/utils/retry.ts:

@Retry decorator (preferred for methods)

import { Retry } from "shared";

class MyWorker {
  @Retry({ maxRetries: 3, baseDelayMs: 1000, isRetryable: () => true })
  async callExternalService(): Promise<void> {
    const res = await fetch("http://api/endpoint", { method: "POST" });
    if (!res.ok) throw new Error(`HTTP ${res.status}`);
  }
}

withRetry function (for inline/conditional logic)

import { withRetry } from "shared";

const result = await withRetry(
  () => fetch("http://api/data").then(r => r.json()),
  { maxRetries: 3, baseDelayMs: 500, isRetryable: (err) => isTransient(err) }
);

Decision Checklist

When you encounter an outbound call, ask:

  1. Is this call idempotent? If yes (GET, PUT, DELETE with idempotency key) -> retry aggressively.
  2. Is this call non-idempotent? If yes (POST creating resources) -> retry cautiously, only on network errors (never got a response), not on 5xx (server may have processed it).
  3. Is this best-effort? (e.g., triggering reports, sending notifications) -> retry with try/catch at call site so failures don't propagate.
  4. Is this critical path? (e.g., saving user data) -> retry and propagate failure if exhausted.

What to Retry

Condition Retry? Reason
Network error (ECONNREFUSED, ETIMEDOUT) Yes Transient connectivity issue
HTTP 429 (Too Many Requests) Yes Rate limiting, respect Retry-After header
HTTP 500, 502, 503, 504 Yes Server-side transient failures
HTTP 400, 401, 403, 404, 409 No Client errors indicate a permanent problem
DNS resolution failure Yes (limited) May be temporary DNS propagation

Configuration Defaults

For service-to-service calls within the cluster:

  • maxRetries: 3
  • baseDelayMs: 1000 (1 second)
  • maxDelayMs: 5000 (5 seconds)

For external API calls:

  • maxRetries: 5
  • baseDelayMs: 500
  • maxDelayMs: 30000 (respect rate limits)

Anti-patterns

  • No retry at all on service-to-service calls -- fragile
  • Retry on 4xx -- wastes resources, will never succeed
  • Retry without backoff -- can overwhelm a recovering service
  • Retry without a cap -- can hang indefinitely
  • Retry non-idempotent POST without checking -- can create duplicates
  • Stacking retry layers -- never combine an HTTP client's built-in retry with withRetry/@Retry around the same call, or attempts multiply (maxRetries × client.limit). See below.

Single retry layer

Retry belongs to exactly one layer per call. The ky HTTP clients used by the CLI (apps/cli/src/utils/api-client.ts) and Portal (apps/portal/src/lib/api-client.ts) set retry: 0 precisely so they never stack with the shared cockatiel retry.

If a call needs transient-failure retries, pick one layer:

  • Enable the HTTP client's own retry (with its own backoff), OR
  • Wrap the call in withRetry / @Retry from packages/shared/src/utils/retry.ts.

Never both — combining them compounds attempts to maxRetries × client.limit.

Reference

Full API documentation: docs/architecture/retry.md

Source: SKILL.md on GitHub

skilld matched fixed text patterns in SKILL.md and file names. Patterns miss obfuscated code.

skilld run checks every file with the same patterns. It asks for approval before it loads a Skill with a behavior marked Needs approval.

No third-party reports yet.

Signed by skilld at e4b5866. This ties the file your Agent reads to that commit on GitHub. It does not review the instructions.

Last checked against GitHub yesterday.

Activeupdated 5 months ago
metadata
{
  "version": "1.0.0"
}

README badge

README badge for microsoft/scope/resilience