@trackunit/iris-app 2.16.3 → 2.16.4-alpha-563d99d17d6.0

package/CHANGELOG.md

@@ -1,131 +1,3 @@
-## 2.16.3 (2026-11-04)
-
-### 🧱 Updated Dependencies
-
-- Updated iris-app-build-utilities to 3.0.18
-- Updated iris-app-api to 2.13.6
-- Updated react-vite-test-setup to 0.0.204
-- Updated css-classname-utils to 0.0.112
-- Updated react-graphql-tools to 1.23.35
-- Updated shared-utils to 1.22.31
-
-## 2.16.2 (2026-11-04)
-
-### 🧱 Updated Dependencies
-
-- Updated iris-app-build-utilities to 3.0.17
-- Updated iris-app-api to 2.13.5
-- Updated react-vite-test-setup to 0.0.203
-- Updated css-classname-utils to 0.0.111
-- Updated react-graphql-tools to 1.23.34
-- Updated shared-utils to 1.22.30
-
-## 2.16.1 (2026-11-04)
-
-### 🧱 Updated Dependencies
-
-- Updated iris-app-build-utilities to 3.0.16
-- Updated iris-app-api to 2.13.4
-- Updated react-vite-test-setup to 0.0.202
-- Updated css-classname-utils to 0.0.110
-- Updated react-graphql-tools to 1.23.33
-- Updated shared-utils to 1.22.29
-
-## 2.16.0 (2026-11-04)
-
-### 🚀 Features
-
-- **iris-app-sdk:** guide apps to lazy pages for AI navigation and follow getParentRoute ([#27279](https://github.com/Trackunit/manager/pull/27279))
-- **iris-app:** generate AGENTS.md only, no CLAUDE.md ([#27348](https://github.com/Trackunit/manager/pull/27348))
-
-### 🧱 Updated Dependencies
-
-- Updated iris-app-build-utilities to 3.0.15
-- Updated iris-app-api to 2.13.3
-- Updated react-vite-test-setup to 0.0.201
-- Updated css-classname-utils to 0.0.109
-- Updated react-graphql-tools to 1.23.32
-- Updated shared-utils to 1.22.28
-
-### ❤️ Thank You
-
-- Kasper Laursen @ghost-of-kla-trackunit
-- Ulrik Jørgensen @ujo-trackunit
-
-## 2.15.16 (2026-11-04)
-
-### 🧱 Updated Dependencies
-
-- Updated iris-app-build-utilities to 3.0.14
-- Updated iris-app-api to 2.13.2
-- Updated react-vite-test-setup to 0.0.200
-- Updated css-classname-utils to 0.0.108
-- Updated react-graphql-tools to 1.23.31
-- Updated shared-utils to 1.22.27
-
-## 2.15.15 (2026-11-03)
-
-### 🩹 Fixes
-
-- **iris-app:** retry submit when iris-app-sdk-server's upstream fetch fails ([#27291](https://github.com/Trackunit/manager/pull/27291))
-
-### ❤️ Thank You
-
-- mta
-- Nick Lediet
-
-## 2.15.14 (2026-11-03)
-
-### 🧱 Updated Dependencies
-
-- Updated iris-app-build-utilities to 3.0.13
-- Updated iris-app-api to 2.13.1
-- Updated react-vite-test-setup to 0.0.199
-- Updated css-classname-utils to 0.0.107
-- Updated react-graphql-tools to 1.23.30
-- Updated shared-utils to 1.22.26
-
-## 2.15.13 (2026-11-03)
-
-### 🧱 Updated Dependencies
-
-- Updated iris-app-build-utilities to 3.0.12
-- Updated iris-app-api to 2.13.0
-- Updated react-graphql-tools to 1.23.29
-
-## 2.15.12 (2026-11-03)
-
-### 🧱 Updated Dependencies
-
-- Updated iris-app-build-utilities to 3.0.11
-- Updated iris-app-api to 2.12.28
-- Updated react-vite-test-setup to 0.0.198
-- Updated css-classname-utils to 0.0.106
-- Updated react-graphql-tools to 1.23.28
-- Updated shared-utils to 1.22.25
-
-## 2.15.11 (2026-11-03)
-
-### 🧱 Updated Dependencies
-
-- Updated iris-app-build-utilities to 3.0.10
-- Updated iris-app-api to 2.12.27
-- Updated react-vite-test-setup to 0.0.197
-- Updated css-classname-utils to 0.0.105
-- Updated react-graphql-tools to 1.23.27
-- Updated shared-utils to 1.22.24
-
-## 2.15.10 (2026-11-03)
-
-### 🧱 Updated Dependencies
-
-- Updated iris-app-build-utilities to 3.0.9
-- Updated iris-app-api to 2.12.26
-- Updated react-vite-test-setup to 0.0.196
-- Updated css-classname-utils to 0.0.104
-- Updated react-graphql-tools to 1.23.26
-- Updated shared-utils to 1.22.23
-
 ## 2.15.9 (2026-11-02)
 
 ### 🧱 Updated Dependencies

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@trackunit/iris-app",
-  "version": "2.16.3",
+  "version": "2.16.4-alpha-563d99d17d6.0",
   "license": "SEE LICENSE IN LICENSE.txt",
   "main": "src/index.js",
   "generators": "./generators.json",
@@ -10,7 +10,7 @@
     "node": ">=24.x"
   },
   "dependencies": {
-    "@trackunit/css-classname-utils": "0.0.112",
+    "@trackunit/css-classname-utils": "0.0.113-alpha-563d99d17d6.0",
     "@typescript-eslint/types": "8.71.2",
     "@typescript-eslint/typescript-estree": "8.71.2",
     "pacote": "^21.5.1",
@@ -26,10 +26,10 @@
     "@nx/react": "23.3.0",
     "@npmcli/arborist": "^9.1.9",
     "win-ca": "^3.5.1",
-    "@trackunit/iris-app-build-utilities": "3.0.18",
-    "@trackunit/react-graphql-tools": "1.23.35",
-    "@trackunit/shared-utils": "1.22.31",
-    "@trackunit/iris-app-api": "2.13.6",
+    "@trackunit/iris-app-build-utilities": "3.0.19-alpha-563d99d17d6.0",
+    "@trackunit/react-graphql-tools": "1.23.36-alpha-563d99d17d6.0",
+    "@trackunit/shared-utils": "1.22.32-alpha-563d99d17d6.0",
+    "@trackunit/iris-app-api": "2.13.7-alpha-563d99d17d6.0",
     "tslib": "^2.6.2",
     "@clack/prompts": "^1.8.1",
     "@nx/devkit": "23.3.0",

package/src/executors/submit/executor.js

@@ -90,20 +90,6 @@ function isRetryableError(statusCode, code, type) {
     }
     return RETRYABLE_TRANSPORT_CODES.has(code) || (code === "FETCH_ERROR" && type === "request-timeout");
 }
-/**
- * Older iris-app-sdk-server releases answer a failed outbound fetch of their own with
- * 400 `{ error: "fetch failed" }`, which npm-registry-fetch appends to the message as " - fetch failed".
- * That is a transient server-side failure, not a rejected package.
- *
- * @param {NpmGeneralError} error The failed upload attempt.
- * @returns {boolean} Whether the attempt should be retried.
- */
-function isRetryableUploadError(error) {
-    if (error.statusCode === 400 && error.message.includes(" - fetch failed.")) {
-        return true;
-    }
-    return isRetryableError(error.statusCode, error.code, error.type);
-}
 function isRetryableApproveError(statusCode, code, type) {
     // Same as isRetryableError but also accept 404 for approvals.
     // 404 can happen spuriously on approval
@@ -167,7 +153,7 @@ async function doUploadAppWithRetry(accessToken, manifest, tarData, settings, re
             console.error("❌ Unable to ship app package. Got error from Iris App SDK repository.", e);
             return { success: false };
         }
-        if (!isRetryableUploadError(e)) {
+        if (!isRetryableError(e.statusCode, e.code, e.type)) {
             console.error("❌ Unable to ship app package.", e.message);
             return { success: false };
         }

package/src/generators/ai-agent-sync/README.md

@@ -1,6 +1,6 @@
 # AI Agent Sync Generator
 
-Syncs agent skills, AGENTS.md, and AI agent configuration files to the latest version. Ensures the SDK is at the latest version before applying updates.
+Syncs agent skills, AGENTS.md, CLAUDE.md, and AI agent configuration files to the latest version. Ensures the SDK is at the latest version before applying updates.
 
 ## Usage
 
@@ -13,9 +13,8 @@ nx g @trackunit/iris-app:ai-agent-sync
 - `.agents/skills/` - AI agent skills for the IrisX App SDK (editor-agnostic)
 - `.mcp.json` - project-scoped MCP configuration for coding agents
 - `.cursor/mcp.json` - Cursor MCP configuration
-- `AGENTS.md` - Workspace-level agent instructions (always applied), read by Cursor and Claude Code
-
-It also removes the `CLAUDE.md` that earlier SDK versions generated, since Claude Code reads `AGENTS.md` natively. Only an unmodified copy is removed (see `legacy-claude-md/`), and not while a `CLAUDE.local.md` or `.claude/CLAUDE.md` exists, since its `@AGENTS.md` import is then what loads `AGENTS.md`. A `CLAUDE.md` you wrote or edited is kept.
+- `AGENTS.md` - Workspace-level agent instructions (always applied)
+- `CLAUDE.md` - Claude-specific configuration (references AGENTS.md)
 
 ## Flow
 

package/src/generators/ai-agent-sync/generator.d.ts

@@ -1,7 +1,7 @@
 import { GeneratorCallback, Tree } from "@nx/devkit";
 import { AiAgentSyncGeneratorSchema } from "./schema";
 /**
- * Syncs Cursor skills, AGENTS.md, and AI agent configuration files.
+ * Syncs Cursor skills, AGENTS.md, CLAUDE.md, and AI agent configuration files.
  * Requires the SDK to be at the latest version before running.
  */
 export declare function aiAgentSyncGenerator(tree: Tree, options: AiAgentSyncGeneratorSchema): Promise<GeneratorCallback>;

package/src/generators/ai-agent-sync/generator.js

@@ -3,7 +3,6 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.aiAgentSyncGenerator = aiAgentSyncGenerator;
 const tslib_1 = require("tslib");
 const devkit_1 = require("@nx/devkit");
-const fs = tslib_1.__importStar(require("fs"));
 const devkit_exports_1 = require("nx/src/devkit-exports");
 const path = tslib_1.__importStar(require("path"));
 const semver = tslib_1.__importStar(require("semver"));
@@ -11,9 +10,6 @@ const get_package_manifest_1 = require("../utils/get-package-manifest");
 const link_claude_skills_1 = require("../utils/link-claude-skills");
 const IRIS_APP_PACKAGE = "@trackunit/iris-app";
 const MIGRATIONS_PACKAGE = "@trackunit/migrations";
-const CLAUDE_MD = "CLAUDE.md";
-const CLAUDE_MEMORY_FILES = [CLAUDE_MD, ".claude/CLAUDE.md", "CLAUDE.local.md"];
-const LEGACY_CLAUDE_MD_DIR = path.join(__dirname, "legacy-claude-md");
 function getStringValue(obj, key) {
     if (typeof obj === "object" && obj !== null && key in obj) {
         const value = obj[key];
@@ -53,48 +49,8 @@ function upgradeInstructions() {
         `  ${pmc.exec} nx g ${MIGRATIONS_PACKAGE}:run-migrations`,
     ].join("\n");
 }
-function normalizeWhitespace(content) {
-    return content.replace(/\s+/g, " ").trim();
-}
-/**
- * Every CLAUDE.md template earlier SDK versions shipped, whitespace-normalized so a
- * workspace formatter's line wrapping or line endings do not hide a match.
- */
-function readLegacyClaudeMdTemplates() {
-    return new Set(fs
-        .readdirSync(LEGACY_CLAUDE_MD_DIR)
-        .filter(file => file.endsWith(".md"))
-        .map(file => normalizeWhitespace(fs.readFileSync(path.join(LEGACY_CLAUDE_MD_DIR, file), "utf-8"))));
-}
-function importsAgentsMd(content) {
-    return /^@AGENTS\.md\s*$/m.test(content);
-}
-/**
- * Earlier SDK versions generated a CLAUDE.md that imported AGENTS.md. Claude Code
- * now reads AGENTS.md directly, so an unmodified copy of that file is removed. Any
- * other CLAUDE.md is the user's and is kept, because AGENTS.md tells users they may
- * add one.
- *
- * Claude Code skips AGENTS.md while any of its memory files exists, so the SDK copy
- * is also kept when another one does: its import is then what loads AGENTS.md.
- */
-function removeSdkGeneratedClaudeMd(tree) {
-    const content = tree.read(CLAUDE_MD, "utf-8");
-    const otherMemoryFiles = CLAUDE_MEMORY_FILES.filter(file => file !== CLAUDE_MD && tree.exists(file));
-    if (content !== null &&
-        otherMemoryFiles.length === 0 &&
-        readLegacyClaudeMdTemplates().has(normalizeWhitespace(content))) {
-        tree.delete(CLAUDE_MD);
-    }
-    const presentMemoryFiles = CLAUDE_MEMORY_FILES.filter(file => tree.exists(file));
-    if (presentMemoryFiles.length > 0 &&
-        !presentMemoryFiles.some(file => importsAgentsMd(tree.read(file, "utf-8") ?? ""))) {
-        devkit_1.logger.warn(`[iris-app:ai-agent-sync] Claude Code skips AGENTS.md while ${presentMemoryFiles.join(", ")} exists. ` +
-            `Add an @AGENTS.md line to one of them or delete them.`);
-    }
-}
 /**
- * Syncs Cursor skills, AGENTS.md, and AI agent configuration files.
+ * Syncs Cursor skills, AGENTS.md, CLAUDE.md, and AI agent configuration files.
  * Requires the SDK to be at the latest version before running.
  */
 async function aiAgentSyncGenerator(tree, options) {
@@ -113,7 +69,7 @@ async function aiAgentSyncGenerator(tree, options) {
                 `Then run this generator again.`);
         }
     }
-    // Clean up files that were managed by previous versions.
+    // Clean up old .cursor files that were managed by previous versions.
     const oldManagedFiles = [
         ".cursor/rules/irisx-app-sdk.mdc",
         ".cursor/rules/rules-index.mdc",
@@ -132,11 +88,10 @@ async function aiAgentSyncGenerator(tree, options) {
             tree.delete(file);
         }
     }
-    removeSdkGeneratedClaudeMd(tree);
     // Copy MCP configuration and agent skills shared with the preset generator.
     const managedFilesTemplatePath = path.join(__dirname, "../preset/files");
     (0, devkit_1.generateFiles)(tree, managedFilesTemplatePath, ".", {});
-    // Copy AGENTS.md to workspace root
+    // Copy AGENTS.md and CLAUDE.md to workspace root
     const rootTemplatePath = path.join(__dirname, "../preset/root-files");
     (0, devkit_1.generateFiles)(tree, rootTemplatePath, ".", {});
     await (0, devkit_1.formatFiles)(tree);

package/src/generators/extend/files/AI_TOOLS_EXTENSION/.env.example__template__

@@ -0,0 +1,9 @@
+# Environment variables for local development
+# Copy this file to .env and fill in your values
+#
+# These variables are read by getSecret() from @trackunit/serverside-utils
+# The env var name must match the secretKey parameter exactly
+#
+# Example:
+# const apiKey = await getSecret({ context: c, secretKey: "API_KEY" });
+# API_KEY=your_api_key_here

package/src/generators/extend/files/AI_TOOLS_EXTENSION/extension-manifest.ts__template__

@@ -0,0 +1,16 @@
+import { AiToolsExtensionManifest } from '@trackunit/iris-app-api';
+import { toManifestAiTools } from '@trackunit/serverside-ai-tools';
+import { tools } from './src/tools';
+
+const aiToolsExtensionManifest: AiToolsExtensionManifest = {
+    id: "<%= projectName %>",
+    type: "AI_TOOLS_EXTENSION",
+    runtime: "DENO",
+    sourceRoot:  "dist/<%= projectRoot %>/",
+    dependencyDefinitionFile: "dist/<%= dependencyDefinitionFile %>",
+    name: "AI tools <%= projectName %>",
+    main: "index.js",
+    aiTools: toManifestAiTools(tools),
+};
+
+export default aiToolsExtensionManifest;

package/src/generators/extend/files/AI_TOOLS_EXTENSION/package.json__template__

@@ -0,0 +1,10 @@
+{
+  "name": "<%= importPath %>",
+  "type": "commonjs",
+  "dependencies": {
+    "@hono/node-server": "^1.19.17",
+    "dotenv": "16.3.1",
+    "hono": "^4.13.5",
+    "zod": "^3.25.76"
+  }
+}

package/src/generators/extend/files/AI_TOOLS_EXTENSION/src/index.ts__template__

@@ -0,0 +1,9 @@
+import { createAiToolsApp } from "@trackunit/serverside-ai-tools";
+import { tools } from "./tools";
+
+export default createAiToolsApp(tools, {
+  requiredScope: "account.view",
+  handlers: {
+    get_greeting: (_context, { name }) => ({ content: [{ type: "text", text: `Hello, ${name}!` }] }),
+  },
+}).fetch;

package/src/generators/extend/files/AI_TOOLS_EXTENSION/src/local-serve.ts__template__

@@ -0,0 +1,11 @@
+// Auto-generated: mimics the production serverside runtime for local development.
+// Do not edit — SDK updates may overwrite changes.
+import "dotenv/config";
+
+import { serve } from "@hono/node-server";
+
+import handler from "./index";
+
+const port = Number(process.env.PORT) || 8000;
+
+serve({ fetch: handler, port });

package/src/generators/extend/files/AI_TOOLS_EXTENSION/src/tools.ts__template__

@@ -0,0 +1,16 @@
+import { defineAiTools } from "@trackunit/serverside-ai-tools";
+import { z } from "zod";
+
+// Definitions only: extension-manifest.ts imports this file at build time.
+// AI clients see the tools as `<namespace>_<name>`; the namespace must be unique across Trackunit.
+export const tools = defineAiTools({
+  namespace: "<%= projectName %>",
+  tools: {
+    get_greeting: {
+      title: "Get greeting",
+      description: "Returns a greeting for the given name. Replace this example with your app's tools.",
+      inputSchema: { name: z.string().min(1).describe("Who to greet.") },
+      annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false },
+    },
+  },
+});

package/src/generators/extend/files/non-ui-test/extension-manifest.spec.ts__template__

@@ -5,7 +5,7 @@ describe("extension manifest", () => {
     expect(extensionManifest).toMatchObject({
       id: "<%= projectName %>",
       type: "<%= type %>",
-      sourceRoot: "<% if (type === 'SERVERSIDE_API_EXTENSION') { %>dist/<%= projectRoot %>/<% } else { %><%= sourceRoot %><% } %>",
+      sourceRoot: "<% if (type === 'SERVERSIDE_API_EXTENSION' || type === 'AI_TOOLS_EXTENSION') { %>dist/<%= projectRoot %>/<% } else { %><%= sourceRoot %><% } %>",
     });
   });
 });

package/src/generators/extend/files/react-app/src/routeTree.tsx__template__

@@ -1,9 +1,8 @@
-import { Navigate, createRootRoute, createRoute, lazyRouteComponent } from "@tanstack/react-router";
+import { Navigate, createRootRoute, createRoute } from "@tanstack/react-router";
+import { App } from "./app";
 
-// Pages are loaded lazily because the extension manifest imports this tree in
-// Node at build time, where a page that needs a browser would fail the build.
 const rootRoute = createRootRoute({
-  component: lazyRouteComponent(() => import("./app"), "App"),
+  component: () => <App />,
 });
 
 const defaultRoute = createRoute({

package/src/generators/extend/generator.js

@@ -230,6 +230,20 @@ const IrisAppExtensionGenerator = async function (tree, options) {
             return projectJson;
         });
     }
+    if (irisAppExtensionType === "AI_TOOLS_EXTENSION") {
+        const serversideAiToolsVersion = await getPackageVersion("@trackunit/serverside-ai-tools");
+        (0, devkit_1.updateJson)(tree, (0, devkit_1.joinPathFragments)(normalizedOptions.projectRoot, "package.json"), packageJson => {
+            packageJson.dependencies = {
+                ...packageJson.dependencies,
+                "@trackunit/serverside-ai-tools": serversideAiToolsVersion,
+            };
+            return packageJson;
+        });
+        if (normalizedOptions.updatePackageJson) {
+            // The extension manifest imports the package at build time, from the workspace.
+            (0, devkit_1.addDependenciesToPackageJson)(tree, { "@trackunit/serverside-ai-tools": serversideAiToolsVersion }, {});
+        }
+    }
     if (normalizedOptions.graphql) {
         await (0, exports.addServersideGraphql)(tree, {
             projectName: normalizedOptions.projectName,

package/src/generators/extend/schema.d.ts

@@ -14,6 +14,7 @@ export interface IrisAppExtensionGeneratorSchema {
     | "ASSET_HOME_EXTENSION"
     | "ASSET_EVENTS_ACTIONS_EXTENSION"
     | "LIFECYCLE_EXTENSION"
-    | "SERVERSIDE_API_EXTENSION";
+    | "SERVERSIDE_API_EXTENSION"
+    | "AI_TOOLS_EXTENSION";
   graphql?: boolean;
 }

package/src/generators/extend/schema.json

@@ -56,7 +56,8 @@
           "CUSTOMER_HOME_EXTENSION",
           "IRIS_APP_SETTINGS_EXTENSION",
           "LIFECYCLE_EXTENSION",
-          "SERVERSIDE_API_EXTENSION"
+          "SERVERSIDE_API_EXTENSION",
+          "AI_TOOLS_EXTENSION"
         ]
       }
     },

package/src/generators/preset/root-files/AGENTS.md

@@ -60,19 +60,3 @@ Available extension types:
 ## Quality Assurance
 
 Before completing any task: Always check for and fix all ESLint and TypeScript errors in modified files.
-
-## Claude Code
-
-Claude Code (v2.1.277 or later) reads this file directly. A `CLAUDE.md` or `CLAUDE.local.md` stops that; if you need one (older Claude Code, personal notes), make its first line `@AGENTS.md`.
-
-SDK-specific skills live in `.agents/skills/`. The generator creates a `.claude/skills` symlink pointing at `../.agents/skills` so Claude Code auto-discovers them. When a skill is referenced in this file, read it from `.agents/skills/[skill-name]/SKILL.md`.
-
-Restart Claude Code after changing `.mcp.json` so the MCP servers are reloaded.
-
-If skills are not appearing in your available skills list, the symlink may be missing (for example on Windows without Developer Mode, or if a real `.claude/skills` directory existed first). Recreate it with:
-
-```bash
-ln -s ../.agents/skills .claude/skills
-```
-
-If `.claude/skills` already exists as a real directory, move its contents into `.agents/skills/` and delete it before running the command above.

package/src/generators/ai-agent-sync/legacy-claude-md/v1.md

@@ -1 +0,0 @@
-@AGENTS.md

package/src/generators/ai-agent-sync/legacy-claude-md/v2.md

@@ -1,13 +0,0 @@
-@AGENTS.md
-
-# Claude Code Users
-
-Skills are in `.agents/skills/` (cross-tool compatible). Claude Code reads from `.claude/skills/`.
-
-To enable skill discovery, create a symlink:
-
-```bash
-ln -s .agents/skills .claude/skills
-```
-
-Or read skills directly from `.agents/skills/[skill-name]/SKILL.md` when referenced in AGENTS.md.

package/src/generators/ai-agent-sync/legacy-claude-md/v3.md

@@ -1,17 +0,0 @@
-@AGENTS.md
-
-# IrisX App Workspace
-
-This is an IrisX App project generated by the Trackunit SDK. Follow AGENTS.md for all development rules.
-
-## Skills
-
-SDK-specific skills are located in `.agents/skills/`. When a skill is referenced in AGENTS.md, read it from `.agents/skills/[skill-name]/SKILL.md`.
-
-If skills from `.agents/skills/` are not appearing in your available skills list, suggest the user symlink them for automatic discovery:
-
-```bash
-ln -s .agents/skills .claude/skills
-```
-
-Note: If the user already has a `.claude/skills` folder, they should symlink individual skills or the contents instead.

package/src/generators/ai-agent-sync/legacy-claude-md/v4.md

@@ -1,17 +0,0 @@
-@AGENTS.md
-
-# IrisX App Workspace
-
-This is an IrisX App project generated by the Trackunit SDK. Follow AGENTS.md for all development rules.
-
-## Skills
-
-SDK-specific skills live in `.agents/skills/`. The generator creates a `.claude/skills` symlink pointing at `../.agents/skills` so Claude Code auto-discovers them. When a skill is referenced in AGENTS.md, read it from `.agents/skills/[skill-name]/SKILL.md`.
-
-If skills are not appearing in your available skills list, the symlink may be missing (for example on Windows without Developer Mode, or if a real `.claude/skills` directory existed first). Recreate it with:
-
-```bash
-ln -s ../.agents/skills .claude/skills
-```
-
-If `.claude/skills` already exists as a real directory, move its contents into `.agents/skills/` and delete it before running the command above.