first-tree 0.0.3 → 0.0.5

package/skills/first-tree/engine/repo.ts

@@ -1,12 +1,20 @@
 import { existsSync, readFileSync, readdirSync, statSync } from "node:fs";
-import { join, resolve } from "node:path";
+import { basename, dirname, join, resolve } from "node:path";
 import {
+  AGENT_INSTRUCTIONS_FILE,
+  CLAUDE_FRAMEWORK_VERSION,
+  CLAUDE_INSTALLED_PROGRESS,
   FRAMEWORK_VERSION,
+  INSTALLED_PROGRESS,
+  LEGACY_AGENT_INSTRUCTIONS_FILE,
+  LEGACY_PROGRESS,
+  LEGACY_REPO_SKILL_PROGRESS,
+  LEGACY_REPO_SKILL_VERSION,
   LEGACY_SKILL_PROGRESS,
   LEGACY_SKILL_VERSION,
-  LEGACY_PROGRESS,
   LEGACY_VERSION,
-  INSTALLED_PROGRESS,
+  agentInstructionsFileCandidates,
+  installedSkillRoots,
   type FrameworkLayout,
   detectFrameworkLayout,
   frameworkVersionCandidates,
@@ -17,6 +25,59 @@ import {
 const FRONTMATTER_RE = /^---\s*\n(.*?)\n---/s;
 const OWNERS_RE = /^owners:\s*\[([^\]]*)\]/m;
 const TITLE_RE = /^title:\s*['"]?(.+?)['"]?\s*$/m;
+const EMPTY_REPO_ENTRY_ALLOWLIST = new Set([
+  ".DS_Store",
+  ".editorconfig",
+  ".gitattributes",
+  ".github",
+  ".gitignore",
+  "AGENT.md",
+  "AGENTS.md",
+  "CLAUDE.md",
+  "LICENSE",
+  "LICENSE.md",
+  "LICENSE.txt",
+  "README",
+  "README.md",
+  "README.txt",
+]);
+const SOURCE_FILE_HINTS = new Set([
+  ".gitmodules",
+  "Cargo.toml",
+  "Dockerfile",
+  "Gemfile",
+  "Makefile",
+  "bun.lock",
+  "bun.lockb",
+  "docker-compose.yml",
+  "go.mod",
+  "package-lock.json",
+  "package.json",
+  "pnpm-lock.yaml",
+  "pyproject.toml",
+  "requirements.txt",
+  "tsconfig.json",
+  "uv.lock",
+  "vite.config.ts",
+  "vite.config.js",
+]);
+const SOURCE_DIR_HINTS = new Set([
+  "app",
+  "apps",
+  "backend",
+  "cli",
+  "client",
+  "docs",
+  "e2e",
+  "frontend",
+  "lib",
+  "packages",
+  "scripts",
+  "server",
+  "src",
+  "test",
+  "tests",
+]);
 
 export const FRAMEWORK_BEGIN_MARKER = "<!-- BEGIN CONTEXT-TREE FRAMEWORK";
 export const FRAMEWORK_END_MARKER = "<!-- END CONTEXT-TREE FRAMEWORK -->";
@@ -26,11 +87,35 @@ export interface Frontmatter {
   owners?: string[];
 }
 
+function hasGitMetadata(root: string): boolean {
+  try {
+    const stat = statSync(join(root, ".git"));
+    return stat.isDirectory() || stat.isFile();
+  } catch {
+    return false;
+  }
+}
+
+function discoverGitRoot(start: string): string | null {
+  let dir = start;
+  while (true) {
+    if (hasGitMetadata(dir)) {
+      return dir;
+    }
+    const parent = dirname(dir);
+    if (parent === dir) {
+      return null;
+    }
+    dir = parent;
+  }
+}
+
 export class Repo {
   readonly root: string;
 
   constructor(root?: string) {
-    this.root = resolve(root ?? process.cwd());
+    const start = resolve(root ?? process.cwd());
+    this.root = root === undefined ? discoverGitRoot(start) ?? start : start;
   }
 
   pathExists(relPath: string): boolean {
@@ -84,12 +169,24 @@ export class Repo {
     return knownConfigs.some((c) => this.pathExists(c));
   }
 
+  installedSkillRoots(): string[] {
+    return installedSkillRoots();
+  }
+
+  missingInstalledSkillRoots(): string[] {
+    return this.installedSkillRoots().filter(
+      (root) =>
+        !this.pathExists(join(root, "SKILL.md")) ||
+        !this.pathExists(join(root, "assets", "framework", "VERSION")),
+    );
+  }
+
+  hasCurrentInstalledSkill(): boolean {
+    return this.missingInstalledSkillRoots().length === 0;
+  }
+
   isGitRepo(): boolean {
-    try {
-      return statSync(join(this.root, ".git")).isDirectory();
-    } catch {
-      return false;
-    }
+    return hasGitMetadata(this.root);
   }
 
   hasFramework(): boolean {
@@ -122,6 +219,12 @@ export class Repo {
     if (layout === "legacy-skill") {
       return LEGACY_SKILL_PROGRESS;
     }
+    if (layout === "legacy-repo-skill") {
+      return LEGACY_REPO_SKILL_PROGRESS;
+    }
+    if (layout === "claude-skill") {
+      return CLAUDE_INSTALLED_PROGRESS;
+    }
     return INSTALLED_PROGRESS;
   }
 
@@ -133,11 +236,39 @@ export class Repo {
     if (layout === "legacy-skill") {
       return LEGACY_SKILL_VERSION;
     }
+    if (layout === "legacy-repo-skill") {
+      return LEGACY_REPO_SKILL_VERSION;
+    }
+    if (layout === "claude-skill") {
+      return CLAUDE_FRAMEWORK_VERSION;
+    }
     return FRAMEWORK_VERSION;
   }
 
-  hasAgentMdMarkers(): boolean {
-    const text = this.readFile("AGENT.md");
+  agentInstructionsPath(): string | null {
+    return resolveFirstExistingPath(this.root, agentInstructionsFileCandidates());
+  }
+
+  hasCanonicalAgentInstructionsFile(): boolean {
+    return this.pathExists(AGENT_INSTRUCTIONS_FILE);
+  }
+
+  hasLegacyAgentInstructionsFile(): boolean {
+    return this.pathExists(LEGACY_AGENT_INSTRUCTIONS_FILE);
+  }
+
+  hasDuplicateAgentInstructionsFiles(): boolean {
+    return this.hasCanonicalAgentInstructionsFile() && this.hasLegacyAgentInstructionsFile();
+  }
+
+  readAgentInstructions(): string | null {
+    const relPath = this.agentInstructionsPath();
+    if (relPath === null) return null;
+    return this.readFile(relPath);
+  }
+
+  hasAgentInstructionsMarkers(): boolean {
+    const text = this.readAgentInstructions();
     if (text === null) return false;
     return text.includes(FRAMEWORK_BEGIN_MARKER) && text.includes(FRAMEWORK_END_MARKER);
   }
@@ -181,4 +312,82 @@ export class Repo {
   hasPlaceholderNode(): boolean {
     return this.fileContains("NODE.md", "<!-- PLACEHOLDER");
   }
+
+  repoName(): string {
+    return basename(this.root);
+  }
+
+  topLevelEntries(): string[] {
+    try {
+      return readdirSync(this.root).filter((entry) => entry !== ".git");
+    } catch {
+      return [];
+    }
+  }
+
+  looksLikeTreeRepo(): boolean {
+    if (
+      this.pathExists("package.json")
+      && this.pathExists("src/cli.ts")
+      && this.pathExists("skills/first-tree/SKILL.md")
+      && this.progressPath() === null
+      && this.frontmatter("NODE.md") === null
+      && !this.hasAgentInstructionsMarkers()
+      && !this.pathExists("members/NODE.md")
+    ) {
+      return false;
+    }
+
+    return (
+      this.progressPath() !== null
+      || this.hasFramework()
+      || this.hasAgentInstructionsMarkers()
+      || this.pathExists("members/NODE.md")
+      || this.frontmatter("NODE.md") !== null
+    );
+  }
+
+  isLikelyEmptyRepo(): boolean {
+    const relevant = this.topLevelEntries().filter(
+      (entry) => !EMPTY_REPO_ENTRY_ALLOWLIST.has(entry),
+    );
+    return relevant.length === 0;
+  }
+
+  isLikelySourceRepo(): boolean {
+    if (this.looksLikeTreeRepo()) {
+      return false;
+    }
+
+    const entries = this.topLevelEntries().filter(
+      (entry) => !EMPTY_REPO_ENTRY_ALLOWLIST.has(entry),
+    );
+    if (entries.length === 0) {
+      return false;
+    }
+
+    let directoryCount = 0;
+
+    for (const entry of entries) {
+      if (SOURCE_FILE_HINTS.has(entry)) {
+        return true;
+      }
+      if (isDirectory(this.root, entry)) {
+        directoryCount += 1;
+        if (SOURCE_DIR_HINTS.has(entry)) {
+          return true;
+        }
+      }
+    }
+
+    return directoryCount >= 2 || entries.length >= 4;
+  }
+}
+
+function isDirectory(root: string, relPath: string): boolean {
+  try {
+    return statSync(join(root, relPath)).isDirectory();
+  } catch {
+    return false;
+  }
 }

package/skills/first-tree/engine/rules/agent-instructions.ts

@@ -1,20 +1,42 @@
 import { FRAMEWORK_END_MARKER } from "#skill/engine/repo.js";
 import type { Repo } from "#skill/engine/repo.js";
 import type { RuleResult } from "#skill/engine/rules/index.js";
-import { FRAMEWORK_TEMPLATES_DIR } from "#skill/engine/runtime/asset-loader.js";
+import {
+  AGENT_INSTRUCTIONS_FILE,
+  AGENT_INSTRUCTIONS_TEMPLATE,
+  FRAMEWORK_TEMPLATES_DIR,
+  LEGACY_AGENT_INSTRUCTIONS_FILE,
+} from "#skill/engine/runtime/asset-loader.js";
 
 export function evaluate(repo: Repo): RuleResult {
   const tasks: string[] = [];
-  if (!repo.pathExists("AGENT.md")) {
+  const hasCanonicalInstructions = repo.hasCanonicalAgentInstructionsFile();
+  const hasLegacyInstructions = repo.hasLegacyAgentInstructionsFile();
+
+  if (!hasCanonicalInstructions && !hasLegacyInstructions) {
+    tasks.push(
+      `${AGENT_INSTRUCTIONS_FILE} is missing — create from \`${FRAMEWORK_TEMPLATES_DIR}/${AGENT_INSTRUCTIONS_TEMPLATE}\``,
+    );
+    return { group: "Agent Instructions", order: 3, tasks };
+  }
+
+  if (hasCanonicalInstructions && hasLegacyInstructions) {
     tasks.push(
-      `AGENT.md is missing — create from \`${FRAMEWORK_TEMPLATES_DIR}/agent.md.template\``,
+      `Merge any remaining user-authored content from \`${LEGACY_AGENT_INSTRUCTIONS_FILE}\` into \`${AGENT_INSTRUCTIONS_FILE}\`, then delete the legacy file`,
     );
-  } else if (!repo.hasAgentMdMarkers()) {
+  } else if (hasLegacyInstructions) {
+    tasks.push(
+      `Rename \`${LEGACY_AGENT_INSTRUCTIONS_FILE}\` to \`${AGENT_INSTRUCTIONS_FILE}\` to use the canonical agent instructions filename`,
+    );
+  }
+
+  const instructionsPath = repo.agentInstructionsPath() ?? AGENT_INSTRUCTIONS_FILE;
+  if (!repo.hasAgentInstructionsMarkers()) {
     tasks.push(
-      "AGENT.md exists but is missing framework markers — add `<!-- BEGIN CONTEXT-TREE FRAMEWORK -->` and `<!-- END CONTEXT-TREE FRAMEWORK -->` sections",
+      `\`${instructionsPath}\` exists but is missing framework markers — add \`<!-- BEGIN CONTEXT-TREE FRAMEWORK -->\` and \`<!-- END CONTEXT-TREE FRAMEWORK -->\` sections`,
     );
   } else {
-    const text = repo.readFile("AGENT.md") ?? "";
+    const text = repo.readAgentInstructions() ?? "";
     const afterMarker = text.split(FRAMEWORK_END_MARKER);
     if (afterMarker.length > 1) {
       const userSection = afterMarker[1].trim();
@@ -28,7 +50,7 @@ export function evaluate(repo: Repo): RuleResult {
         );
       if (lines.length === 0) {
         tasks.push(
-          "Add your project-specific instructions below the framework markers in AGENT.md",
+          `Add your project-specific instructions below the framework markers in ${AGENT_INSTRUCTIONS_FILE}`,
         );
       }
     }

package/skills/first-tree/engine/rules/agent-integration.ts

@@ -1,13 +1,15 @@
 import type { Repo } from "#skill/engine/repo.js";
 import type { RuleResult } from "#skill/engine/rules/index.js";
+import { claudeCodeExampleCandidates } from "#skill/engine/runtime/adapters.js";
 import { FRAMEWORK_EXAMPLES_DIR } from "#skill/engine/runtime/asset-loader.js";
 
 export function evaluate(repo: Repo): RuleResult {
   const tasks: string[] = [];
+  const [claudeExamplePath] = claudeCodeExampleCandidates();
   if (repo.pathExists(".claude/settings.json")) {
     if (!repo.fileContains(".claude/settings.json", "inject-tree-context")) {
       tasks.push(
-        `Add SessionStart hook to \`.claude/settings.json\` (see \`${FRAMEWORK_EXAMPLES_DIR}/claude-code/\`)`,
+        `Add SessionStart hook to \`.claude/settings.json\` (see \`${claudeExamplePath}/\`)`,
       );
     }
   } else if (!repo.anyAgentConfig()) {

package/skills/first-tree/engine/rules/framework.ts

@@ -1,12 +1,12 @@
 import type { Repo } from "#skill/engine/repo.js";
 import type { RuleResult } from "#skill/engine/rules/index.js";
-import { SKILL_ROOT } from "#skill/engine/runtime/asset-loader.js";
+import { installedSkillRootsDisplay } from "#skill/engine/runtime/asset-loader.js";
 
 export function evaluate(repo: Repo): RuleResult {
   const tasks: string[] = [];
   if (!repo.hasFramework()) {
     tasks.push(
-      `\`${SKILL_ROOT}/\` not found — run \`context-tree init\` to install the framework skill bundled with the current \`first-tree\` package`,
+      `${installedSkillRootsDisplay()} not found — run \`context-tree init\` to install the framework skill bundled with the current \`first-tree\` package`,
     );
   }
   return { group: "Framework", order: 1, tasks };

package/skills/first-tree/engine/runtime/adapters.ts

@@ -1,7 +1,9 @@
 import { join } from "node:path";
 import {
+  CLAUDE_FRAMEWORK_EXAMPLES_DIR,
+  CLAUDE_FRAMEWORK_HELPERS_DIR,
   FRAMEWORK_EXAMPLES_DIR,
-  FRAMEWORK_HELPERS_DIR,
+  LEGACY_REPO_SKILL_EXAMPLES_DIR,
   LEGACY_SKILL_EXAMPLES_DIR,
   LEGACY_EXAMPLES_DIR,
 } from "#skill/engine/runtime/asset-loader.js";
@@ -11,12 +13,14 @@ export const CODEX_CONFIG_PATH = ".codex/config.json";
 
 export function claudeCodeExampleCandidates(): string[] {
   return [
+    join(CLAUDE_FRAMEWORK_EXAMPLES_DIR, "claude-code"),
     join(FRAMEWORK_EXAMPLES_DIR, "claude-code"),
+    join(LEGACY_REPO_SKILL_EXAMPLES_DIR, "claude-code"),
     join(LEGACY_SKILL_EXAMPLES_DIR, "claude-code"),
     join(LEGACY_EXAMPLES_DIR, "claude-code"),
   ];
 }
 
 export function injectTreeContextHint(): string {
-  return join(FRAMEWORK_HELPERS_DIR, "inject-tree-context.sh");
+  return join(CLAUDE_FRAMEWORK_HELPERS_DIR, "inject-tree-context.sh");
 }

package/skills/first-tree/engine/runtime/asset-loader.ts

@@ -2,7 +2,11 @@ import { existsSync, statSync } from "node:fs";
 import { join } from "node:path";
 
 export const SKILL_NAME = "first-tree";
-export const SKILL_ROOT = join("skills", SKILL_NAME);
+export const BUNDLED_SKILL_ROOT = join("skills", SKILL_NAME);
+export const SKILL_ROOT = join(".agents", "skills", SKILL_NAME);
+export const CLAUDE_SKILL_ROOT = join(".claude", "skills", SKILL_NAME);
+export const INSTALLED_SKILL_ROOTS = [SKILL_ROOT, CLAUDE_SKILL_ROOT] as const;
+
 export const SKILL_AGENTS_DIR = join(SKILL_ROOT, "agents");
 export const SKILL_REFERENCES_DIR = join(SKILL_ROOT, "references");
 export const FRAMEWORK_ASSET_ROOT = join(SKILL_ROOT, "assets", "framework");
@@ -14,6 +18,96 @@ export const FRAMEWORK_PROMPTS_DIR = join(FRAMEWORK_ASSET_ROOT, "prompts");
 export const FRAMEWORK_EXAMPLES_DIR = join(FRAMEWORK_ASSET_ROOT, "examples");
 export const FRAMEWORK_HELPERS_DIR = join(FRAMEWORK_ASSET_ROOT, "helpers");
 export const INSTALLED_PROGRESS = join(SKILL_ROOT, "progress.md");
+export const AGENT_INSTRUCTIONS_FILE = "AGENTS.md";
+export const LEGACY_AGENT_INSTRUCTIONS_FILE = "AGENT.md";
+export const AGENT_INSTRUCTIONS_TEMPLATE = "agents.md.template";
+
+export const CLAUDE_SKILL_AGENTS_DIR = join(CLAUDE_SKILL_ROOT, "agents");
+export const CLAUDE_SKILL_REFERENCES_DIR = join(CLAUDE_SKILL_ROOT, "references");
+export const CLAUDE_FRAMEWORK_ASSET_ROOT = join(
+  CLAUDE_SKILL_ROOT,
+  "assets",
+  "framework",
+);
+export const CLAUDE_FRAMEWORK_MANIFEST = join(
+  CLAUDE_FRAMEWORK_ASSET_ROOT,
+  "manifest.json",
+);
+export const CLAUDE_FRAMEWORK_VERSION = join(
+  CLAUDE_FRAMEWORK_ASSET_ROOT,
+  "VERSION",
+);
+export const CLAUDE_FRAMEWORK_TEMPLATES_DIR = join(
+  CLAUDE_FRAMEWORK_ASSET_ROOT,
+  "templates",
+);
+export const CLAUDE_FRAMEWORK_WORKFLOWS_DIR = join(
+  CLAUDE_FRAMEWORK_ASSET_ROOT,
+  "workflows",
+);
+export const CLAUDE_FRAMEWORK_PROMPTS_DIR = join(
+  CLAUDE_FRAMEWORK_ASSET_ROOT,
+  "prompts",
+);
+export const CLAUDE_FRAMEWORK_EXAMPLES_DIR = join(
+  CLAUDE_FRAMEWORK_ASSET_ROOT,
+  "examples",
+);
+export const CLAUDE_FRAMEWORK_HELPERS_DIR = join(
+  CLAUDE_FRAMEWORK_ASSET_ROOT,
+  "helpers",
+);
+export const CLAUDE_INSTALLED_PROGRESS = join(
+  CLAUDE_SKILL_ROOT,
+  "progress.md",
+);
+
+export const LEGACY_REPO_SKILL_ROOT = join("skills", SKILL_NAME);
+export const LEGACY_REPO_SKILL_AGENTS_DIR = join(
+  LEGACY_REPO_SKILL_ROOT,
+  "agents",
+);
+export const LEGACY_REPO_SKILL_REFERENCES_DIR = join(
+  LEGACY_REPO_SKILL_ROOT,
+  "references",
+);
+export const LEGACY_REPO_SKILL_ASSET_ROOT = join(
+  LEGACY_REPO_SKILL_ROOT,
+  "assets",
+  "framework",
+);
+export const LEGACY_REPO_SKILL_MANIFEST = join(
+  LEGACY_REPO_SKILL_ASSET_ROOT,
+  "manifest.json",
+);
+export const LEGACY_REPO_SKILL_VERSION = join(
+  LEGACY_REPO_SKILL_ASSET_ROOT,
+  "VERSION",
+);
+export const LEGACY_REPO_SKILL_TEMPLATES_DIR = join(
+  LEGACY_REPO_SKILL_ASSET_ROOT,
+  "templates",
+);
+export const LEGACY_REPO_SKILL_WORKFLOWS_DIR = join(
+  LEGACY_REPO_SKILL_ASSET_ROOT,
+  "workflows",
+);
+export const LEGACY_REPO_SKILL_PROMPTS_DIR = join(
+  LEGACY_REPO_SKILL_ASSET_ROOT,
+  "prompts",
+);
+export const LEGACY_REPO_SKILL_EXAMPLES_DIR = join(
+  LEGACY_REPO_SKILL_ASSET_ROOT,
+  "examples",
+);
+export const LEGACY_REPO_SKILL_HELPERS_DIR = join(
+  LEGACY_REPO_SKILL_ASSET_ROOT,
+  "helpers",
+);
+export const LEGACY_REPO_SKILL_PROGRESS = join(
+  LEGACY_REPO_SKILL_ROOT,
+  "progress.md",
+);
 
 export const LEGACY_SKILL_NAME = "first-tree-cli-framework";
 export const LEGACY_SKILL_ROOT = join("skills", LEGACY_SKILL_NAME);
@@ -49,7 +143,12 @@ export const LEGACY_WORKFLOWS_DIR = join(LEGACY_FRAMEWORK_ROOT, "workflows");
 export const LEGACY_PROMPTS_DIR = join(LEGACY_FRAMEWORK_ROOT, "prompts");
 export const LEGACY_EXAMPLES_DIR = join(LEGACY_FRAMEWORK_ROOT, "examples");
 
-export type FrameworkLayout = "skill" | "legacy-skill" | "legacy";
+export type FrameworkLayout =
+  | "skill"
+  | "claude-skill"
+  | "legacy-repo-skill"
+  | "legacy-skill"
+  | "legacy";
 
 function pathExists(root: string, relPath: string): boolean {
   const fullPath = join(root, relPath);
@@ -60,17 +159,45 @@ function pathExists(root: string, relPath: string): boolean {
   }
 }
 
+export function installedSkillRoots(): string[] {
+  return [...INSTALLED_SKILL_ROOTS];
+}
+
+export function installedSkillRootsDisplay(): string {
+  return installedSkillRoots()
+    .map((root) => `\`${root}/\``)
+    .join(" and ");
+}
+
 export function frameworkVersionCandidates(): string[] {
-  return [FRAMEWORK_VERSION, LEGACY_SKILL_VERSION, LEGACY_VERSION];
+  return [
+    FRAMEWORK_VERSION,
+    CLAUDE_FRAMEWORK_VERSION,
+    LEGACY_REPO_SKILL_VERSION,
+    LEGACY_SKILL_VERSION,
+    LEGACY_VERSION,
+  ];
 }
 
 export function progressFileCandidates(): string[] {
-  return [INSTALLED_PROGRESS, LEGACY_SKILL_PROGRESS, LEGACY_PROGRESS];
+  return [
+    INSTALLED_PROGRESS,
+    CLAUDE_INSTALLED_PROGRESS,
+    LEGACY_REPO_SKILL_PROGRESS,
+    LEGACY_SKILL_PROGRESS,
+    LEGACY_PROGRESS,
+  ];
+}
+
+export function agentInstructionsFileCandidates(): string[] {
+  return [AGENT_INSTRUCTIONS_FILE, LEGACY_AGENT_INSTRUCTIONS_FILE];
 }
 
 export function frameworkTemplateDirCandidates(): string[] {
   return [
     FRAMEWORK_TEMPLATES_DIR,
+    CLAUDE_FRAMEWORK_TEMPLATES_DIR,
+    LEGACY_REPO_SKILL_TEMPLATES_DIR,
     LEGACY_SKILL_TEMPLATES_DIR,
     LEGACY_TEMPLATES_DIR,
   ];
@@ -79,6 +206,8 @@ export function frameworkTemplateDirCandidates(): string[] {
 export function frameworkWorkflowDirCandidates(): string[] {
   return [
     FRAMEWORK_WORKFLOWS_DIR,
+    CLAUDE_FRAMEWORK_WORKFLOWS_DIR,
+    LEGACY_REPO_SKILL_WORKFLOWS_DIR,
     LEGACY_SKILL_WORKFLOWS_DIR,
     LEGACY_WORKFLOWS_DIR,
   ];
@@ -87,6 +216,8 @@ export function frameworkWorkflowDirCandidates(): string[] {
 export function frameworkPromptDirCandidates(): string[] {
   return [
     FRAMEWORK_PROMPTS_DIR,
+    CLAUDE_FRAMEWORK_PROMPTS_DIR,
+    LEGACY_REPO_SKILL_PROMPTS_DIR,
     LEGACY_SKILL_PROMPTS_DIR,
     LEGACY_PROMPTS_DIR,
   ];
@@ -95,6 +226,8 @@ export function frameworkPromptDirCandidates(): string[] {
 export function frameworkExampleDirCandidates(): string[] {
   return [
     FRAMEWORK_EXAMPLES_DIR,
+    CLAUDE_FRAMEWORK_EXAMPLES_DIR,
+    LEGACY_REPO_SKILL_EXAMPLES_DIR,
     LEGACY_SKILL_EXAMPLES_DIR,
     LEGACY_EXAMPLES_DIR,
   ];
@@ -116,6 +249,12 @@ export function detectFrameworkLayout(root: string): FrameworkLayout | null {
   if (pathExists(root, FRAMEWORK_VERSION)) {
     return "skill";
   }
+  if (pathExists(root, CLAUDE_FRAMEWORK_VERSION)) {
+    return "claude-skill";
+  }
+  if (pathExists(root, LEGACY_REPO_SKILL_VERSION)) {
+    return "legacy-repo-skill";
+  }
   if (pathExists(root, LEGACY_SKILL_VERSION)) {
     return "legacy-skill";
   }

package/skills/first-tree/engine/runtime/installer.ts

@@ -2,9 +2,10 @@ import { copyFileSync, cpSync, existsSync, mkdirSync, rmSync } from "node:fs";
 import { dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
 import {
-  FRAMEWORK_ASSET_ROOT,
+  BUNDLED_SKILL_ROOT,
+  INSTALLED_SKILL_ROOTS,
+  LEGACY_REPO_SKILL_ROOT,
   LEGACY_SKILL_ROOT,
-  SKILL_ROOT,
 } from "#skill/engine/runtime/asset-loader.js";
 
 export function resolveBundledPackageRoot(startUrl = import.meta.url): string {
@@ -12,7 +13,7 @@ export function resolveBundledPackageRoot(startUrl = import.meta.url): string {
   while (true) {
     if (
       existsSync(join(dir, "package.json")) &&
-      existsSync(join(dir, SKILL_ROOT, "SKILL.md"))
+      existsSync(join(dir, BUNDLED_SKILL_ROOT, "SKILL.md"))
     ) {
       return dir;
     }
@@ -38,7 +39,7 @@ export function resolveCanonicalSkillRoot(sourceRoot: string): string {
     return directSkillRoot;
   }
 
-  const nestedSkillRoot = join(sourceRoot, SKILL_ROOT);
+  const nestedSkillRoot = join(sourceRoot, BUNDLED_SKILL_ROOT);
   if (
     existsSync(join(nestedSkillRoot, "SKILL.md")) &&
     existsSync(join(nestedSkillRoot, "assets", "framework", "VERSION"))
@@ -53,16 +54,21 @@ export function resolveCanonicalSkillRoot(sourceRoot: string): string {
 
 export function copyCanonicalSkill(sourceRoot: string, targetRoot: string): void {
   const src = resolveCanonicalSkillRoot(sourceRoot);
-  const dst = join(targetRoot, SKILL_ROOT);
-  const legacyDst = join(targetRoot, LEGACY_SKILL_ROOT);
-  if (existsSync(dst)) {
-    rmSync(dst, { recursive: true, force: true });
+  for (const relPath of [
+    ...INSTALLED_SKILL_ROOTS,
+    LEGACY_REPO_SKILL_ROOT,
+    LEGACY_SKILL_ROOT,
+  ]) {
+    const fullPath = join(targetRoot, relPath);
+    if (existsSync(fullPath)) {
+      rmSync(fullPath, { recursive: true, force: true });
+    }
   }
-  if (legacyDst !== dst && existsSync(legacyDst)) {
-    rmSync(legacyDst, { recursive: true, force: true });
+  for (const relPath of INSTALLED_SKILL_ROOTS) {
+    const dst = join(targetRoot, relPath);
+    mkdirSync(dirname(dst), { recursive: true });
+    cpSync(src, dst, { recursive: true });
   }
-  mkdirSync(dirname(dst), { recursive: true });
-  cpSync(src, dst, { recursive: true });
 }
 
 export function renderTemplateFile(