diff --git a/website/docs/reference/ard.md b/website/docs/reference/ard.md new file mode 100644 index 0000000..a6c6e1d --- /dev/null +++ b/website/docs/reference/ard.md @@ -0,0 +1,72 @@ +--- +sidebar_position: 4 +--- + +# Agentic Resource Discovery (ARD) + +Git-Ape publishes an [ARD](https://agenticresourcediscovery.org) `ai-catalog.json` so that AI agents and tools that support Agentic Resource Discovery can automatically find and invoke Git-Ape skills. + +## What is ARD? + +Agentic Resource Discovery is an open protocol that lets AI agents discover skills and tools published by any team or organisation — similar to how DNS lets browsers discover websites. An AI agent can query an ARD catalog endpoint to find available skills, read their descriptions, and invoke them automatically. + +## Catalog Endpoint + +Git-Ape's catalog is published at: + +``` +https://azure.github.io/git-ape/.well-known/ai-catalog.json +``` + +The catalog lists all 15 Git-Ape skills. + +:::note +Git-Ape's docs are a GitHub Pages **project** site, so the catalog is served under the `/git-ape/` path prefix (as shown above) rather than at the `azure.github.io` domain root. Register the full URL above with your ARD-enabled agent or discovery service. +::: + +## Git-Ape Skills in the Catalog + +| Skill | Description | +|---|---| +| **Azure Cost Estimator** | Estimate monthly costs by querying the Azure Retail Prices API against ARM templates | +| **Azure Deployment Preflight** | What-if analysis, permission checks, and resource change preview before any deployment | +| **Azure Drift Detector** | Detect and reconcile configuration drift between deployed Azure resources and stored state | +| **Azure Integration Tester** | Post-deployment health checks for Function Apps, Storage, Databases, and App Services | +| **Azure Naming Research** | Look up CAF abbreviations, naming rules, and regex patterns for Azure resource types | +| **Azure Policy Advisor** | Assess ARM templates for CIS/NIST/FedRAMP policy gaps and subscription-level assignments | +| **Azure Resource Availability** | Validate VM SKUs, Kubernetes versions, API versions, and quota before deploying | +| **Azure Resource Visualizer** | Generate Mermaid architecture diagrams from live Azure resource groups | +| **Azure REST API Reference** | Look up exact property schemas, required fields, and stable API versions for any resource type | +| **Azure Role Selector** | Recommend least-privilege RBAC roles for managed identities and service principals | +| **Azure Security Analyzer** | Per-resource security assessment with severity ratings before deployment confirmation | +| **Azure Stack Deploy** | Run a subscription-scoped Azure Deployment Stack and write `state.json` | +| **Azure Stack Destroy** | Tear down a Git-Ape deployment and purge soft-deleted resources | +| **Git-Ape Onboarding** | Bootstrap Entra OIDC, RBAC, GitHub environments, and CI/CD workflow scaffolding | +| **Prerequisites Check** | Validate `az`, `gh`, `jq`, `git` installation and auth sessions | + +## Catalog Format + +The catalog follows the [ARD `ai-catalog.json` spec v1.0](https://agenticresourcediscovery.org): + +```json +{ + "specVersion": "1.0", + "host": { "displayName": "Azure Git-Ape", "identifier": "azure.github.io" }, + "entries": [ ... ], + "collections": [] +} +``` + +Each `entries[]` item includes `identifier`, `displayName`, `type: "application/ai-skill"`, `url` (the skill's `SKILL.md`), and a `description` derived from the skill's `SKILL.md` frontmatter (condensed for length). + +The `collections[]` array is ARD's federation mechanism — it links sub-catalogs by URL so a crawler can resolve them without inlining their entries. Git-Ape's catalog currently federates no external collections, so it ships as `"collections": []`. + +## Adding Git-Ape to an ARD-Enabled Agent + +If your AI agent or tool supports ARD discovery, register the catalog URL: + +``` +https://azure.github.io/git-ape/.well-known/ai-catalog.json +``` + +The agent will discover all 15 Git-Ape skills and their descriptions, and can invoke them via the GitHub Copilot skill invocation protocol. diff --git a/website/sidebars.ts b/website/sidebars.ts index 2b7d644..53f2972 100644 --- a/website/sidebars.ts +++ b/website/sidebars.ts @@ -103,6 +103,7 @@ const sidebars: SidebarsConfig = { 'reference/plugin-json', 'reference/marketplace', 'reference/arm-templates', + 'reference/ard', ], }, 'changelog', diff --git a/website/static/.well-known/ai-catalog.json b/website/static/.well-known/ai-catalog.json new file mode 100644 index 0000000..31b824a --- /dev/null +++ b/website/static/.well-known/ai-catalog.json @@ -0,0 +1,115 @@ +{ + "specVersion": "1.0", + "host": { + "displayName": "Azure Git-Ape", + "identifier": "azure.github.io" + }, + "entries": [ + { + "identifier": "urn:ai:github.com:azure:git-ape:azure-cost-estimator", + "displayName": "Azure Cost Estimator", + "type": "application/ai-skill", + "url": "https://github.com/Azure/git-ape/blob/main/.github/skills/azure-cost-estimator/SKILL.md", + "description": "Estimate monthly costs for Azure resources by querying the Azure Retail Prices API. Parses ARM templates to identify resources, SKUs, and regions, then looks up real retail pricing. Produces a per-resource cost breakdown with monthly totals." + }, + { + "identifier": "urn:ai:github.com:azure:git-ape:azure-deployment-preflight", + "displayName": "Azure Deployment Preflight", + "type": "application/ai-skill", + "url": "https://github.com/Azure/git-ape/blob/main/.github/skills/azure-deployment-preflight/SKILL.md", + "description": "Run preflight validation on ARM templates before deployment. Performs what-if analysis, permission checks, and generates a structured report with resource changes (create/modify/delete). Use before any deployment to preview changes and catch issues early." + }, + { + "identifier": "urn:ai:github.com:azure:git-ape:azure-drift-detector", + "displayName": "Azure Drift Detector", + "type": "application/ai-skill", + "url": "https://github.com/Azure/git-ape/blob/main/.github/skills/azure-drift-detector/SKILL.md", + "description": "Detect configuration drift between deployed Azure resources and stored deployment state. Compare actual Azure configuration against desired state, identify differences, and guide user through reconciliation options." + }, + { + "identifier": "urn:ai:github.com:azure:git-ape:azure-integration-tester", + "displayName": "Azure Integration Tester", + "type": "application/ai-skill", + "url": "https://github.com/Azure/git-ape/blob/main/.github/skills/azure-integration-tester/SKILL.md", + "description": "Run post-deployment integration tests for Azure resources. Verify Function Apps, Storage Accounts, Databases, and App Services are healthy and accessible. Use after successful Azure deployment." + }, + { + "identifier": "urn:ai:github.com:azure:git-ape:azure-naming-research", + "displayName": "Azure Naming Research", + "type": "application/ai-skill", + "url": "https://github.com/Azure/git-ape/blob/main/.github/skills/azure-naming-research/SKILL.md", + "description": "Research Azure naming constraints and CAF abbreviations for a given resource type. Look up the official CAF slug, naming rules (length, scope, valid characters), and derive validation and cleaning regex patterns for an Azure resource." + }, + { + "identifier": "urn:ai:github.com:azure:git-ape:azure-policy-advisor", + "displayName": "Azure Policy Advisor", + "type": "application/ai-skill", + "url": "https://github.com/Azure/git-ape/blob/main/.github/skills/azure-policy-advisor/SKILL.md", + "description": "Assess ARM template resources for Azure Policy compliance. Query existing subscription assignments, identify unassigned built-in and custom policies (CIS, NIST, FedRAMP), and emit a two-part report: template-fixable gaps and subscription-level policy assignments." + }, + { + "identifier": "urn:ai:github.com:azure:git-ape:azure-resource-availability", + "displayName": "Azure Resource Availability", + "type": "application/ai-skill", + "url": "https://github.com/Azure/git-ape/blob/main/.github/skills/azure-resource-availability/SKILL.md", + "description": "Query live Azure APIs to validate resource availability before template generation or deployment. Checks VM SKU restrictions, Kubernetes and runtime version support, API version compatibility, and subscription quota." + }, + { + "identifier": "urn:ai:github.com:azure:git-ape:azure-resource-visualizer", + "displayName": "Azure Resource Visualizer", + "type": "application/ai-skill", + "url": "https://github.com/Azure/git-ape/blob/main/.github/skills/azure-resource-visualizer/SKILL.md", + "description": "Analyze deployed Azure resource groups and generate detailed Mermaid architecture diagrams showing relationships between resources. Use for post-deployment visualization, understanding existing infrastructure, or documenting live Azure environments." + }, + { + "identifier": "urn:ai:github.com:azure:git-ape:azure-rest-api-reference", + "displayName": "Azure REST API Reference", + "type": "application/ai-skill", + "url": "https://github.com/Azure/git-ape/blob/main/.github/skills/azure-rest-api-reference/SKILL.md", + "description": "Look up Azure REST API and ARM template reference documentation for any resource type. Returns exact property schemas, required fields, valid values, and latest stable API versions. Use before generating or modifying ARM templates to ensure correctness." + }, + { + "identifier": "urn:ai:github.com:azure:git-ape:azure-role-selector", + "displayName": "Azure Role Selector", + "type": "application/ai-skill", + "url": "https://github.com/Azure/git-ape/blob/main/.github/skills/azure-role-selector/SKILL.md", + "description": "Recommend least-privilege Azure RBAC roles for deployed resources. Finds minimal built-in roles matching desired permissions or creates custom role definitions. Use during security analysis or when configuring access for service principals and managed identities." + }, + { + "identifier": "urn:ai:github.com:azure:git-ape:azure-security-analyzer", + "displayName": "Azure Security Analyzer", + "type": "application/ai-skill", + "url": "https://github.com/Azure/git-ape/blob/main/.github/skills/azure-security-analyzer/SKILL.md", + "description": "Analyze Azure resource configurations against security best practices. Produces per-resource security assessment with severity ratings and actionable recommendations. Use during template generation before deployment confirmation." + }, + { + "identifier": "urn:ai:github.com:azure:git-ape:azure-stack-deploy", + "displayName": "Azure Stack Deploy", + "type": "application/ai-skill", + "url": "https://github.com/Azure/git-ape/blob/main/.github/skills/azure-stack-deploy/SKILL.md", + "description": "Run an Azure Deployment Stack create at subscription scope for a prepared Git-Ape deployment artifact and write state.json. Use locally so the result matches the CI deploy workflow." + }, + { + "identifier": "urn:ai:github.com:azure:git-ape:azure-stack-destroy", + "displayName": "Azure Stack Destroy", + "type": "application/ai-skill", + "url": "https://github.com/Azure/git-ape/blob/main/.github/skills/azure-stack-destroy/SKILL.md", + "description": "Tear down a Git-Ape deployment by ID. Reads state.json to delete the Azure Deployment Stack and purge soft-deleted Key Vault and Cognitive Services resources. Matches the CI destroy workflow." + }, + { + "identifier": "urn:ai:github.com:azure:git-ape:git-ape-onboarding", + "displayName": "Git-Ape Onboarding", + "type": "application/ai-skill", + "url": "https://github.com/Azure/git-ape/blob/main/.github/skills/git-ape-onboarding/SKILL.md", + "description": "Bootstrap a GitHub repository for Git-Ape CI/CD: Entra app registration, OIDC federated credentials, RBAC role assignments, GitHub environments, required secrets, and scaffold Actions workflow files for Azure deployments." + }, + { + "identifier": "urn:ai:github.com:azure:git-ape:prereq-check", + "displayName": "Prerequisites Check", + "type": "application/ai-skill", + "url": "https://github.com/Azure/git-ape/blob/main/.github/skills/prereq-check/SKILL.md", + "description": "Validate Git-Ape CLI tool installation (az, gh, jq, git), versions, and auth sessions. Shows platform-specific install commands for anything missing. Use before first-time onboarding or when a command-not-found error occurs." + } + ], + "collections": [] +}