From 714f42cc2eae437441c6de549e8552d92e058b51 Mon Sep 17 00:00:00 2001
From: Pedro Rodrigues <pedro.rodrigues@supabase.io>
Date: Wed, 28 Jan 2026 12:00:10 +0000
Subject: [PATCH] fix: include subdirectory in reference paths in AGENTS.md

The build system now correctly preserves subdirectory paths when
generating the Available References section. For example, files in
references/db/ are now listed as references/db/file.md instead of
just references/file.md.

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
---
 packages/skills-build/src/build.ts |  8 ++++---
 skills/supabase/AGENTS.md          | 36 +++++++++++++++---------------
 2 files changed, 23 insertions(+), 21 deletions(-)

diff --git a/packages/skills-build/src/build.ts b/packages/skills-build/src/build.ts
index bb9561d..88afd33 100644
--- a/packages/skills-build/src/build.ts
+++ b/packages/skills-build/src/build.ts
@@ -8,7 +8,7 @@ import {
 	unlinkSync,
 	writeFileSync,
 } from "node:fs";
-import { basename, join } from "node:path";
+import { basename, join, relative } from "node:path";
 import {
 	discoverSkills,
 	getSkillPaths,
@@ -345,8 +345,10 @@ function buildSkill(paths: SkillPaths): void {
 		for (const file of referenceFiles) {
 			const name = basename(file, ".md");
 			const prefix = name.split("-")[0];
+			// Compute relative path from references directory
+			const relativePath = relative(paths.referencesDir, file);
 			const group = grouped.get(prefix) || [];
-			group.push(name);
+			group.push(relativePath);
 			grouped.set(prefix, group);
 		}
 
@@ -355,7 +357,7 @@ function buildSkill(paths: SkillPaths): void {
 			const title = section ? section.title : prefix;
 			output.push(`**${title}** (\`${prefix}-\`):`);
 			for (const file of files.sort()) {
-				output.push(`- \`references/${file}.md\``);
+				output.push(`- \`references/${file}\``);
 			}
 			output.push("");
 		}
diff --git a/skills/supabase/AGENTS.md b/skills/supabase/AGENTS.md
index fd0fd89..4f7832e 100644
--- a/skills/supabase/AGENTS.md
+++ b/skills/supabase/AGENTS.md
@@ -38,34 +38,34 @@ Reference files are named `{prefix}-{topic}.md` (e.g., `query-missing-indexes.md
 ## Available References
 
 **Connection Pooling** (`conn-`):
-- `references/conn-pooling.md`
+- `references/db/conn-pooling.md`
 
 **Migrations** (`migrations-`):
-- `references/migrations-diff.md`
-- `references/migrations-idempotent.md`
-- `references/migrations-testing.md`
+- `references/db/migrations-diff.md`
+- `references/db/migrations-idempotent.md`
+- `references/db/migrations-testing.md`
 
 **Performance** (`perf-`):
-- `references/perf-indexes.md`
-- `references/perf-query-optimization.md`
+- `references/db/perf-indexes.md`
+- `references/db/perf-query-optimization.md`
 
 **Row Level Security** (`rls-`):
-- `references/rls-common-mistakes.md`
-- `references/rls-mandatory.md`
-- `references/rls-performance.md`
-- `references/rls-policy-types.md`
-- `references/rls-views.md`
+- `references/db/rls-common-mistakes.md`
+- `references/db/rls-mandatory.md`
+- `references/db/rls-performance.md`
+- `references/db/rls-policy-types.md`
+- `references/db/rls-views.md`
 
 **Schema Design** (`schema-`):
-- `references/schema-auth-fk.md`
-- `references/schema-extensions.md`
-- `references/schema-jsonb.md`
-- `references/schema-realtime.md`
-- `references/schema-timestamps.md`
+- `references/db/schema-auth-fk.md`
+- `references/db/schema-extensions.md`
+- `references/db/schema-jsonb.md`
+- `references/db/schema-realtime.md`
+- `references/db/schema-timestamps.md`
 
 **Security** (`security-`):
-- `references/security-functions.md`
-- `references/security-service-role.md`
+- `references/db/security-functions.md`
+- `references/db/security-service-role.md`
 
 ---