fix: move reference files to ref/ subdirectories

Moves progressive discovery reference files (auth.md, storage.md, etc.)
to ref/ subdirectories within azcli/ and gcloud/ to avoid pi detecting
them as separate incomplete skills.

Structure:
  azcli/
  ├── SKILL.md         ← hub
  └── ref/             ← reference docs
      ├── auth.md
      ├── storage.md
      └── ...

Updated hub files (azcli/SKILL.md, gcloud/SKILL.md) to reference ref/*.md.

Verified:
- skills add still finds 8/8 skills ✅
- All internal references intact (gcloud/ref/iam.md → auth.md works)
- No broken links

Co-Authored-By: Pi <noreply@pi.dev>

Author: marcfargas

.changeset/flatten-directory-structure.md

@@ -4,7 +4,17 @@
 
 Flatten directory structure for skills CLI compatibility.
 
-All skills are now at the top level (e.g., `azcli/`, `gcloud/`) instead of nested in category folders (`azure/azcli/`, `google-cloud/gcloud/`). This allows `npx skills add marcfargas/skills` to discover all 8 skills without the `--full-depth` flag.
+All skills are now at the top level (e.g., `azcli/`, `gcloud/`) instead of nested in category folders (`azure/azcli/`, `google-cloud/gcloud/`). Progressive discovery reference files moved to `ref/` subdirectories to prevent pi from detecting them as separate skills.
 
-**Before:** 1/8 skills found by default  
-**After:** 8/8 skills found by default
+**Before:** 1/8 skills found by default (npx skills add)  
+**After:** 8/8 skills found by default ✅
+
+**Structure:**
+```
+azcli/
+├── SKILL.md       ← hub (150 lines)
+└── ref/           ← loaded on demand
+    ├── auth.md
+    ├── storage.md
+    └── ...
+```

azcli/SKILL.md

@@ -74,13 +74,13 @@ Key global flags: `--subscription`, `--output` (`-o`), `--query`, `--verbose`, `
 
 | Service | File | Key Commands |
 |---------|------|-------------|
-| Auth & Config | [auth.md](auth.md) | Login, service principals, managed identities, subscriptions, config |
-| IAM & Resources | [iam.md](iam.md) | Resource groups, RBAC, Entra ID (Azure AD), Key Vault |
-| Compute & Networking | [compute.md](compute.md) | VMs, VNets, NSGs, DNS, load balancers, monitoring |
-| Serverless & Containers | [serverless.md](serverless.md) | App Service, Functions, Container Apps, AKS, Container Registry |
-| Storage | [storage.md](storage.md) | Storage accounts, blobs, file shares, queues, tables |
-| Data | [data.md](data.md) | SQL Database, Cosmos DB, Service Bus, Event Hubs |
-| Automation & CI/CD | [automation.md](automation.md) | Scripting, output formats, JMESPath, Bicep/ARM, GitHub Actions |
+| Auth & Config | [auth.md](ref/auth.md) | Login, service principals, managed identities, subscriptions, config |
+| IAM & Resources | [iam.md](ref/iam.md) | Resource groups, RBAC, Entra ID (Azure AD), Key Vault |
+| Compute & Networking | [compute.md](ref/compute.md) | VMs, VNets, NSGs, DNS, load balancers, monitoring |
+| Serverless & Containers | [serverless.md](ref/serverless.md) | App Service, Functions, Container Apps, AKS, Container Registry |
+| Storage | [storage.md](ref/storage.md) | Storage accounts, blobs, file shares, queues, tables |
+| Data | [data.md](ref/data.md) | SQL Database, Cosmos DB, Service Bus, Event Hubs |
+| Automation & CI/CD | [automation.md](ref/automation.md) | Scripting, output formats, JMESPath, Bicep/ARM, GitHub Actions |
 
 **Read the per-service file for full command reference.**
 

azcli/auth.md azcli/ref/auth.mdazcli/auth.md renamed to azcli/ref/auth.md

@@ -71,13 +71,13 @@ Key global flags: `--project`, `--format`, `--filter`, `--limit`, `--quiet`, `--
 
 | Service | File | Key Commands |
 |---------|------|-------------|
-| Auth & Config | [auth.md](auth.md) | Login, ADC, impersonation, config profiles |
-| IAM & Projects | [iam.md](iam.md) | Projects, APIs, service accounts, Secret Manager |
-| Compute & Networking | [compute.md](compute.md) | VMs, SSH, firewall, VPC, DNS, static IPs |
-| Serverless | [serverless.md](serverless.md) | Cloud Run, Functions, App Engine, Scheduler, Tasks |
-| Storage & Artifacts | [storage.md](storage.md) | gcloud storage, Artifact Registry |
-| Data | [data.md](data.md) | Cloud SQL, BigQuery (bq), Pub/Sub |
-| Automation & CI/CD | [automation.md](automation.md) | Scripting, output formats, filtering, GitHub Actions, operations |
+| Auth & Config | [auth.md](ref/auth.md) | Login, ADC, impersonation, config profiles |
+| IAM & Projects | [iam.md](ref/iam.md) | Projects, APIs, service accounts, Secret Manager |
+| Compute & Networking | [compute.md](ref/compute.md) | VMs, SSH, firewall, VPC, DNS, static IPs |
+| Serverless | [serverless.md](ref/serverless.md) | Cloud Run, Functions, App Engine, Scheduler, Tasks |
+| Storage & Artifacts | [storage.md](ref/storage.md) | gcloud storage, Artifact Registry |
+| Data | [data.md](ref/data.md) | Cloud SQL, BigQuery (bq), Pub/Sub |
+| Automation & CI/CD | [automation.md](ref/automation.md) | Scripting, output formats, filtering, GitHub Actions, operations |
 
 **Read the per-service file for full command reference.**