From c07c2346015b926651da116732cb4c116b11a6a9 Mon Sep 17 00:00:00 2001
From: Pedro Rodrigues <pedro.rodrigues@supabase.io>
Date: Wed, 28 Jan 2026 15:53:34 +0000
Subject: [PATCH] fix: remove CLAUDE.md symlink generation from build

The CLAUDE.md symlink causes installation errors when using
`npx skills add` as it tries to copy AGENTS.md to itself.

- Remove createClaudeSymlink function from build.ts
- Remove claudeSymlink from SkillPaths interface
- Remove CLAUDE.md references from AGENTS.md structure documentation
- Delete existing CLAUDE.md symlink from skills directory

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
---
 AGENTS.md                                     |  1 -
 packages/skills-build/src/build.ts            | 27 -------------------
 packages/skills-build/src/config.ts           |  2 --
 .../AGENTS.md                                 |  3 ---
 .../CLAUDE.md                                 |  1 -
 5 files changed, 34 deletions(-)
 delete mode 120000 skills/supabase-postgres-best-practices/CLAUDE.md

diff --git a/AGENTS.md b/AGENTS.md
index 4bc4def..7208117 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -11,7 +11,6 @@ skills/
   {skill-name}/
     SKILL.md              # Required: skill manifest (Agent Skills spec)
     AGENTS.md             # Generated: navigation guide for agents
-    CLAUDE.md             # Generated: symlink to AGENTS.md
     references/
       _sections.md        # Required: section definitions
       {prefix}-{name}.md  # Reference files
diff --git a/packages/skills-build/src/build.ts b/packages/skills-build/src/build.ts
index bb9561d..2fc2401 100644
--- a/packages/skills-build/src/build.ts
+++ b/packages/skills-build/src/build.ts
@@ -1,11 +1,8 @@
 import {
 	existsSync,
-	lstatSync,
 	readdirSync,
 	readFileSync,
 	statSync,
-	symlinkSync,
-	unlinkSync,
 	writeFileSync,
 } from "node:fs";
 import { basename, join } from "node:path";
@@ -246,25 +243,6 @@ function skillNameToTitle(skillName: string): string {
 		.join(" ");
 }
 
-/**
- * Create CLAUDE.md symlink pointing to AGENTS.md
- */
-function createClaudeSymlink(paths: SkillPaths): void {
-	const symlinkPath = paths.claudeSymlink;
-
-	// Remove existing symlink or file if it exists
-	if (existsSync(symlinkPath)) {
-		const stat = lstatSync(symlinkPath);
-		if (stat.isSymbolicLink() || stat.isFile()) {
-			unlinkSync(symlinkPath);
-		}
-	}
-
-	// Create symlink (relative path so it works across environments)
-	symlinkSync("AGENTS.md", symlinkPath);
-	console.log(`  Created symlink: CLAUDE.md -> AGENTS.md`);
-}
-
 /**
  * Build AGENTS.md for a specific skill
  *
@@ -293,7 +271,6 @@ function buildSkill(paths: SkillPaths): void {
 
 	// Header
 	output.push(`# ${paths.name}\n`);
-	output.push(`> **Note:** \`CLAUDE.md\` is a symlink to this file.\n`);
 
 	// Brief description
 	output.push(`## Overview\n`);
@@ -305,7 +282,6 @@ function buildSkill(paths: SkillPaths): void {
 	output.push(`${paths.name}/`);
 	output.push(`  SKILL.md       # Main skill file - read this first`);
 	output.push(`  AGENTS.md      # This navigation guide`);
-	output.push(`  CLAUDE.md      # Symlink to AGENTS.md`);
 	if (existsSync(paths.referencesDir)) {
 		output.push(`  references/    # Detailed reference files`);
 	}
@@ -371,9 +347,6 @@ function buildSkill(paths: SkillPaths): void {
 	writeFileSync(paths.agentsOutput, output.join("\n"));
 	console.log(`  Generated: ${paths.agentsOutput}`);
 	console.log(`  Total references: ${referenceFiles.length}`);
-
-	// Create CLAUDE.md symlink
-	createClaudeSymlink(paths);
 }
 
 // Run build when executed directly
diff --git a/packages/skills-build/src/config.ts b/packages/skills-build/src/config.ts
index ae273db..9e20937 100644
--- a/packages/skills-build/src/config.ts
+++ b/packages/skills-build/src/config.ts
@@ -17,7 +17,6 @@ export interface SkillPaths {
 	skillDir: string;
 	referencesDir: string;
 	agentsOutput: string;
-	claudeSymlink: string;
 	skillFile: string;
 }
 
@@ -39,7 +38,6 @@ export function getSkillPaths(skillName: string): SkillPaths {
 		skillDir,
 		referencesDir: join(skillDir, "references"),
 		agentsOutput: join(skillDir, "AGENTS.md"),
-		claudeSymlink: join(skillDir, "CLAUDE.md"),
 		skillFile: join(skillDir, "SKILL.md"),
 	};
 }
diff --git a/skills/supabase-postgres-best-practices/AGENTS.md b/skills/supabase-postgres-best-practices/AGENTS.md
index cb45e6b..4f31812 100644
--- a/skills/supabase-postgres-best-practices/AGENTS.md
+++ b/skills/supabase-postgres-best-practices/AGENTS.md
@@ -1,7 +1,5 @@
 # supabase-postgres-best-practices
 
-> **Note:** `CLAUDE.md` is a symlink to this file.
-
 ## Overview
 
 Postgres performance optimization and best practices from Supabase. Use this skill when writing, reviewing, or optimizing Postgres queries, schema designs, or database configurations.
@@ -12,7 +10,6 @@ Postgres performance optimization and best practices from Supabase. Use this ski
 supabase-postgres-best-practices/
   SKILL.md       # Main skill file - read this first
   AGENTS.md      # This navigation guide
-  CLAUDE.md      # Symlink to AGENTS.md
   references/    # Detailed reference files
 ```
 
diff --git a/skills/supabase-postgres-best-practices/CLAUDE.md b/skills/supabase-postgres-best-practices/CLAUDE.md
deleted file mode 120000
index 47dc3e3..0000000
--- a/skills/supabase-postgres-best-practices/CLAUDE.md
+++ /dev/null
@@ -1 +0,0 @@
-AGENTS.md
\ No newline at end of file