Add a community skill registry

.github/skills/community/README.md

@@ -0,0 +1,34 @@
+# Community Skills
+
+This directory is the **third-party skill registry** for Git-Ape. Anyone can
+contribute a skill here via pull request — you do not need to be a
+maintainer, and you do not need prior approval to open the PR.
+
+Community skills are **not** maintained by the Git-Ape team. Each skill must
+declare its own author (and, ideally, a source repository) so users know who
+to contact and where the canonical version lives.
+
+## How this differs from `.github/skills/<name>/`
+
+| | First-party (`.github/skills/<name>/`) | Community (`.github/skills/community/<name>/`) |
+|---|---|---|
+| Maintained by | Git-Ape team | The contributor / their org |
+| Required frontmatter | `name`, `description` | `name`, `description`, **`metadata.author`** |
+| Review bar | Maintainer review + full CI (structure, script lint, markdownlint) | **Same** — maintainer review + full CI |
+| Listed in | [Skill Registry](https://azure.github.io/git-ape/docs/skills/registry) as `first-party` | [Skill Registry](https://azure.github.io/git-ape/docs/skills/registry) as `community` |
+
+## Adding a skill here
+
+See [`CONTRIBUTING.md`](../../../CONTRIBUTING.md#contributing-a-community-skill)
+for the full process. In short:
+
+1. Copy [`.github/templates/COMMUNITY_SKILL.template.md`](../../templates/COMMUNITY_SKILL.template.md)
+   to `.github/skills/community/<your-skill-slug>/SKILL.md`.
+2. Fill in `metadata.author` (required) and, if you maintain the skill
+   elsewhere, `metadata.source`.
+3. Open a PR. It goes through the same review and CI checks as any
+   first-party skill.
+4. Once merged, `node scripts/generate-docs.js` picks it up automatically —
+   it appears in `.github/skills/registry.json` and the
+   [Skill Registry](https://azure.github.io/git-ape/docs/skills/registry) docs
+   page with no further registration step.

.github/skills/registry.json

@@ -0,0 +1,201 @@
+{
+  "$comment": "AUTO-GENERATED — DO NOT EDIT. Source: .github/skills/. Regenerate with `node scripts/generate-docs.js`.",
+  "schemaVersion": 1,
+  "skills": [
+    {
+      "name": "azure-cost-estimator",
+      "tier": "first-party",
+      "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. Use during template generation or when user asks about costs.",
+      "path": ".github/skills/azure-cost-estimator",
+      "docsUrl": "https://azure.github.io/git-ape/docs/skills/azure-cost-estimator",
+      "userInvocable": true,
+      "author": "Microsoft",
+      "license": "MIT",
+      "version": null,
+      "maturity": "stable",
+      "source": null
+    },
+    {
+      "name": "azure-deployment-preflight",
+      "tier": "first-party",
+      "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.",
+      "path": ".github/skills/azure-deployment-preflight",
+      "docsUrl": "https://azure.github.io/git-ape/docs/skills/azure-deployment-preflight",
+      "userInvocable": true,
+      "author": "Microsoft",
+      "license": "MIT",
+      "version": null,
+      "maturity": "stable",
+      "source": null
+    },
+    {
+      "name": "azure-drift-detector",
+      "tier": "first-party",
+      "description": "Detect configuration drift between deployed Azure resources and stored deployment state. Compare actual Azure configuration against desired state in .azure/deployments/, identify differences, and guide user through reconciliation options. Use when checking for manual changes, policy remediations, or unauthorized modifications.",
+      "path": ".github/skills/azure-drift-detector",
+      "docsUrl": "https://azure.github.io/git-ape/docs/skills/azure-drift-detector",
+      "userInvocable": true,
+      "author": "Microsoft",
+      "license": "MIT",
+      "version": null,
+      "maturity": "stable",
+      "source": null
+    },
+    {
+      "name": "azure-integration-tester",
+      "tier": "first-party",
+      "description": "Run post-deployment integration tests for Azure resources. Verify Function Apps, Storage Accounts, Databases, App Services are healthy and accessible. Use after successful Azure deployment.",
+      "path": ".github/skills/azure-integration-tester",
+      "docsUrl": "https://azure.github.io/git-ape/docs/skills/azure-integration-tester",
+      "userInvocable": true,
+      "author": "Microsoft",
+      "license": "MIT",
+      "version": null,
+      "maturity": "stable",
+      "source": null
+    },
+    {
+      "name": "azure-naming-research",
+      "tier": "first-party",
+      "description": "Research Azure naming constraints and CAF abbreviations for a given resource type. Use when you need to look up the official CAF slug, naming rules (length, scope, valid characters), and derive validation/cleaning regex patterns for an Azure resource. Triggers on: CAF abbreviation lookup, Azure naming rules research, resource naming constraints.",
+      "path": ".github/skills/azure-naming-research",
+      "docsUrl": "https://azure.github.io/git-ape/docs/skills/azure-naming-research",
+      "userInvocable": true,
+      "author": "Microsoft",
+      "license": "MIT",
+      "version": null,
+      "maturity": "stable",
+      "source": null
+    },
+    {
+      "name": "azure-policy-advisor",
+      "tier": "first-party",
+      "description": "Assess ARM template resources for Azure Policy compliance. Analyse the template, query existing subscription assignments via `az policy assignment list`, identify unassigned built-in and custom policies (CIS, NIST, FedRAMP), and emit a two-part report: template-fixable gaps (Part 1) and subscription-level policy assignments (Part 2). USE FOR: recommending Azure Policy assignments for an ARM template, auditing a subscription against CIS/NIST/general best practices, deciding which initiatives to assign at sub or management-group scope, distinguishing template-fixable vs platform-level governance gaps. DO NOT USE FOR: per-resource security configuration assessment (use azure-security-analyzer), RBAC role recommendations (use azure-role-selector), CAF naming abbreviations (use azure-naming-research), or pricing estimates (use azure-cost-estimator). INVOKES: az policy assignment list, az policy set-definition list, microsoft_docs_search, microsoft_docs_fetch.",
+      "path": ".github/skills/azure-policy-advisor",
+      "docsUrl": "https://azure.github.io/git-ape/docs/skills/azure-policy-advisor",
+      "userInvocable": true,
+      "author": "Microsoft",
+      "license": "MIT",
+      "version": null,
+      "maturity": "stable",
+      "source": null
+    },
+    {
+      "name": "azure-resource-availability",
+      "tier": "first-party",
+      "description": "Query live Azure APIs to validate resource availability before template generation or deployment. Checks VM SKU restrictions, Kubernetes/runtime version support, API version compatibility, and subscription quota. Use during requirements gathering and preflight to catch deployment failures early.",
+      "path": ".github/skills/azure-resource-availability",
+      "docsUrl": "https://azure.github.io/git-ape/docs/skills/azure-resource-availability",
+      "userInvocable": true,
+      "author": "Microsoft",
+      "license": "MIT",
+      "version": null,
+      "maturity": "stable",
+      "source": null
+    },
+    {
+      "name": "azure-resource-visualizer",
+      "tier": "first-party",
+      "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.",
+      "path": ".github/skills/azure-resource-visualizer",
+      "docsUrl": "https://azure.github.io/git-ape/docs/skills/azure-resource-visualizer",
+      "userInvocable": true,
+      "author": "Microsoft",
+      "license": "MIT",
+      "version": null,
+      "maturity": "stable",
+      "source": null
+    },
+    {
+      "name": "azure-rest-api-reference",
+      "tier": "first-party",
+      "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. No Azure connection required.",
+      "path": ".github/skills/azure-rest-api-reference",
+      "docsUrl": "https://azure.github.io/git-ape/docs/skills/azure-rest-api-reference",
+      "userInvocable": true,
+      "author": "Microsoft",
+      "license": "MIT",
+      "version": null,
+      "maturity": "stable",
+      "source": null
+    },
+    {
+      "name": "azure-role-selector",
+      "tier": "first-party",
+      "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.",
+      "path": ".github/skills/azure-role-selector",
+      "docsUrl": "https://azure.github.io/git-ape/docs/skills/azure-role-selector",
+      "userInvocable": true,
+      "author": "Microsoft",
+      "license": "MIT",
+      "version": null,
+      "maturity": "stable",
+      "source": null
+    },
+    {
+      "name": "azure-security-analyzer",
+      "tier": "first-party",
+      "description": "Analyze Azure resource configurations against security best practices using Azure MCP bestpractices service. Produces per-resource security assessment with severity ratings and recommendations. Use during template generation before deployment confirmation.",
+      "path": ".github/skills/azure-security-analyzer",
+      "docsUrl": "https://azure.github.io/git-ape/docs/skills/azure-security-analyzer",
+      "userInvocable": true,
+      "author": "Microsoft",
+      "license": "MIT",
+      "version": null,
+      "maturity": "stable",
+      "source": null
+    },
+    {
+      "name": "azure-stack-deploy",
+      "tier": "first-party",
+      "description": "Run an Azure Deployment Stack create (subscription scope) for a prepared Git-Ape deployment artifact and write state.json (schemaVersion 1.0). Use locally so the result matches the CI deploy workflow.",
+      "path": ".github/skills/azure-stack-deploy",
+      "docsUrl": "https://azure.github.io/git-ape/docs/skills/azure-stack-deploy",
+      "userInvocable": true,
+      "author": "Microsoft",
+      "license": "MIT",
+      "version": null,
+      "maturity": "stable",
+      "source": null
+    },
+    {
+      "name": "azure-stack-destroy",
+      "tier": "first-party",
+      "description": "Tear down a Git-Ape deployment by ID. Reads `state.json` under `.azure/deployments/<id>/` to delete the Azure Deployment Stack and purge soft-deleted Key Vault / Cognitive Services. Refuses to run without `state.json`. Use for any local CLI or VS Code Git-Ape teardown so the result matches the CI destroy workflow.",
+      "path": ".github/skills/azure-stack-destroy",
+      "docsUrl": "https://azure.github.io/git-ape/docs/skills/azure-stack-destroy",
+      "userInvocable": true,
+      "author": "Microsoft",
+      "license": "MIT",
+      "version": null,
+      "maturity": "stable",
+      "source": null
+    },
+    {
+      "name": "git-ape-onboarding",
+      "tier": "first-party",
+      "description": "Bootstrap a GitHub repository for Git-Ape CI/CD: Entra app registration, OIDC federated credentials, RBAC role assignments, GitHub environments (azure-deploy/azure-destroy), required secrets, and scaffold Actions workflow files — plus enterprise-wide distribution via a `.github-private` repo (managed-settings.json plugin standards + custom agents). USE FOR: first-time Git-Ape setup, new subscription onboarding, multi-environment (dev/staging/prod) setup, configure OIDC, federated credentials, RBAC setup, GitHub environments, scaffold workflow files, rolling Git-Ape out org/enterprise-wide. DO NOT USE FOR: deploying resources (use git-ape), drift detection alone, secret rotation.",
+      "path": ".github/skills/git-ape-onboarding",
+      "docsUrl": "https://azure.github.io/git-ape/docs/skills/git-ape-onboarding",
+      "userInvocable": true,
+      "author": "Microsoft",
+      "license": "MIT",
+      "version": null,
+      "maturity": "stable",
+      "source": null
+    },
+    {
+      "name": "prereq-check",
+      "tier": "first-party",
+      "description": "Validate Git-Ape CLI tool installation (az, gh, jq, git), versions, and auth sessions. Shows platform-specific install commands for anything missing. USE FOR: check Git-Ape prerequisites, what do I need to install for Git-Ape, verify Git-Ape CLI tools, az: command not found, gh: command not found, jq: command not found, git: command not found, az missing, gh missing, jq missing, git missing, fresh machine setup for Git-Ape, dev container setup for Git-Ape, before running git-ape-onboarding, az login required, gh auth login, auth expired, not logged in, outdated az version, minimum az version, upgrade az. DO NOT USE FOR: Anything else. This skill is narrowly scoped to prerequisites checks for Git-Ape's CLI tools and auth sessions. Do not use it for any other purpose.",
+      "path": ".github/skills/prereq-check",
+      "docsUrl": "https://azure.github.io/git-ape/docs/skills/prereq-check",
+      "userInvocable": true,
+      "author": "Git-Ape",
+      "license": "MIT",
+      "version": "0.1.0",
+      "maturity": "stable",
+      "source": null
+    }
+  ]
+}

.github/templates/COMMUNITY_SKILL.template.md

@@ -0,0 +1,90 @@
+<!-- markdownlint-disable -->
+
+---
+title: "Community skill scaffold template"
+description: "Copy this file to .github/skills/community/<slug>/SKILL.md and replace every <!-- TODO --> marker."
+---
+
+<!--
+  HOW TO USE THIS TEMPLATE
+  1. Copy this file to `.github/skills/community/<your-slug>/SKILL.md`
+     (rename, drop `.template`). Directory name must be kebab-case and
+     must match the `name:` field below exactly.
+  2. Remove this comment block and the `title:`/`description:` frontmatter
+     above — a real SKILL.md uses `name:` + `description:` + `metadata:`
+     frontmatter instead (see below).
+  3. Fill in `metadata.author` — REQUIRED for community skills. This is how
+     users know who built/maintains the skill. Use your GitHub handle,
+     org name, or a contact email.
+  4. If you maintain the canonical version of this skill in your own repo,
+     set `metadata.source` to that repo's URL so users can track updates
+     there. Omit it if this repo is the canonical home.
+  5. Set `metadata.maturity` to `experimental` (default) or `stable` once
+     you've used it in production for a while.
+  6. Replace every <!-- TODO --> marker in the body. This skill goes through
+     the same PR review and CI checks (structure validation, markdownlint,
+     script lint if it has scripts) as a first-party skill.
+
+  Required frontmatter for the real SKILL.md (replace the title/description
+  block above):
+
+  ---
+  name: <your-slug>
+  description: "One sentence describing what the skill does and when it fires. USE FOR: <trigger phrases>. DO NOT USE FOR: <out-of-scope cases>."
+  license: MIT
+  metadata:
+    author: <your GitHub handle, org, or contact>
+    source: <optional: URL of the repo where you maintain this skill>
+    maturity: experimental
+    version: "1.0.0"
+  ---
+-->
+
+# <!-- TODO: Skill Display Name -->
+
+> <!-- TODO: One-sentence value proposition. -->
+
+## When to Use
+
+<!-- TODO: Bullet list. Each bullet is a phrase a user would actually say. -->
+
+* <!-- TODO -->
+* <!-- TODO -->
+
+## Procedure
+
+<!-- TODO: Numbered, deterministic steps. A fresh model should be able to execute end-to-end with only this file (plus any scripts/references/ it links to) in context. -->
+
+### 1. <!-- TODO: First step name -->
+
+<!-- TODO: What to do, with which input, calling which tool. -->
+
+### 2. <!-- TODO: Second step name -->
+
+<!-- TODO -->
+
+### 3. <!-- TODO: Final step name -->
+
+<!-- TODO -->
+
+## Outputs
+
+<!-- TODO: The literal structure this skill is contracted to produce — table, JSON shape, or file path. -->
+
+## Constraints
+
+**Always:**
+
+* <!-- TODO -->
+
+**Never:**
+
+* <!-- TODO -->
+
+## Attribution
+
+* **Author:** <!-- TODO: same value as `metadata.author` above -->
+* **Source:** <!-- TODO: same value as `metadata.source`, or "This repository" -->
+* **Support:** <!-- TODO: where users should file issues for this skill (your repo's issue tracker, not Azure/git-ape) -->
+
+<!-- markdownlint-enable -->

.github/workflows/git-ape-docs-check.yml

@@ -40,15 +40,15 @@ jobs:
       - name: Check for stale docs
         id: diff
         run: |
-          if git diff --quiet website/docs/; then
+          if git diff --quiet website/docs/ .github/skills/registry.json; then
             echo "stale=false" >> "$GITHUB_OUTPUT"
             echo "✅ Generated docs are up to date"
           else
             echo "stale=true" >> "$GITHUB_OUTPUT"
             echo "⚠️ Generated docs are stale"
             echo ""
             echo "Changed files:"
-            git diff --name-only website/docs/
+            git diff --name-only website/docs/ .github/skills/registry.json
           fi
 
       - name: Comment on PR if stale
@@ -57,7 +57,7 @@ jobs:
         with:
           script: |
             const { execSync } = require('child_process');
-            const changedFiles = execSync('git diff --name-only website/docs/')
+            const changedFiles = execSync('git diff --name-only website/docs/ .github/skills/registry.json')
               .toString()
               .trim()
               .split('\n')