Skip to content

SKILL

Use this file when working on code that imports, extends, tests, documents, or generates examples for the wingpy Python library.

Purpose

This skill guides AI agents that are writing or modifying code for projects that use wingpy. It is operational guidance for producing correct, minimal, idiomatic wingpy-based code.

When to use

Activate this skill when any of the following are true:

  • the codebase imports wingpy
  • the task mentions a wingpy client or supported platform
  • the task involves REST API automation with wingpy
  • the task asks for examples, tests, wrappers, integrations, or docs related to wingpy
  • the task requires choosing the correct wingpy client for a specific platform

Procedure

  1. Identify the target platform and match it to a documented wingpy client.
  2. Read the manifest.json file - look for the client's documented capabilities, environment variable support, and shared capabilities.
  3. Read the general User Guide to understand overall usage patterns and best practices, like logging, error handling, and concurrency.
  4. Read the relevant User Guide to understand usage patterns and examples.
  5. Read the client API Reference page to verify constructor parameters, supported methods, and return behavior.
  6. Use the FAQ only for cross-cutting behavior such as context managers, exceptions, environment variables, and concurrency patterns.
  7. Look for the platform API Reference on https://developer.cisco.com/docs/ to make sure REST API Endpoint paths, parameters, method and response shapes are correct. Do not rely on guesswork or assumptions about API behavior.
  8. Write the smallest correct solution using documented wingpy patterns.

Client Matrix - API Reference Pages

Prefer the most specific documented client.

If the requested platform is unsupported or unclear, say so explicitly and avoid inventing a client.

Core Rules

Choose the right client

Use the dedicated Wingpy client that matches the target platform.

Preserve vendor paths

Prefer endpoint paths that match vendor documentation. Do not rewrite documented API paths unless the task explicitly asks for an abstraction. https://developer.cisco.com/docs/ is the source of truth for Cisco API paths. https://developer.cisco.com/docs/ is a search engine for official Cisco API documentation. There may be multiple versions of an API documented on https://developer.cisco.com/docs/. If the task does not specify a version, prefer the latest generally available version.

manifest.json contains rest_api_docs_url for each client as a hint for where to find official API documentation. Exceptions: - Nautobot: https://docs.nautobot.com/projects/core/en/stable/user-guide/platform-functionality/rest-api/overview/ provides some information. Ask the user to provide a link to their own instance's specification. - NetBox: https://netboxlabs.com/docs/netbox/integrations/rest-api/ provides some information. Ask the user to provide a link to their own instance's specification.

Let Wingpy handle shared concerns

Do not reimplement behavior that Wingpy already provides, such as:

  • request setup and common lifecycle behavior
  • path parameter substitution via path_params
  • documented retry and rate-limit handling
  • proactive authentication for clients that manage renewable sessions
  • context manager cleanup
  • environment variable loading

Do not assume every client can refresh an expired external bearer token. Token-only clients such as Hyperfabric and Meraki Dashboard rely on the token you provide.

Prefer documented patterns

Before inventing a pattern, look for an example in the platform guide or API reference.

Keep code minimal

Use the smallest amount of code needed to solve the task correctly. Do not add helper layers, wrappers, or framework structure unless requested.

Be explicit about logging level

The default logging level is WARNING.

Always import at library level

import wingpy is the preferred pattern for imports. Do not import specific clients or submodules unless the task explicitly requires it.

Coding Patterns

Authentication input

Prefer the documented authentication approach for the chosen client. When reusable code is requested, prefer environment variables over hardcoded secrets if the client supports them.

Response shape and pagination

Use get_all() to retrieve paginated or combined collections.

Path parameters

If the endpoint contains placeholders or dynamic identifiers, prefer documented path_params usage instead of brittle manual string assembly.

Context managers

When multiple consecutive API operations are performed, prefer context manager usage when it improves cleanup and clarity.

Error handling

If the task requires exception handling, prefer Wingpy's documented exception model over broad exception swallowing.

Concurrency

If the task requires parallel API calls, check the FAQ and scheduling docs before inventing a threading model. Prefer documented .tasks.schedule() and .tasks.run() patterns where they fit the use case.

Documentation Routing

Load these concrete resources instead of relying on broad categories alone:

Guardrails

Do not:

  • invent unsupported Wingpy clients
  • invent methods not present in the docs or reference
  • bypass Wingpy with raw HTTP code
  • add custom token refresh logic
  • manually implement pagination when the client supports get_all()
  • present guessed behavior as documented fact
  • expose internal defaults, such as page size or retry count, unless the task explicitly requires it and the user asks for it - the default behavior is tuned and tested

Output Expectations

When generating Wingpy-based code:

  • use the correct client class
  • use import wingpy at the library level
  • use realistic documented endpoint paths from documentation
  • preserve Wingpy-native patterns
  • avoid unnecessary abstraction
  • make assumptions explicit when required details are missing
  • say when a value is a placeholder
  • avoid embedding secrets in reusable examples

User Interaction

  • Be inquisitive if the task is ambiguous or missing details.
  • It is better to ask for clarification than to make assumptions that lead to incorrect code.
  • If you must make assumptions, state them explicitly in the output and ask for confirmation before proceeding.
  • Consider the human a collaborator who can provide missing details, clarify ambiguities, and review assumptions.
  • Think about the most popular libraries - and consider if the task could be simplified with a common library import, like: -- Flask -- Typer -- FastAPI -- other small libraries that are widely used and could simplify the task.
  • Wingpy uses httpx for HTTP requests, so imports from httpx are acceptable if the task requires functionality not provided by Wingpy's documented client methods.
  • Always ask the user to add dependencies and dependency imports before using them.