medium-skill

Medium-sized skill for comprehensive token testing

⭐3stars🔀1forks📁View on GitHub🕐Updated Jan 2, 2026⬇️1downloads

When & Why to Use This Skill

This Claude skill serves as a comprehensive technical playbook for engineering teams to design and implement robust API integrations. It provides structured guidance on establishing clear API contracts, managing authentication and secrets securely, implementing resilient error handling with exponential backoff, and handling large-scale data through efficient pagination. By codifying best practices, it helps developers build reliable, secure, and scalable integration layers while minimizing common pitfalls in external service communication.

Use Cases

  • Architecting New Integrations: Use the playbook to define mandatory fields, rate limits, and authentication checklists before writing the first line of code.
  • Enhancing System Reliability: Implement the recommended exponential backoff and jitter strategies to handle transient network failures and avoid amplifying outages.
  • Security Auditing: Review current secret management and logging practices against the skill's guidelines to ensure credentials are never exposed in source control or debug logs.
  • Optimizing Data Fetching: Apply standardized pagination and cursor-based navigation logic to handle large datasets efficiently without impacting system performance.
  • Code Review Standardization: Reference the skill during pull requests to ensure integration code adheres to established best practices for error handling and idempotency.
namemedium-skill
descriptionMedium-sized skill for comprehensive token testing

Medium Skill: Practical API Integration Playbook

This skill represents a medium-sized document that an engineering team might maintain to describe best practices for integrating with external APIs. The content is intentionally richer and longer than the previous skills, providing enough material for tests that compare token usage between metadata-only prompts and fully expanded skill prompts.

Establishing Clear Contracts

Before writing the first line of integration code, clarify the API contract:

  • Define which operations are required for the product's first release.
  • Identify rate limits, quota policies, and billing implications.
  • Capture authentication requirements in a short checklist.
  • Decide which fields are mandatory and which are optional.

These details should live in version-controlled documentation so that they can evolve alongside the code. Engineers can reference this skill while writing tests or reviewing changes to the integration layer.

Authentication and Secrets

Most APIs require some form of credential such as an API key, OAuth token, or signed JWT. Good practices include:

  1. Store secrets in a secure vault rather than in source control.
  2. Provide a lightweight helper that loads credentials from a single place.
  3. Rotate credentials regularly and document the rotation procedure.
  4. Log authentication failures with enough context to debug, but never log secrets.

When tests in this repository count tokens, they treat this section as part of the "full content" that is only loaded when the agent explicitly requests the medium‑sized skill.

Error Handling and Retries

API integrations fail in many subtle ways: network timeouts, malformed responses, authentication drift, and upstream outages. The integration layer should:

  • Distinguish between transient and permanent failures.
  • Use exponential backoff with jitter for retries.
  • Prefer idempotent operations when possible.
  • Surface clear error messages to both logs and users.

The goal is to avoid tight retry loops that amplify outages while still providing a smooth experience when brief network issues occur. Unit tests often simulate these failures by stubbing HTTP clients and asserting that the integration layer behaves as described here.

Pagination and Partial Results

Many APIs paginate large collections. Instead of loading every record at once, integrations should stream or page through results:

  • Respect server-provided cursors or continuation tokens.
  • Choose sensible default page sizes for the client.
  • Allow callers to stop early when they have enough data.
  • Validate that pagination state is not lost across retries.

By structuring the integration code around clear data flows and reusable helpers, teams can keep this logic understandable even when working with complex external APIs.