LLMs and AI agents¶
Wingpy makes it easy to use Large Language Models ( AI / LLM ) for automation. It provides a skill for your agent.
This ensures that the agent:
- uses the correct wingpy client
- uses correct syntax
- uses environment variables
- checks the latest documentation before writing code
- knows how to adjust logging levels
- how wingpy uses error handling
- and much more...
Using the skill¶
Start by adding the skill to your project. You can do this with the quick setup or the manual setup instructions below.
Then simply ask the agent to use the skill in your chat window. For example:
Prompt template
Using the skill in ./wingpy-coding-skill, write a script that [describe your task here]
The generated files (manifest.json and SKILL.md) contain instructions for the agent.
Quick setup¶
You can generate the wingpy-coding-skill skill folder with the following command, if you have a active Python venv and wingpy installed:
optionally you can specify the folder of the skill:
We recommend to simply add the skill in your root folder of a new project. This makes for a flow like this:
Now you can open an editor like Visual Studio Code and start editing the main.py file. Open your chat window and select "agent".
Manual setup¶
If you prefer you can copy it from the code-blocks below.
Create a folder like wingpy-coding-skill in your project folder root and add the following files:
SKILL.md file¶
SKILL.md
---
name: wingpy-coding-skill
description: 'Use when writing, testing, documenting, reviewing, or generating code that imports wingpy, selects a wingpy client, or automates APIC, Catalyst Center, vManage, FMC, Hyperfabric, ISE, Meraki Dashboard, Modeling Labs, Nautobot, NetBox, Nexus Dashboard, or Splunk Enterprise.'
---
> 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.
- Cisco APIC: `wingpy.CiscoAPIC`
Guide: [Cisco APIC User Guide](https://wingpy.automation.wingmen.dk/user-guide/apic/)
API: [Cisco APIC API Reference](https://wingpy.automation.wingmen.dk/api/apic/)
- Cisco Catalyst Center: `wingpy.CiscoCatalystCenter`
Guide: [Cisco Catalyst Center User Guide](https://wingpy.automation.wingmen.dk/user-guide/catalyst-center/)
API: [Cisco Catalyst Center API Reference](https://wingpy.automation.wingmen.dk/api/catalyst-center/)
- Cisco Catalyst SD-WAN vManage: `wingpy.CiscoVmanage`
Guide: [Cisco Catalyst SD-WAN vManage User Guide](https://wingpy.automation.wingmen.dk/user-guide/vmanage/)
API: [Cisco Catalyst SD-WAN vManage API Reference](https://wingpy.automation.wingmen.dk/api/vmanage/)
- Cisco FMC: `wingpy.CiscoFMC`
Guide: [Cisco FMC User Guide](https://wingpy.automation.wingmen.dk/user-guide/fmc/)
API: [Cisco FMC API Reference](https://wingpy.automation.wingmen.dk/api/fmc/)
- Cisco Hyperfabric: `wingpy.CiscoHyperfabric`
Guide: [Cisco Hyperfabric User Guide](https://wingpy.automation.wingmen.dk/user-guide/hyperfabric/)
API: [Cisco Hyperfabric API Reference](https://wingpy.automation.wingmen.dk/api/hyperfabric/)
- Cisco ISE: `wingpy.CiscoISE`
Guide: [Cisco ISE User Guide](https://wingpy.automation.wingmen.dk/user-guide/ise/)
API: [Cisco ISE API Reference](https://wingpy.automation.wingmen.dk/api/ise/)
- Cisco Meraki Dashboard: `wingpy.CiscoMerakiDashboard`
Guide: [Cisco Meraki Dashboard User Guide](https://wingpy.automation.wingmen.dk/user-guide/meraki-dashboard/)
API: [Cisco Meraki Dashboard API Reference](https://wingpy.automation.wingmen.dk/api/meraki-dashboard/)
- Cisco Modeling Labs: `wingpy.CiscoModelingLabs`
Guide: [Cisco Modeling Labs User Guide](https://wingpy.automation.wingmen.dk/user-guide/cml/)
API: [Cisco Modeling Labs API Reference](https://wingpy.automation.wingmen.dk/api/cml/)
- Nautobot: `wingpy.Nautobot`
Guide: [Nautobot User Guide](https://wingpy.automation.wingmen.dk/user-guide/nautobot/)
API: [Nautobot API Reference](https://wingpy.automation.wingmen.dk/api/nautobot/)
- NetBox: `wingpy.NetBox`
Guide: [NetBox User Guide](https://wingpy.automation.wingmen.dk/user-guide/netbox/)
API: [NetBox API Reference](https://wingpy.automation.wingmen.dk/api/netbox/)
- Cisco Nexus Dashboard: `wingpy.CiscoNexusDashboard`
Guide: [Cisco Nexus Dashboard User Guide](https://wingpy.automation.wingmen.dk/user-guide/nexus-dashboard/)
API: [Cisco Nexus Dashboard API Reference](https://wingpy.automation.wingmen.dk/api/nexus-dashboard/)
- Splunk Enterprise: `wingpy.SplunkEnterprise`
Guide: [Splunk Enterprise User Guide](https://wingpy.automation.wingmen.dk/user-guide/splunk/)
API: [Splunk Enterprise API Reference](https://wingpy.automation.wingmen.dk/api/splunk/)
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:
- General getting started: [User Guide](https://wingpy.automation.wingmen.dk/user-guide/)
The User Guide contains sections on authentication, logging, error handling, concurrency, and other cross-cutting concerns that apply to all clients.
It also contains client-specific sections with usage patterns and examples. It constitutes the idiomatic way to use Wingpy and should be consulted before the API reference.
- FAQ overview: [FAQ](https://wingpy.automation.wingmen.dk/faq/)
Can be consulted for specific questions.
- Environment variables: [FAQ: Environment Variables](https://wingpy.automation.wingmen.dk/faq/#environment-variables)
- Path building: [FAQ: Path Building](https://wingpy.automation.wingmen.dk/faq/#path-building)
- Base client behavior: [Base API Reference](https://wingpy.automation.wingmen.dk/api/base/)
- Exceptions: [Exceptions API Reference](https://wingpy.automation.wingmen.dk/api/exceptions/)
- Responses: [Responses API Reference](https://wingpy.automation.wingmen.dk/api/responses/)
- Scheduling and concurrency: [Scheduling API Reference](https://wingpy.automation.wingmen.dk/api/scheduling/)
Refer to the general guidance found in the User Guide.
## 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.
manifest.json file¶
manifest.json
{
"clients": [
{
"api_url": "https://wingpy.automation.wingmen.dk/api/apic/",
"auth_mode": "session",
"automatically_uses_environment_variables": true,
"client_class": "wingpy.CiscoAPIC",
"environment_variables": [
{
"description": "Username for Cisco APIC authentication",
"name": "WINGPY_APIC_USERNAME"
},
{
"description": "Password for Cisco APIC authentication",
"name": "WINGPY_APIC_PASSWORD"
},
{
"description": "Hostname or IP address of the Cisco APIC controller",
"name": "WINGPY_APIC_BASE_URL"
}
],
"guide_url": "https://wingpy.automation.wingmen.dk/user-guide/apic/",
"platform": "Cisco APIC",
"rest_api_docs_url": "https://developer.cisco.com/docs/search/?q=APIC",
"supports_get_all": true,
"supports_path_params": true,
"supports_token_refresh": true
},
{
"api_url": "https://wingpy.automation.wingmen.dk/api/catalyst-center/",
"auth_mode": "session",
"automatically_uses_environment_variables": true,
"client_class": "wingpy.CiscoCatalystCenter",
"environment_variables": [
{
"description": "Username for Cisco Catalyst Center authentication",
"name": "WINGPY_CATALYST_CENTER_USERNAME"
},
{
"description": "Password for Cisco Catalyst Center authentication",
"name": "WINGPY_CATALYST_CENTER_PASSWORD"
},
{
"description": "Hostname or IP address of the Cisco Catalyst Center controller",
"name": "WINGPY_CATALYST_CENTER_BASE_URL"
}
],
"guide_url": "https://wingpy.automation.wingmen.dk/user-guide/catalyst-center/",
"platform": "Cisco Catalyst Center",
"rest_api_docs_url": "https://developer.cisco.com/docs/search/?q=Catalyst%20Center",
"supports_get_all": true,
"supports_path_params": true,
"supports_token_refresh": true
},
{
"api_url": "https://wingpy.automation.wingmen.dk/api/vmanage/",
"auth_mode": "session",
"automatically_uses_environment_variables": true,
"client_class": "wingpy.CiscoVmanage",
"environment_variables": [
{
"description": "Username for Cisco vManage authentication",
"name": "WINGPY_VMANAGE_USERNAME"
},
{
"description": "Password for Cisco vManage authentication",
"name": "WINGPY_VMANAGE_PASSWORD"
},
{
"description": "Hostname or IP address of the Cisco vManage controller",
"name": "WINGPY_VMANAGE_BASE_URL"
}
],
"guide_url": "https://wingpy.automation.wingmen.dk/user-guide/vmanage/",
"platform": "Cisco Catalyst SD-WAN vManage",
"rest_api_docs_url": "https://developer.cisco.com/docs/search/?q=vManage",
"supports_get_all": true,
"supports_path_params": true,
"supports_token_refresh": true
},
{
"api_url": "https://wingpy.automation.wingmen.dk/api/fmc/",
"auth_mode": "session",
"automatically_uses_environment_variables": true,
"client_class": "wingpy.CiscoFMC",
"environment_variables": [
{
"description": "Username for Cisco FMC authentication",
"name": "WINGPY_FMC_USERNAME"
},
{
"description": "Password for Cisco FMC authentication",
"name": "WINGPY_FMC_PASSWORD"
},
{
"description": "Hostname or IP address of the Cisco FMC controller",
"name": "WINGPY_FMC_BASE_URL"
}
],
"guide_url": "https://wingpy.automation.wingmen.dk/user-guide/fmc/",
"platform": "Cisco FMC",
"rest_api_docs_url": "https://www.cisco.com/c/en/us/support/security/defense-center/products-programming-reference-guides-list.html",
"supports_get_all": true,
"supports_path_params": true,
"supports_token_refresh": true
},
{
"api_url": "https://wingpy.automation.wingmen.dk/api/hyperfabric/",
"auth_mode": "external-token",
"automatically_uses_environment_variables": true,
"client_class": "wingpy.CiscoHyperfabric",
"environment_variables": [
{
"description": "API key for Cisco Hyperfabric authentication",
"name": "WINGPY_HYPERFABRIC_TOKEN"
}
],
"guide_url": "https://wingpy.automation.wingmen.dk/user-guide/hyperfabric/",
"platform": "Cisco Hyperfabric",
"rest_api_docs_url": "https://developer.cisco.com/docs/hyperfabric/",
"supports_get_all": true,
"supports_path_params": true,
"supports_token_refresh": false
},
{
"api_url": "https://wingpy.automation.wingmen.dk/api/ise/",
"auth_mode": "session",
"automatically_uses_environment_variables": true,
"client_class": "wingpy.CiscoISE",
"environment_variables": [
{
"description": "Username for Cisco ISE authentication",
"name": "WINGPY_ISE_USERNAME"
},
{
"description": "Password for Cisco ISE authentication",
"name": "WINGPY_ISE_PASSWORD"
},
{
"description": "Hostname or IP address of the Cisco ISE controller",
"name": "WINGPY_ISE_BASE_URL"
}
],
"guide_url": "https://wingpy.automation.wingmen.dk/user-guide/ise/",
"platform": "Cisco ISE",
"rest_api_docs_url": "https://developer.cisco.com/docs/search/?q=Identity+Services+Engine",
"supports_get_all": true,
"supports_path_params": true,
"supports_token_refresh": true
},
{
"api_url": "https://wingpy.automation.wingmen.dk/api/meraki-dashboard/",
"auth_mode": "external-token",
"automatically_uses_environment_variables": true,
"client_class": "wingpy.CiscoMerakiDashboard",
"environment_variables": [
{
"description": "API key for Cisco Meraki Dashboard authentication",
"name": "WINGPY_MERAKI_DASHBOARD_TOKEN"
},
{
"description": "Name of the organization to manage in Cisco Meraki Dashboard",
"name": "WINGPY_MERAKI_DASHBOARD_ORG_NAME"
}
],
"guide_url": "https://wingpy.automation.wingmen.dk/user-guide/meraki-dashboard/",
"platform": "Cisco Meraki Dashboard",
"rest_api_docs_url": "https://developer.cisco.com/docs/search/?q=Meraki+Dashboard",
"supports_get_all": true,
"supports_path_params": true,
"supports_token_refresh": false
},
{
"api_url": "https://wingpy.automation.wingmen.dk/api/cml/",
"auth_mode": "session",
"automatically_uses_environment_variables": true,
"client_class": "wingpy.CiscoModelingLabs",
"environment_variables": [
{
"description": "Username for Cisco Modeling Labs authentication",
"name": "WINGPY_CML_USERNAME"
},
{
"description": "Password for Cisco Modeling Labs authentication",
"name": "WINGPY_CML_PASSWORD"
},
{
"description": "Hostname or IP address of the Cisco Modeling Labs controller",
"name": "WINGPY_CML_BASE_URL"
}
],
"guide_url": "https://wingpy.automation.wingmen.dk/user-guide/cml/",
"platform": "Cisco Modeling Labs",
"rest_api_docs_url": "https://developer.cisco.com/docs/search/?q=Cisco+Modeling+Labs",
"supports_get_all": true,
"supports_path_params": true,
"supports_token_refresh": true
},
{
"api_url": "https://wingpy.automation.wingmen.dk/api/nautobot/",
"auth_mode": "external-token",
"automatically_uses_environment_variables": true,
"client_class": "wingpy.Nautobot",
"environment_variables": [
{
"description": "API key for Nautobot authentication",
"name": "WINGPY_NAUTOBOT_TOKEN"
},
{
"description": "Hostname or IP address of the Nautobot controller",
"name": "WINGPY_NAUTOBOT_BASE_URL"
}
],
"guide_url": "https://wingpy.automation.wingmen.dk/user-guide/nautobot/",
"platform": "Nautobot",
"supports_get_all": true,
"supports_path_params": true,
"supports_token_refresh": false
},
{
"api_url": "https://wingpy.automation.wingmen.dk/api/netbox/",
"auth_mode": "external-token",
"automatically_uses_environment_variables": true,
"client_class": "wingpy.NetBox",
"environment_variables": [
{
"description": "API key for NetBox authentication",
"name": "WINGPY_NETBOX_TOKEN"
},
{
"description": "Hostname or IP address of the NetBox controller",
"name": "WINGPY_NETBOX_BASE_URL"
}
],
"guide_url": "https://wingpy.automation.wingmen.dk/user-guide/netbox/",
"platform": "NetBox",
"supports_get_all": true,
"supports_path_params": true,
"supports_token_refresh": false
},
{
"api_url": "https://wingpy.automation.wingmen.dk/api/nexus-dashboard/",
"auth_mode": "session",
"automatically_uses_environment_variables": true,
"client_class": "wingpy.CiscoNexusDashboard",
"environment_variables": [
{
"description": "Username for Cisco Nexus Dashboard authentication",
"name": "WINGPY_NEXUS_DASHBOARD_USERNAME"
},
{
"description": "Password for Cisco Nexus Dashboard authentication",
"name": "WINGPY_NEXUS_DASHBOARD_PASSWORD"
},
{
"description": "Hostname or IP address of the Cisco Nexus Dashboard controller",
"name": "WINGPY_NEXUS_DASHBOARD_BASE_URL"
}
],
"guide_url": "https://wingpy.automation.wingmen.dk/user-guide/nexus-dashboard/",
"platform": "Cisco Nexus Dashboard",
"rest_api_docs_url": "https://developer.cisco.com/docs/search/?q=Nexus+Dashboard",
"supports_get_all": true,
"supports_path_params": true,
"supports_token_refresh": true
},
{
"api_url": "https://wingpy.automation.wingmen.dk/api/splunk/",
"auth_mode": "session",
"automatically_uses_environment_variables": true,
"client_class": "wingpy.SplunkEnterprise",
"environment_variables": [
{
"description": "Username for Splunk Enterprise authentication",
"name": "WINGPY_SPLUNK_ENTERPRISE_USERNAME"
},
{
"description": "Password for Splunk Enterprise authentication",
"name": "WINGPY_SPLUNK_ENTERPRISE_PASSWORD"
},
{
"description": "Hostname or IP address of the Splunk Enterprise controller",
"name": "WINGPY_SPLUNK_ENTERPRISE_BASE_URL"
}
],
"guide_url": "https://wingpy.automation.wingmen.dk/user-guide/splunk/",
"platform": "Splunk Enterprise",
"rest_api_docs_url": "https://docs.splunk.com/Documentation/Splunk/latest/RESTREF/RESTprolog",
"supports_get_all": true,
"supports_path_params": true,
"supports_token_refresh": true
}
],
"documentation": {
"api_reference_url": "https://wingpy.automation.wingmen.dk/api/",
"changelog_url": "https://wingpy.automation.wingmen.dk/changelog/",
"faq_url": "https://wingpy.automation.wingmen.dk/faq/",
"home_url": "https://wingpy.automation.wingmen.dk/",
"llms_full_url": "https://wingpy.automation.wingmen.dk/llms-full.txt",
"llms_url": "https://wingpy.automation.wingmen.dk/llms.txt",
"user_guide_url": "https://wingpy.automation.wingmen.dk/user-guide/"
},
"rules": {
"avoid_assuming_token_refresh_for_external_tokens": true,
"avoid_guessing_undocumented_methods": true,
"avoid_manual_pagination_when_get_all_is_available": true,
"avoid_raw_http_when_wingpy_supports_task": true,
"avoid_unnecessary_abstraction": true,
"prefer_documented_vendor_paths": true,
"prefer_environment_variables_for_reusable_examples": true,
"prefer_platform_specific_clients": true
},
"schema_version": "1.0",
"shared_capabilities": {
"concurrency_entrypoints": [
"client.tasks.schedule",
"client.tasks.run"
],
"context_manager_cleanup": true,
"path_params": true,
"rate_limit_handling": true,
"request_retries": true,
"response_wrappers": [
"wingpy.ResponseMapping",
"wingpy.ResponseSequence",
"wingpy.XMLResponseMapping"
]
},
"skill": {
"description": "Operational guidance and capability metadata for coding agents that write or review code using the wingpy Python library.",
"human_document": "SKILL.md",
"machine_manifest": "manifest.json",
"name": "wingpy-coding-skill"
}
}