@openwebf/webf 0.24.0 → 0.24.1

package/README.md

@@ -10,6 +10,14 @@ npm install -g @openwebf/webf
 
 ## Usage
 
+### Initialize Claude Code Skills
+
+The `webf agents init` command injects WebF Claude Code skills (from `@openwebf/claude-code-skills`) into your project and updates `CLAUDE.md` to reference them.
+
+```bash
+webf agents init [project-dir]
+```
+
 ### Generate Code
 
 The `webf codegen` command generates Dart abstract classes and React/Vue components from TypeScript definitions. It automatically creates a project if needed.

package/bin/webf.js

@@ -2,7 +2,7 @@
 
 const { Command } = require('commander');
 const version = require('../package.json').version;
-const { generateCommand, generateModuleCommand } = require('../dist/commands');
+const { generateCommand, generateModuleCommand, agentsInitCommand } = require('../dist/commands');
 
 const program = new Command();
 
@@ -35,4 +35,12 @@ program
   .description('Generate NPM package and Dart bindings for a WebF module from TypeScript interfaces (*.module.d.ts)')
   .action(generateModuleCommand);
 
+const agents = program.command('agents').description('Manage Claude Code agent configs');
+
+agents
+  .command('init')
+  .argument('[projectDir]', 'Target project directory', '.')
+  .description('Initialize Claude Code skills config for a project')
+  .action(agentsInitCommand);
+
 program.parse();

package/dist/agents.js

@@ -0,0 +1,245 @@
+"use strict";
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.agentsInitCommand = agentsInitCommand;
+const fs_1 = __importDefault(require("fs"));
+const os_1 = __importDefault(require("os"));
+const path_1 = __importDefault(require("path"));
+const yaml_1 = __importDefault(require("yaml"));
+const WEBF_AGENTS_BLOCK_START = '<!-- webf-agents:init start -->';
+const WEBF_AGENTS_BLOCK_END = '<!-- webf-agents:init end -->';
+function ensureDirSync(dirPath) {
+    fs_1.default.mkdirSync(dirPath, { recursive: true });
+}
+function readFileIfExists(filePath) {
+    try {
+        return fs_1.default.readFileSync(filePath);
+    }
+    catch (error) {
+        if ((error === null || error === void 0 ? void 0 : error.code) === 'ENOENT')
+            return null;
+        throw error;
+    }
+}
+function backupFileSync(filePath) {
+    const timestamp = new Date()
+        .toISOString()
+        .replace(/[:.]/g, '')
+        .replace('T', '')
+        .replace('Z', 'Z');
+    const backupPath = `${filePath}.bak.${timestamp}`;
+    fs_1.default.copyFileSync(filePath, backupPath);
+    return backupPath;
+}
+function copyFileWithBackupSync(srcPath, destPath) {
+    const src = fs_1.default.readFileSync(srcPath);
+    const dest = readFileIfExists(destPath);
+    if (dest && Buffer.compare(src, dest) === 0)
+        return { changed: false, backupPath: null };
+    ensureDirSync(path_1.default.dirname(destPath));
+    let backupPath = null;
+    if (dest) {
+        backupPath = backupFileSync(destPath);
+    }
+    fs_1.default.writeFileSync(destPath, src);
+    return { changed: true, backupPath };
+}
+function copyDirRecursiveSync(srcDir, destDir, stats) {
+    ensureDirSync(destDir);
+    const entries = fs_1.default.readdirSync(srcDir, { withFileTypes: true });
+    for (const entry of entries) {
+        const srcPath = path_1.default.join(srcDir, entry.name);
+        const destPath = path_1.default.join(destDir, entry.name);
+        if (entry.isDirectory()) {
+            copyDirRecursiveSync(srcPath, destPath, stats);
+            continue;
+        }
+        if (entry.isFile()) {
+            const { changed, backupPath } = copyFileWithBackupSync(srcPath, destPath);
+            if (changed)
+                stats.filesWritten += 1;
+            else
+                stats.filesUnchanged += 1;
+            if (backupPath)
+                stats.backupsCreated += 1;
+        }
+    }
+}
+function listFilesRecursiveSync(dirPath) {
+    const out = [];
+    const entries = fs_1.default.readdirSync(dirPath, { withFileTypes: true });
+    for (const entry of entries) {
+        const entryPath = path_1.default.join(dirPath, entry.name);
+        if (entry.isDirectory()) {
+            out.push(...listFilesRecursiveSync(entryPath));
+            continue;
+        }
+        if (entry.isFile())
+            out.push(entryPath);
+    }
+    return out;
+}
+function toPosixRelativePath(fromDir, absolutePath) {
+    const rel = path_1.default.relative(fromDir, absolutePath);
+    return rel.split(path_1.default.sep).join('/');
+}
+function parseSkillFrontmatter(skillMd) {
+    var _a;
+    const trimmed = skillMd.trimStart();
+    if (!trimmed.startsWith('---'))
+        return {};
+    const endIndex = trimmed.indexOf('\n---', 3);
+    if (endIndex === -1)
+        return {};
+    const fm = trimmed.slice(3, endIndex).trim();
+    try {
+        const parsed = (_a = yaml_1.default.parse(fm)) !== null && _a !== void 0 ? _a : {};
+        return { name: parsed === null || parsed === void 0 ? void 0 : parsed.name, description: parsed === null || parsed === void 0 ? void 0 : parsed.description };
+    }
+    catch (_b) {
+        return {};
+    }
+}
+function updateOrAppendMarkedBlock(existing, newBlock) {
+    const startIndex = existing.indexOf(WEBF_AGENTS_BLOCK_START);
+    const endIndex = existing.indexOf(WEBF_AGENTS_BLOCK_END);
+    if (startIndex !== -1 && endIndex !== -1 && endIndex > startIndex) {
+        const before = existing.slice(0, startIndex).trimEnd();
+        const after = existing.slice(endIndex + WEBF_AGENTS_BLOCK_END.length).trimStart();
+        const next = [before, newBlock.trim(), after].filter(Boolean).join('\n\n');
+        return { content: next + '\n', action: 'replaced' };
+    }
+    const content = existing.trimEnd();
+    return { content: (content ? content + '\n\n' : '') + newBlock.trim() + '\n', action: 'appended' };
+}
+function buildClaudeBlock(sourcePackageName, sourcePackageVersion, skills) {
+    const lines = [];
+    lines.push(WEBF_AGENTS_BLOCK_START);
+    lines.push('## WebF Claude Code Skills');
+    lines.push('');
+    lines.push(`Source: \`${sourcePackageName}@${sourcePackageVersion}\``);
+    lines.push('');
+    lines.push('### Skills');
+    for (const skill of skills) {
+        const desc = skill.description ? ` — ${skill.description}` : '';
+        lines.push(`- \`${skill.name}\`${desc} (\`${skill.skillFileRelativePath}\`)`);
+    }
+    const anyReferences = skills.some(s => s.referenceRelativePaths.length > 0);
+    if (anyReferences) {
+        lines.push('');
+        lines.push('### References');
+        for (const skill of skills) {
+            if (skill.referenceRelativePaths.length === 0)
+                continue;
+            const refs = skill.referenceRelativePaths.map(r => `\`${r}\``).join(', ');
+            lines.push(`- \`${skill.name}\`: ${refs}`);
+        }
+    }
+    lines.push(WEBF_AGENTS_BLOCK_END);
+    return lines.join('\n');
+}
+function resolveSkillsPackageRoot() {
+    var _a, _b;
+    const packageJsonPath = require.resolve('@openwebf/claude-code-skills/package.json');
+    const packageRoot = path_1.default.dirname(packageJsonPath);
+    const packageJson = JSON.parse(fs_1.default.readFileSync(packageJsonPath, 'utf-8'));
+    return {
+        packageRoot,
+        packageName: (_a = packageJson === null || packageJson === void 0 ? void 0 : packageJson.name) !== null && _a !== void 0 ? _a : '@openwebf/claude-code-skills',
+        packageVersion: (_b = packageJson === null || packageJson === void 0 ? void 0 : packageJson.version) !== null && _b !== void 0 ? _b : 'unknown',
+    };
+}
+function listSkillDirectories(skillsPackageRoot) {
+    const entries = fs_1.default.readdirSync(skillsPackageRoot, { withFileTypes: true });
+    const dirs = entries
+        .filter(e => e.isDirectory())
+        .map(e => e.name)
+        .filter(name => fs_1.default.existsSync(path_1.default.join(skillsPackageRoot, name, 'SKILL.md')))
+        .sort();
+    return dirs;
+}
+function collectSkillInfo(projectRoot, skillsDir, skillDirectoryName) {
+    var _a;
+    const skillDirAbs = path_1.default.join(skillsDir, skillDirectoryName);
+    const skillMdAbs = path_1.default.join(skillDirAbs, 'SKILL.md');
+    const skillMd = fs_1.default.readFileSync(skillMdAbs, 'utf-8');
+    const fm = parseSkillFrontmatter(skillMd);
+    const referenceRelativePaths = [];
+    const files = listFilesRecursiveSync(skillDirAbs);
+    for (const fileAbs of files) {
+        if (path_1.default.basename(fileAbs) === 'SKILL.md')
+            continue;
+        referenceRelativePaths.push(toPosixRelativePath(projectRoot, fileAbs));
+    }
+    referenceRelativePaths.sort();
+    return {
+        directoryName: skillDirectoryName,
+        name: (_a = fm.name) !== null && _a !== void 0 ? _a : skillDirectoryName,
+        description: fm.description,
+        skillFileRelativePath: toPosixRelativePath(projectRoot, skillMdAbs),
+        referenceRelativePaths,
+    };
+}
+function agentsInitCommand(projectDir) {
+    return __awaiter(this, void 0, void 0, function* () {
+        var _a, _b;
+        const startedAt = Date.now();
+        const resolvedProjectDir = path_1.default.resolve(process.cwd(), projectDir || '.');
+        const claudeMdPath = path_1.default.join(resolvedProjectDir, 'CLAUDE.md');
+        const claudeDir = path_1.default.join(resolvedProjectDir, '.claude');
+        const projectSkillsDir = path_1.default.join(claudeDir, 'skills');
+        const hasClaudeMd = fs_1.default.existsSync(claudeMdPath);
+        const hasClaudeDir = fs_1.default.existsSync(claudeDir);
+        const isNewProject = !hasClaudeMd && !hasClaudeDir;
+        console.log('webf agents init');
+        console.log(`Project: ${resolvedProjectDir}`);
+        if (isNewProject) {
+            console.log('Detected: no CLAUDE.md and no .claude/ (new project)');
+        }
+        else {
+            console.log(`Detected: CLAUDE.md=${hasClaudeMd ? 'yes' : 'no'}, .claude/=${hasClaudeDir ? 'yes' : 'no'} (existing project)`);
+        }
+        const { packageRoot, packageName, packageVersion } = resolveSkillsPackageRoot();
+        const skillDirectories = listSkillDirectories(packageRoot);
+        if (skillDirectories.length === 0) {
+            throw new Error(`No skills found in ${packageName} (resolved at ${packageRoot}).`);
+        }
+        console.log(`Skills source: ${packageName}@${packageVersion}`);
+        console.log(`Skills destination: ${toPosixRelativePath(resolvedProjectDir, projectSkillsDir)}`);
+        ensureDirSync(projectSkillsDir);
+        const copyStats = { filesWritten: 0, filesUnchanged: 0, backupsCreated: 0 };
+        for (const skillDirName of skillDirectories) {
+            const srcSkillDir = path_1.default.join(packageRoot, skillDirName);
+            const destSkillDir = path_1.default.join(projectSkillsDir, skillDirName);
+            copyDirRecursiveSync(srcSkillDir, destSkillDir, copyStats);
+        }
+        const installedSkills = skillDirectories.map(skillDirName => collectSkillInfo(resolvedProjectDir, projectSkillsDir, skillDirName));
+        const block = buildClaudeBlock(packageName, packageVersion, installedSkills);
+        if (isNewProject) {
+            const initial = ['# Claude Code', '', block, ''].join('\n');
+            fs_1.default.writeFileSync(claudeMdPath, initial, 'utf-8');
+            console.log(`Created ${toPosixRelativePath(resolvedProjectDir, claudeMdPath)}`);
+        }
+        else {
+            const existing = (_b = (_a = readFileIfExists(claudeMdPath)) === null || _a === void 0 ? void 0 : _a.toString('utf-8')) !== null && _b !== void 0 ? _b : '';
+            const { content, action } = updateOrAppendMarkedBlock(existing, block);
+            fs_1.default.writeFileSync(claudeMdPath, content, 'utf-8');
+            console.log(`${action === 'replaced' ? 'Updated' : 'Appended'} WebF skills block in ${toPosixRelativePath(resolvedProjectDir, claudeMdPath)}`);
+        }
+        const versionFilePath = path_1.default.join(claudeDir, 'webf-claude-code-skills.version');
+        fs_1.default.writeFileSync(versionFilePath, `${packageName}@${packageVersion}${os_1.default.EOL}`, 'utf-8');
+        console.log(`Wrote ${toPosixRelativePath(resolvedProjectDir, versionFilePath)}`);
+        console.log(`Installed ${installedSkills.length} skills (${copyStats.filesWritten} files written, ${copyStats.filesUnchanged} unchanged, ${copyStats.backupsCreated} backups) in ${Date.now() - startedAt}ms`);
+    });
+}

package/dist/commands.js

@@ -12,6 +12,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.agentsInitCommand = void 0;
 exports.generateCommand = generateCommand;
 exports.generateModuleCommand = generateModuleCommand;
 const child_process_1 = require("child_process");
@@ -25,6 +26,8 @@ const glob_1 = require("glob");
 const lodash_1 = __importDefault(require("lodash"));
 const inquirer_1 = __importDefault(require("inquirer"));
 const yaml_1 = __importDefault(require("yaml"));
+const agents_1 = require("./agents");
+Object.defineProperty(exports, "agentsInitCommand", { enumerable: true, get: function () { return agents_1.agentsInitCommand; } });
 /**
  * Sanitize a package name to comply with npm naming rules
  * NPM package name rules:
@@ -178,33 +181,6 @@ function readFlutterPackageMetadata(packagePath) {
         return null;
     }
 }
-function copyReadmeToPackageRoot(params) {
-    const { sourceRoot, targetRoot } = params;
-    const targetPath = path_1.default.join(targetRoot, 'README.md');
-    if (fs_1.default.existsSync(targetPath)) {
-        return { copied: false, targetPath };
-    }
-    const candidateNames = ['README.md', 'Readme.md', 'readme.md'];
-    let sourcePath = null;
-    for (const candidate of candidateNames) {
-        const abs = path_1.default.join(sourceRoot, candidate);
-        if (fs_1.default.existsSync(abs)) {
-            sourcePath = abs;
-            break;
-        }
-    }
-    if (!sourcePath) {
-        return { copied: false, targetPath };
-    }
-    try {
-        const content = fs_1.default.readFileSync(sourcePath, 'utf-8');
-        writeFileIfChanged(targetPath, content);
-        return { copied: true, sourcePath, targetPath };
-    }
-    catch (_a) {
-        return { copied: false, targetPath };
-    }
-}
 // Copy markdown docs that match .d.ts basenames from source to the built dist folder,
 // and generate an aggregated README.md in the dist directory.
 function copyMarkdownDocsToDist(params) {
@@ -684,16 +660,6 @@ function generateCommand(distPath, options) {
         }
         // Auto-initialize typings in the output directory if needed
         ensureInitialized(resolvedDistPath);
-        // Copy README.md from the source Flutter package into the npm package root (so `npm publish` includes it).
-        if (options.flutterPackageSrc) {
-            const { copied } = copyReadmeToPackageRoot({
-                sourceRoot: options.flutterPackageSrc,
-                targetRoot: resolvedDistPath,
-            });
-            if (copied) {
-                console.log('📄 Copied README.md to package root');
-            }
-        }
         console.log(`\nGenerating ${framework} code from ${options.flutterPackageSrc}...`);
         yield (0, generator_1.dartGen)({
             source: options.flutterPackageSrc,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@openwebf/webf",
-  "version": "0.24.0",
+  "version": "0.24.1",
   "description": "Command line tools for WebF",
   "main": "index.js",
   "bin": {
@@ -39,6 +39,7 @@
   "dependencies": {
     "@microsoft/tsdoc": "^0.15.1",
     "@microsoft/tsdoc-config": "^0.17.1",
+    "@openwebf/claude-code-skills": "^1.0.1",
     "commander": "^14.0.0",
     "glob": "^10.4.5",
     "inquirer": "^8.2.6",

package/src/agents.ts

@@ -0,0 +1,267 @@
+import fs from 'fs';
+import os from 'os';
+import path from 'path';
+import yaml from 'yaml';
+
+type SkillInfo = {
+  directoryName: string;
+  name: string;
+  description?: string;
+  skillFileRelativePath: string;
+  referenceRelativePaths: string[];
+};
+
+type CopyStats = {
+  filesWritten: number;
+  filesUnchanged: number;
+  backupsCreated: number;
+};
+
+const WEBF_AGENTS_BLOCK_START = '<!-- webf-agents:init start -->';
+const WEBF_AGENTS_BLOCK_END = '<!-- webf-agents:init end -->';
+
+function ensureDirSync(dirPath: string) {
+  fs.mkdirSync(dirPath, { recursive: true });
+}
+
+function readFileIfExists(filePath: string): Buffer | null {
+  try {
+    return fs.readFileSync(filePath);
+  } catch (error: any) {
+    if (error?.code === 'ENOENT') return null;
+    throw error;
+  }
+}
+
+function backupFileSync(filePath: string) {
+  const timestamp = new Date()
+    .toISOString()
+    .replace(/[:.]/g, '')
+    .replace('T', '')
+    .replace('Z', 'Z');
+  const backupPath = `${filePath}.bak.${timestamp}`;
+  fs.copyFileSync(filePath, backupPath);
+  return backupPath;
+}
+
+function copyFileWithBackupSync(srcPath: string, destPath: string) {
+  const src = fs.readFileSync(srcPath);
+  const dest = readFileIfExists(destPath);
+
+  if (dest && Buffer.compare(src, dest) === 0) return { changed: false, backupPath: null as string | null };
+
+  ensureDirSync(path.dirname(destPath));
+  let backupPath: string | null = null;
+  if (dest) {
+    backupPath = backupFileSync(destPath);
+  }
+  fs.writeFileSync(destPath, src);
+  return { changed: true, backupPath };
+}
+
+function copyDirRecursiveSync(srcDir: string, destDir: string, stats: CopyStats) {
+  ensureDirSync(destDir);
+  const entries = fs.readdirSync(srcDir, { withFileTypes: true });
+  for (const entry of entries) {
+    const srcPath = path.join(srcDir, entry.name);
+    const destPath = path.join(destDir, entry.name);
+    if (entry.isDirectory()) {
+      copyDirRecursiveSync(srcPath, destPath, stats);
+      continue;
+    }
+    if (entry.isFile()) {
+      const { changed, backupPath } = copyFileWithBackupSync(srcPath, destPath);
+      if (changed) stats.filesWritten += 1;
+      else stats.filesUnchanged += 1;
+      if (backupPath) stats.backupsCreated += 1;
+    }
+  }
+}
+
+function listFilesRecursiveSync(dirPath: string): string[] {
+  const out: string[] = [];
+  const entries = fs.readdirSync(dirPath, { withFileTypes: true });
+  for (const entry of entries) {
+    const entryPath = path.join(dirPath, entry.name);
+    if (entry.isDirectory()) {
+      out.push(...listFilesRecursiveSync(entryPath));
+      continue;
+    }
+    if (entry.isFile()) out.push(entryPath);
+  }
+  return out;
+}
+
+function toPosixRelativePath(fromDir: string, absolutePath: string) {
+  const rel = path.relative(fromDir, absolutePath);
+  return rel.split(path.sep).join('/');
+}
+
+function parseSkillFrontmatter(skillMd: string): { name?: string; description?: string } {
+  const trimmed = skillMd.trimStart();
+  if (!trimmed.startsWith('---')) return {};
+  const endIndex = trimmed.indexOf('\n---', 3);
+  if (endIndex === -1) return {};
+  const fm = trimmed.slice(3, endIndex).trim();
+  try {
+    const parsed = yaml.parse(fm) ?? {};
+    return { name: parsed?.name, description: parsed?.description };
+  } catch {
+    return {};
+  }
+}
+
+function updateOrAppendMarkedBlock(existing: string, newBlock: string): { content: string; action: 'replaced' | 'appended' } {
+  const startIndex = existing.indexOf(WEBF_AGENTS_BLOCK_START);
+  const endIndex = existing.indexOf(WEBF_AGENTS_BLOCK_END);
+
+  if (startIndex !== -1 && endIndex !== -1 && endIndex > startIndex) {
+    const before = existing.slice(0, startIndex).trimEnd();
+    const after = existing.slice(endIndex + WEBF_AGENTS_BLOCK_END.length).trimStart();
+    const next = [before, newBlock.trim(), after].filter(Boolean).join('\n\n');
+    return { content: next + '\n', action: 'replaced' };
+  }
+
+  const content = existing.trimEnd();
+  return { content: (content ? content + '\n\n' : '') + newBlock.trim() + '\n', action: 'appended' };
+}
+
+function buildClaudeBlock(sourcePackageName: string, sourcePackageVersion: string, skills: SkillInfo[]) {
+  const lines: string[] = [];
+  lines.push(WEBF_AGENTS_BLOCK_START);
+  lines.push('## WebF Claude Code Skills');
+  lines.push('');
+  lines.push(`Source: \`${sourcePackageName}@${sourcePackageVersion}\``);
+  lines.push('');
+  lines.push('### Skills');
+  for (const skill of skills) {
+    const desc = skill.description ? ` — ${skill.description}` : '';
+    lines.push(`- \`${skill.name}\`${desc} (\`${skill.skillFileRelativePath}\`)`);
+  }
+
+  const anyReferences = skills.some(s => s.referenceRelativePaths.length > 0);
+  if (anyReferences) {
+    lines.push('');
+    lines.push('### References');
+    for (const skill of skills) {
+      if (skill.referenceRelativePaths.length === 0) continue;
+      const refs = skill.referenceRelativePaths.map(r => `\`${r}\``).join(', ');
+      lines.push(`- \`${skill.name}\`: ${refs}`);
+    }
+  }
+
+  lines.push(WEBF_AGENTS_BLOCK_END);
+  return lines.join('\n');
+}
+
+function resolveSkillsPackageRoot() {
+  const packageJsonPath = require.resolve('@openwebf/claude-code-skills/package.json');
+  const packageRoot = path.dirname(packageJsonPath);
+  const packageJson = JSON.parse(fs.readFileSync(packageJsonPath, 'utf-8'));
+  return {
+    packageRoot,
+    packageName: packageJson?.name ?? '@openwebf/claude-code-skills',
+    packageVersion: packageJson?.version ?? 'unknown',
+  };
+}
+
+function listSkillDirectories(skillsPackageRoot: string) {
+  const entries = fs.readdirSync(skillsPackageRoot, { withFileTypes: true });
+  const dirs = entries
+    .filter(e => e.isDirectory())
+    .map(e => e.name)
+    .filter(name => fs.existsSync(path.join(skillsPackageRoot, name, 'SKILL.md')))
+    .sort();
+  return dirs;
+}
+
+function collectSkillInfo(projectRoot: string, skillsDir: string, skillDirectoryName: string): SkillInfo {
+  const skillDirAbs = path.join(skillsDir, skillDirectoryName);
+  const skillMdAbs = path.join(skillDirAbs, 'SKILL.md');
+  const skillMd = fs.readFileSync(skillMdAbs, 'utf-8');
+  const fm = parseSkillFrontmatter(skillMd);
+
+  const referenceRelativePaths: string[] = [];
+  const files = listFilesRecursiveSync(skillDirAbs);
+  for (const fileAbs of files) {
+    if (path.basename(fileAbs) === 'SKILL.md') continue;
+    referenceRelativePaths.push(toPosixRelativePath(projectRoot, fileAbs));
+  }
+  referenceRelativePaths.sort();
+
+  return {
+    directoryName: skillDirectoryName,
+    name: fm.name ?? skillDirectoryName,
+    description: fm.description,
+    skillFileRelativePath: toPosixRelativePath(projectRoot, skillMdAbs),
+    referenceRelativePaths,
+  };
+}
+
+async function agentsInitCommand(projectDir: string): Promise<void> {
+  const startedAt = Date.now();
+  const resolvedProjectDir = path.resolve(process.cwd(), projectDir || '.');
+  const claudeMdPath = path.join(resolvedProjectDir, 'CLAUDE.md');
+  const claudeDir = path.join(resolvedProjectDir, '.claude');
+  const projectSkillsDir = path.join(claudeDir, 'skills');
+
+  const hasClaudeMd = fs.existsSync(claudeMdPath);
+  const hasClaudeDir = fs.existsSync(claudeDir);
+
+  const isNewProject = !hasClaudeMd && !hasClaudeDir;
+
+  console.log('webf agents init');
+  console.log(`Project: ${resolvedProjectDir}`);
+  if (isNewProject) {
+    console.log('Detected: no CLAUDE.md and no .claude/ (new project)');
+  } else {
+    console.log(`Detected: CLAUDE.md=${hasClaudeMd ? 'yes' : 'no'}, .claude/=${hasClaudeDir ? 'yes' : 'no'} (existing project)`);
+  }
+
+  const { packageRoot, packageName, packageVersion } = resolveSkillsPackageRoot();
+  const skillDirectories = listSkillDirectories(packageRoot);
+
+  if (skillDirectories.length === 0) {
+    throw new Error(`No skills found in ${packageName} (resolved at ${packageRoot}).`);
+  }
+
+  console.log(`Skills source: ${packageName}@${packageVersion}`);
+  console.log(`Skills destination: ${toPosixRelativePath(resolvedProjectDir, projectSkillsDir)}`);
+
+  ensureDirSync(projectSkillsDir);
+
+  const copyStats: CopyStats = { filesWritten: 0, filesUnchanged: 0, backupsCreated: 0 };
+  for (const skillDirName of skillDirectories) {
+    const srcSkillDir = path.join(packageRoot, skillDirName);
+    const destSkillDir = path.join(projectSkillsDir, skillDirName);
+
+    copyDirRecursiveSync(srcSkillDir, destSkillDir, copyStats);
+  }
+
+  const installedSkills = skillDirectories.map(skillDirName =>
+    collectSkillInfo(resolvedProjectDir, projectSkillsDir, skillDirName)
+  );
+
+  const block = buildClaudeBlock(packageName, packageVersion, installedSkills);
+
+  if (isNewProject) {
+    const initial = ['# Claude Code', '', block, ''].join('\n');
+    fs.writeFileSync(claudeMdPath, initial, 'utf-8');
+    console.log(`Created ${toPosixRelativePath(resolvedProjectDir, claudeMdPath)}`);
+  } else {
+    const existing = readFileIfExists(claudeMdPath)?.toString('utf-8') ?? '';
+    const { content, action } = updateOrAppendMarkedBlock(existing, block);
+    fs.writeFileSync(claudeMdPath, content, 'utf-8');
+    console.log(`${action === 'replaced' ? 'Updated' : 'Appended'} WebF skills block in ${toPosixRelativePath(resolvedProjectDir, claudeMdPath)}`);
+  }
+
+  const versionFilePath = path.join(claudeDir, 'webf-claude-code-skills.version');
+  fs.writeFileSync(versionFilePath, `${packageName}@${packageVersion}${os.EOL}`, 'utf-8');
+  console.log(`Wrote ${toPosixRelativePath(resolvedProjectDir, versionFilePath)}`);
+
+  console.log(
+    `Installed ${installedSkills.length} skills (${copyStats.filesWritten} files written, ${copyStats.filesUnchanged} unchanged, ${copyStats.backupsCreated} backups) in ${Date.now() - startedAt}ms`
+  );
+}
+
+export { agentsInitCommand };

package/src/commands.ts

@@ -9,6 +9,7 @@ import { globSync } from 'glob';
 import _ from 'lodash';
 import inquirer from 'inquirer';
 import yaml from 'yaml';
+import { agentsInitCommand } from './agents';
 
 interface GenerateOptions {
   flutterPackageSrc?: string;
@@ -238,40 +239,6 @@ function readFlutterPackageMetadata(packagePath: string): FlutterPackageMetadata
   }
 }
 
-function copyReadmeToPackageRoot(params: {
-  sourceRoot: string;
-  targetRoot: string;
-}): { copied: boolean; sourcePath?: string; targetPath: string } {
-  const { sourceRoot, targetRoot } = params;
-  const targetPath = path.join(targetRoot, 'README.md');
-
-  if (fs.existsSync(targetPath)) {
-    return { copied: false, targetPath };
-  }
-
-  const candidateNames = ['README.md', 'Readme.md', 'readme.md'];
-  let sourcePath: string | null = null;
-  for (const candidate of candidateNames) {
-    const abs = path.join(sourceRoot, candidate);
-    if (fs.existsSync(abs)) {
-      sourcePath = abs;
-      break;
-    }
-  }
-
-  if (!sourcePath) {
-    return { copied: false, targetPath };
-  }
-
-  try {
-    const content = fs.readFileSync(sourcePath, 'utf-8');
-    writeFileIfChanged(targetPath, content);
-    return { copied: true, sourcePath, targetPath };
-  } catch {
-    return { copied: false, targetPath };
-  }
-}
-
 // Copy markdown docs that match .d.ts basenames from source to the built dist folder,
 // and generate an aggregated README.md in the dist directory.
 async function copyMarkdownDocsToDist(params: {
@@ -813,17 +780,6 @@ async function generateCommand(distPath: string, options: GenerateOptions): Prom
   // Auto-initialize typings in the output directory if needed
   ensureInitialized(resolvedDistPath);
 
-  // Copy README.md from the source Flutter package into the npm package root (so `npm publish` includes it).
-  if (options.flutterPackageSrc) {
-    const { copied } = copyReadmeToPackageRoot({
-      sourceRoot: options.flutterPackageSrc,
-      targetRoot: resolvedDistPath,
-    });
-    if (copied) {
-      console.log('📄 Copied README.md to package root');
-    }
-  }
-
   console.log(`\nGenerating ${framework} code from ${options.flutterPackageSrc}...`);
 
   await dartGen({
@@ -1446,4 +1402,4 @@ async function buildAndPublishPackage(packagePath: string, registry?: string, is
   }
 }
 
-export { generateCommand, generateModuleCommand };
+export { generateCommand, generateModuleCommand, agentsInitCommand };

package/templates/react.package.json.tpl

@@ -5,7 +5,7 @@
   "main": "dist/index.js",
   "module": "dist/index.mjs",
   "types": "dist/index.d.ts",
-  "files": ["dist", "README.md"],
+  "files": ["dist"],
   "scripts": {
     "build": "tsup"
   },

package/templates/vue.package.json.tpl

@@ -4,7 +4,7 @@
   "description": "<%= description %>",
   "main": "",
   "types": "index.d.ts",
-  "files": ["index.d.ts", "README.md"],
+  "files": ["index.d.ts"],
   "keywords": [],
   "author": "",
   "license": "ISC",

package/test/agents-init.test.ts

@@ -0,0 +1,80 @@
+import fs from 'fs';
+import os from 'os';
+import path from 'path';
+import { agentsInitCommand } from '../src/agents';
+
+function readText(filePath: string) {
+  return fs.readFileSync(filePath, 'utf-8');
+}
+
+describe('webf agents init', () => {
+  let tempDir: string;
+  let consoleSpy: jest.SpyInstance;
+
+  beforeEach(() => {
+    tempDir = fs.mkdtempSync(path.join(os.tmpdir(), 'webf-agents-init-'));
+    consoleSpy = jest.spyOn(console, 'log').mockImplementation(() => {});
+  });
+
+  afterEach(() => {
+    consoleSpy.mockRestore();
+    fs.rmSync(tempDir, { recursive: true, force: true });
+  });
+
+  it('initializes a new project with skills and CLAUDE.md', async () => {
+    await agentsInitCommand(tempDir);
+
+    expect(fs.existsSync(path.join(tempDir, 'CLAUDE.md'))).toBe(true);
+    expect(fs.existsSync(path.join(tempDir, '.claude', 'skills', 'webf-quickstart', 'SKILL.md'))).toBe(true);
+
+    const claude = readText(path.join(tempDir, 'CLAUDE.md'));
+    expect(claude).toContain('<!-- webf-agents:init start -->');
+    expect(claude).toContain('Source: `@openwebf/claude-code-skills@');
+    expect(claude).toContain('### Skills');
+
+    const version = readText(path.join(tempDir, '.claude', 'webf-claude-code-skills.version'));
+    expect(version).toMatch(/^@openwebf\/claude-code-skills@/);
+  });
+
+  it('updates an existing CLAUDE.md without removing existing content', async () => {
+    fs.writeFileSync(path.join(tempDir, 'CLAUDE.md'), '# Existing\n\nHello\n', 'utf-8');
+
+    await agentsInitCommand(tempDir);
+
+    const claude = readText(path.join(tempDir, 'CLAUDE.md'));
+    expect(claude).toContain('# Existing');
+    expect(claude).toContain('Hello');
+    expect(claude).toContain('<!-- webf-agents:init start -->');
+  });
+
+  it('is idempotent (does not duplicate the injected block)', async () => {
+    await agentsInitCommand(tempDir);
+    await agentsInitCommand(tempDir);
+
+    const claude = readText(path.join(tempDir, 'CLAUDE.md'));
+    const occurrences = claude.split('<!-- webf-agents:init start -->').length - 1;
+    expect(occurrences).toBe(1);
+  });
+
+  it('backs up modified skill files before overwriting', async () => {
+    const skillDir = path.join(tempDir, '.claude', 'skills', 'webf-quickstart');
+    fs.mkdirSync(skillDir, { recursive: true });
+    fs.writeFileSync(path.join(skillDir, 'SKILL.md'), 'local edits', 'utf-8');
+
+    await agentsInitCommand(tempDir);
+
+    const files = fs.readdirSync(skillDir);
+    expect(files.some(f => f.startsWith('SKILL.md.bak.'))).toBe(true);
+
+    const sourceSkill = fs.readFileSync(
+      path.join(
+        path.dirname(require.resolve('@openwebf/claude-code-skills/package.json')),
+        'webf-quickstart',
+        'SKILL.md'
+      ),
+      'utf-8'
+    );
+    const installedSkill = readText(path.join(skillDir, 'SKILL.md'));
+    expect(installedSkill).toBe(sourceSkill);
+  });
+});

package/test/commands.test.ts

@@ -456,78 +456,6 @@ describe('Commands', () => {
       }));
     });
 
-    it('should copy Flutter README.md into generated React package root', async () => {
-      const options = {
-        flutterPackageSrc: '/flutter/src',
-        framework: 'react',
-        packageName: 'test-package'
-      };
-
-      // Mock TypeScript validation
-      mockTypeScriptValidation('/flutter/src');
-
-      const originalExistsSync = mockFs.existsSync as jest.Mock;
-      mockFs.existsSync = jest.fn().mockImplementation((filePath: any) => {
-        const pathStr = filePath.toString();
-        if (pathStr === '/flutter/src/README.md') return true;
-        if (pathStr === path.join(path.resolve('/dist'), 'README.md')) return false;
-        return originalExistsSync(filePath);
-      });
-
-      const originalReadFileSync = mockFs.readFileSync as jest.Mock;
-      mockFs.readFileSync = jest.fn().mockImplementation((filePath: any, encoding?: any) => {
-        const pathStr = filePath.toString();
-        if (pathStr === '/flutter/src/README.md') {
-          return '# Flutter README\n\nHello';
-        }
-        return originalReadFileSync(filePath, encoding);
-      });
-
-      await generateCommand('/dist', options);
-
-      expect(mockFs.writeFileSync).toHaveBeenCalledWith(
-        path.join(path.resolve('/dist'), 'README.md'),
-        '# Flutter README\n\nHello',
-        'utf-8'
-      );
-    });
-
-    it('should copy Flutter README.md into generated Vue package root', async () => {
-      const options = {
-        flutterPackageSrc: '/flutter/src',
-        framework: 'vue',
-        packageName: 'test-package'
-      };
-
-      // Mock TypeScript validation
-      mockTypeScriptValidation('/flutter/src');
-
-      const originalExistsSync = mockFs.existsSync as jest.Mock;
-      mockFs.existsSync = jest.fn().mockImplementation((filePath: any) => {
-        const pathStr = filePath.toString();
-        if (pathStr === '/flutter/src/README.md') return true;
-        if (pathStr === path.join(path.resolve('/dist'), 'README.md')) return false;
-        return originalExistsSync(filePath);
-      });
-
-      const originalReadFileSync = mockFs.readFileSync as jest.Mock;
-      mockFs.readFileSync = jest.fn().mockImplementation((filePath: any, encoding?: any) => {
-        const pathStr = filePath.toString();
-        if (pathStr === '/flutter/src/README.md') {
-          return '# Flutter README\n\nHello';
-        }
-        return originalReadFileSync(filePath, encoding);
-      });
-
-      await generateCommand('/dist', options);
-
-      expect(mockFs.writeFileSync).toHaveBeenCalledWith(
-        path.join(path.resolve('/dist'), 'README.md'),
-        '# Flutter README\n\nHello',
-        'utf-8'
-      );
-    });
-
     it('should generate an aggregated README in dist from markdown docs', async () => {
       const options = {
         flutterPackageSrc: '/flutter/src',