feat(skill): Add Claude Agent Skills generation support

.gitignore

@@ -44,6 +44,9 @@ repomix-output.json
 # repomix runner
 .repomix/
 
+# repomix references
+.claude/skills/repomix-reference-*/
+
 # Agent
 /.mcp.json
 .agents/local/

src/cli/actions/defaultAction.ts

@@ -1,3 +1,4 @@
+import path from 'node:path';
 import { loadFileConfig, mergeConfigs } from '../../config/configLoad.js';
 import {
   type RepomixConfigCli,
@@ -8,11 +9,13 @@ import {
 } from '../../config/configSchema.js';
 import { readFilePathsFromStdin } from '../../core/file/fileStdin.js';
 import type { PackResult } from '../../core/packager.js';
+import { generateDefaultSkillName } from '../../core/skill/skillUtils.js';
 import { RepomixError, rethrowValidationErrorIfZodError } from '../../shared/errorHandle.js';
 import { logger } from '../../shared/logger.js';
 import { splitPatterns } from '../../shared/patternUtils.js';
 import { initTaskRunner } from '../../shared/processConcurrency.js';
 import { reportResults } from '../cliReport.js';
+import { promptSkillLocation } from '../prompts/skillPrompts.js';
 import type { CliOptions } from '../types.js';
 import { runMigrationAction } from './migrationAction.js';
 import type {
@@ -49,6 +52,32 @@ export const runDefaultAction = async (
   const config: RepomixConfigMerged = mergeConfigs(cwd, fileConfig, cliConfig);
   logger.trace('Merged config:', config);
 
+  // Validate skill generation options and prompt for location
+  if (config.skillGenerate !== undefined) {
+    if (config.output.stdout) {
+      throw new RepomixError(
+        '--skill-generate cannot be used with --stdout. Skill output requires writing to filesystem.',
+      );
+    }
+    if (config.output.copyToClipboard) {
+      throw new RepomixError(
+        '--skill-generate cannot be used with --copy. Skill output is a directory and cannot be copied to clipboard.',
+      );
+    }
+
+    // Resolve skill name: use pre-computed name (from remoteAction) or generate from directory
+    cliOptions.skillName ??=
+      typeof config.skillGenerate === 'string'
+        ? config.skillGenerate
+        : generateDefaultSkillName(directories.map((d) => path.resolve(cwd, d)));
+
+    // Prompt for skill location if not already set (from remoteAction)
+    if (!cliOptions.skillDir) {
+      const promptResult = await promptSkillLocation(cliOptions.skillName, cwd);
+      cliOptions.skillDir = promptResult.skillDir;
+    }
+  }
+
   // Handle stdin processing in main process (before worker creation)
   // This is necessary because child_process workers don't inherit stdin
   let stdinFilePaths: string[] | undefined;
@@ -90,7 +119,7 @@ export const runDefaultAction = async (
     const result = (await taskRunner.run(task)) as DefaultActionWorkerResult;
 
     // Report results in main process
-    reportResults(cwd, result.packResult, result.config);
+    reportResults(cwd, result.packResult, result.config, cliOptions);
 
     return {
       packResult: result.packResult,
@@ -287,6 +316,11 @@ export const buildCliConfig = (options: CliOptions): RepomixConfigCli => {
     };
   }
 
+  // Skill generation
+  if (options.skillGenerate !== undefined) {
+    cliConfig.skillGenerate = options.skillGenerate;
+  }
+
   try {
     return repomixConfigCliSchema.parse(cliConfig);
   } catch (error) {

src/cli/actions/remoteAction.ts

@@ -7,9 +7,11 @@ import { downloadGitHubArchive, isArchiveDownloadSupported } from '../../core/gi
 import { getRemoteRefs } from '../../core/git/gitRemoteHandle.js';
 import { isGitHubRepository, parseGitHubRepoInfo, parseRemoteValue } from '../../core/git/gitRemoteParse.js';
 import { isGitInstalled } from '../../core/git/gitRepositoryHandle.js';
+import { generateDefaultSkillNameFromUrl } from '../../core/skill/skillUtils.js';
 import { RepomixError } from '../../shared/errorHandle.js';
 import { logger } from '../../shared/logger.js';
 import { Spinner } from '../cliSpinner.js';
+import { promptSkillLocation, type SkillLocation } from '../prompts/skillPrompts.js';
 import type { CliOptions } from '../types.js';
 import { type DefaultActionRunnerResult, runDefaultAction } from './defaultAction.js';
 
@@ -88,14 +90,37 @@ export const runRemoteAction = async (
       downloadMethod = 'git';
     }
 
+    // For skill generation, prompt for location using current directory (not temp directory)
+    let skillName: string | undefined;
+    let skillDir: string | undefined;
+    let skillLocation: SkillLocation | undefined;
+    if (cliOptions.skillGenerate !== undefined) {
+      skillName =
+        typeof cliOptions.skillGenerate === 'string'
+          ? cliOptions.skillGenerate
+          : generateDefaultSkillNameFromUrl(repoUrl);
+
+      const promptResult = await promptSkillLocation(skillName, process.cwd());
+      skillDir = promptResult.skillDir;
+      skillLocation = promptResult.location;
+    }
+
     // Run the default action on the downloaded/cloned repository
-    result = await deps.runDefaultAction([tempDirPath], tempDirPath, cliOptions);
+    // Pass the pre-computed skill name and directory
+    const optionsWithSkill = { ...cliOptions, skillName, skillDir };
+    result = await deps.runDefaultAction([tempDirPath], tempDirPath, optionsWithSkill);
 
-    // Copy output file only when not in stdout mode
-    // In stdout mode, output is written directly to stdout without creating a file,
-    // so attempting to copy a non-existent file would cause an error and exit code 1
+    // Copy output to current directory
+    // Skip copy for stdout mode (output goes directly to stdout)
+    // For skill generation with project location, copy the skill directory
+    // For personal location, skill is already written to ~/.claude/skills/
     if (!cliOptions.stdout) {
-      await copyOutputToCurrentDirectory(tempDirPath, process.cwd(), result.config.output.filePath);
+      if (result.config.skillGenerate !== undefined && skillLocation === 'project') {
+        // Copy skill directory to current directory (only for project skills)
+        await copySkillOutputToCurrentDirectory(tempDirPath, process.cwd());
+      } else if (result.config.skillGenerate === undefined) {
+        await copyOutputToCurrentDirectory(tempDirPath, process.cwd(), result.config.output.filePath);
+      }
     }
 
     logger.trace(`Repository obtained via ${downloadMethod} method`);
@@ -183,6 +208,40 @@ export const cleanupTempDirectory = async (directory: string): Promise<void> =>
   await fs.rm(directory, { recursive: true, force: true });
 };
 
+export const copySkillOutputToCurrentDirectory = async (sourceDir: string, targetDir: string): Promise<void> => {
+  const sourceClaudeDir = path.join(sourceDir, '.claude');
+  const targetClaudeDir = path.join(targetDir, '.claude');
+
+  try {
+    // Check if source .claude directory exists
+    await fs.access(sourceClaudeDir);
+  } catch {
+    // No skill output was generated
+    logger.trace('No .claude directory found in source, skipping skill output copy');
+    return;
+  }
+
+  try {
+    logger.trace(`Copying skill output from: ${sourceClaudeDir} to: ${targetClaudeDir}`);
+
+    // Copy the entire .claude directory
+    await fs.cp(sourceClaudeDir, targetClaudeDir, { recursive: true });
+  } catch (error) {
+    const nodeError = error as NodeJS.ErrnoException;
+
+    if (nodeError.code === 'EPERM' || nodeError.code === 'EACCES') {
+      throw new RepomixError(
+        `Failed to copy skill output to ${targetClaudeDir}: Permission denied.
+
+The current directory may be protected or require elevated permissions.
+Please try running from a different directory (e.g., your home directory or Documents folder).`,
+      );
+    }
+
+    throw new RepomixError(`Failed to copy skill output: ${(error as Error).message}`);
+  }
+};
+
 export const copyOutputToCurrentDirectory = async (
   sourceDir: string,
   targetDir: string,

src/cli/actions/workers/defaultActionWorker.ts

@@ -55,6 +55,9 @@ async function defaultActionWorker(
   let packResult: PackResult;
 
   try {
+    const { skillName, skillDir } = cliOptions;
+    const packOptions = { skillName, skillDir };
+
     if (stdinFilePaths) {
       // Handle stdin processing with file paths from main process
       // File paths were already read from stdin in the main process
@@ -69,14 +72,22 @@ async function defaultActionWorker(
         },
         {},
         stdinFilePaths,
+        packOptions,
       );
     } else {
       // Handle directory processing
       const targetPaths = directories.map((directory) => path.resolve(cwd, directory));
 
-      packResult = await pack(targetPaths, config, (message) => {
-        spinner.update(message);
-      });
+      packResult = await pack(
+        targetPaths,
+        config,
+        (message) => {
+          spinner.update(message);
+        },
+        {},
+        undefined,
+        packOptions,
+      );
     }
 
     spinner.succeed('Packing completed successfully!');

src/cli/cliReport.ts

@@ -7,10 +7,26 @@ import type { SuspiciousFileResult } from '../core/security/securityCheck.js';
 import { logger } from '../shared/logger.js';
 import { reportTokenCountTree } from './reporters/tokenCountTreeReporter.js';
 
+/**
+ * Convert an absolute path to a relative path if it's under cwd, otherwise return as-is.
+ */
+export const getDisplayPath = (absolutePath: string, cwd: string): string => {
+  return absolutePath.startsWith(cwd) ? path.relative(cwd, absolutePath) : absolutePath;
+};
+
+export interface ReportOptions {
+  skillDir?: string;
+}
+
 /**
  * Reports the results of packing operation including top files, security check, summary, and completion.
  */
-export const reportResults = (cwd: string, packResult: PackResult, config: RepomixConfigMerged): void => {
+export const reportResults = (
+  cwd: string,
+  packResult: PackResult,
+  config: RepomixConfigMerged,
+  options: ReportOptions = {},
+): void => {
   logger.log('');
 
   if (config.output.topFilesLength > 0) {
@@ -40,13 +56,18 @@ export const reportResults = (cwd: string, packResult: PackResult, config: Repom
   reportSkippedFiles(cwd, packResult.skippedFiles);
   logger.log('');
 
-  reportSummary(packResult, config);
+  reportSummary(cwd, packResult, config, options);
   logger.log('');
 
   reportCompletion();
 };
 
-export const reportSummary = (packResult: PackResult, config: RepomixConfigMerged) => {
+export const reportSummary = (
+  cwd: string,
+  packResult: PackResult,
+  config: RepomixConfigMerged,
+  options: ReportOptions = {},
+) => {
   let securityCheckMessage = '';
   if (config.security.enableSecurityCheck) {
     if (packResult.suspiciousFilesResults.length > 0) {
@@ -65,7 +86,16 @@ export const reportSummary = (packResult: PackResult, config: RepomixConfigMerge
   logger.log(`${pc.white('  Total Files:')} ${pc.white(packResult.totalFiles.toLocaleString())} files`);
   logger.log(`${pc.white(' Total Tokens:')} ${pc.white(packResult.totalTokens.toLocaleString())} tokens`);
   logger.log(`${pc.white('  Total Chars:')} ${pc.white(packResult.totalCharacters.toLocaleString())} chars`);
-  logger.log(`${pc.white('       Output:')} ${pc.white(config.output.filePath)}`);
+
+  // Show skill output path or regular output path
+  if (config.skillGenerate !== undefined && options.skillDir) {
+    const displayPath = getDisplayPath(options.skillDir, cwd);
+    logger.log(`${pc.white('       Output:')} ${pc.white(displayPath)} ${pc.dim('(skill directory)')}`);
+  } else {
+    const outputPath = path.resolve(cwd, config.output.filePath);
+    const displayPath = getDisplayPath(outputPath, cwd);
+    logger.log(`${pc.white('       Output:')} ${pc.white(displayPath)}`);
+  }
   logger.log(`${pc.white('     Security:')} ${pc.white(securityCheckMessage)}`);
 
   if (config.output.git?.includeDiffs) {

src/cli/cliRun.ts

@@ -168,6 +168,12 @@ export const run = async () => {
       // MCP
       .optionsGroup('MCP')
       .option('--mcp', 'Run as Model Context Protocol server for AI tool integration')
+      // Skill Generation
+      .optionsGroup('Skill Generation (Experimental)')
+      .option(
+        '--skill-generate [name]',
+        'Generate Claude Agent Skills format output to .claude/skills/<name>/ directory (name auto-generated if omitted)',
+      )
       .action(commanderActionEndpoint);
 
     // Custom error handling function

src/cli/prompts/skillPrompts.ts

@@ -0,0 +1,92 @@
+import fs from 'node:fs/promises';
+import os from 'node:os';
+import path from 'node:path';
+import * as prompts from '@clack/prompts';
+import pc from 'picocolors';
+import { OperationCancelledError } from '../../shared/errorHandle.js';
+import { getDisplayPath } from '../cliReport.js';
+
+export type SkillLocation = 'personal' | 'project';
+
+export interface SkillPromptResult {
+  location: SkillLocation;
+  skillDir: string;
+}
+
+const onCancelOperation = (): never => {
+  prompts.cancel('Skill generation cancelled.');
+  throw new OperationCancelledError('Skill generation cancelled');
+};
+
+/**
+ * Get the base directory for skills based on location type.
+ */
+export const getSkillBaseDir = (cwd: string, location: SkillLocation): string => {
+  if (location === 'personal') {
+    return path.join(os.homedir(), '.claude', 'skills');
+  }
+  return path.join(cwd, '.claude', 'skills');
+};
+
+/**
+ * Prompt user for skill location and handle overwrite confirmation.
+ */
+export const promptSkillLocation = async (
+  skillName: string,
+  cwd: string,
+  deps = {
+    select: prompts.select,
+    confirm: prompts.confirm,
+    isCancel: prompts.isCancel,
+    access: fs.access,
+  },
+): Promise<SkillPromptResult> => {
+  // Step 1: Ask for skill location
+  const location = await deps.select({
+    message: 'Where would you like to save the skill?',
+    options: [
+      {
+        value: 'personal' as SkillLocation,
+        label: 'Personal Skills',
+        hint: '~/.claude/skills/ - Available across all projects',
+      },
+      {
+        value: 'project' as SkillLocation,
+        label: 'Project Skills',
+        hint: '.claude/skills/ - Shared with team via git',
+      },
+    ],
+    initialValue: 'personal' as SkillLocation,
+  });
+
+  if (deps.isCancel(location)) {
+    onCancelOperation();
+  }
+
+  const skillDir = path.join(getSkillBaseDir(cwd, location as SkillLocation), skillName);
+
+  // Step 2: Check if directory exists and ask for overwrite
+  let dirExists = false;
+  try {
+    await deps.access(skillDir);
+    dirExists = true;
+  } catch {
+    // Directory doesn't exist
+  }
+
+  if (dirExists) {
+    const displayPath = getDisplayPath(skillDir, cwd);
+    const overwrite = await deps.confirm({
+      message: `Skill directory already exists. Do you want to overwrite it?\n${pc.dim(`path: ${displayPath}`)}`,
+    });
+
+    if (deps.isCancel(overwrite) || !overwrite) {
+      onCancelOperation();
+    }
+  }
+
+  return {
+    location: location as SkillLocation,
+    skillDir,
+  };
+};

src/cli/types.ts

@@ -55,6 +55,11 @@ export interface CliOptions extends OptionValues {
   // MCP
   mcp?: boolean;
 
+  // Skill Generation
+  skillGenerate?: string | boolean;
+  skillName?: string; // Pre-computed skill name (used internally for remote repos)
+  skillDir?: string; // Pre-computed skill directory (used internally for remote repos)
+
   // Other Options
   topFilesLen?: number;
   verbose?: boolean;