Add root skill-install flag for Claude, Codex, and OpenClaw (#3137)

## Summary
- Adds a root-level `--instal-skill` / `--install-skill` flag so users
can install the composio skill without going through a subcommand.
- Supports selecting the target agent (`claude`, `codex`, or `openclaw`)
and optionally overriding the installed skill name.
- Updates the install flow to place the skill under the chosen agent’s
skills directory and report the selected target in success/warning
messages.
- Documents the new root flag in the CLI README and root help output.
- Adds coverage for flag parsing, target path resolution, and skill-name
validation.

## Testing
- `pnpm test
ts/packages/cli/test/src/commands/install-skill-root-flag.test.ts`
- `pnpm test ts/packages/cli/test/src/effects/install-skill.test.ts`
- Not run: full repository test suite

Author: CryogenicPlanet

ts/packages/cli/README.md

@@ -22,6 +22,7 @@ composio [--log-level all|trace|debug|info|warning|error|fatal|none]
 ### Optional Flags
 
 - `--log-level`: Set the log verbosity level. Accepted values: all, trace, debug, info, warning, error, fatal, none
+- `--instal-skill [skill-name] <claude|codex|openclaw>`: Manually install the composio skill for a supported agent when automatic installation fails. `--install-skill` is accepted as an alias.
 
 ## 🧭 Commands
 
@@ -43,6 +44,7 @@ composio [--log-level all|trace|debug|info|warning|error|fatal|none]
 - `composio generate py [-o, --output-dir <directory>] [--toolkits <toolkit>]`: Generate Python type stubs for toolkits, tools, and triggers from the Composio API.
 - `composio generate ts [-o, --output-dir <directory>] [--compact] [--transpiled] [--type-tools] [--toolkits <toolkit>]`: Generate TypeScript types for toolkits, tools, and triggers from the Composio API.
 - `composio upgrade [--beta]`: Self-update the Composio CLI from the stable channel, or from the beta channel with `--beta`.
+- `composio --instal-skill [skill-name] <claude|codex|openclaw>`: Manually install the composio skill for Claude, Codex, or OpenClaw.
 
 ## Configuration
 

ts/packages/cli/src/commands/index.ts

@@ -38,6 +38,7 @@ import {
   resolveCommandProject,
 } from 'src/services/command-project';
 import { CLI_EXPERIMENTAL_FEATURES } from 'src/constants';
+import { installSkill, type SkillInstallTarget } from 'src/effects/install-skill';
 import {
   experimental,
   type CommandVisibility,
@@ -75,6 +76,94 @@ export const buildRootCommand = (visibility: CommandVisibility) => {
   return $defaultCmd.pipe(Command.withSubcommands(subcommands as any));
 };
 
+const ROOT_INSTALL_SKILL_FLAGS = ['--instal-skill', '--install-skill'] as const;
+const SKILL_INSTALL_TARGETS = ['claude', 'codex', 'openclaw'] as const satisfies ReadonlyArray<
+  SkillInstallTarget
+>;
+
+type RootInstallSkillRequest =
+  | {
+      _tag: 'parsed';
+      skillName?: string;
+      target: SkillInstallTarget;
+    }
+  | { _tag: 'error'; message: string };
+
+const isSkillInstallTarget = (value: string): value is SkillInstallTarget =>
+  (SKILL_INSTALL_TARGETS as ReadonlyArray<string>).includes(value);
+
+export const parseRootInstallSkillRequest = (
+  argv: ReadonlyArray<string>
+): RootInstallSkillRequest | undefined => {
+  const args = argv.slice(2);
+  for (let i = 0; i < args.length; i += 1) {
+    const token = args[i];
+    if (!token) continue;
+
+    if ((ROOT_INSTALL_SKILL_FLAGS as ReadonlyArray<string>).includes(token)) {
+      const rawValues: string[] = [];
+      for (let j = i + 1; j < args.length; j += 1) {
+        const next = args[j];
+        if (!next) continue;
+        if (next.startsWith('-')) break;
+        rawValues.push(next);
+      }
+
+      if (rawValues.length === 0) {
+        return {
+          _tag: 'error',
+          message:
+            'Missing target for --instal-skill. Usage: composio --instal-skill [skill-name] <claude|codex|openclaw>',
+        };
+      }
+
+      if (rawValues.length === 1) {
+        const [target] = rawValues;
+        if (!isSkillInstallTarget(target)) {
+          return {
+            _tag: 'error',
+            message:
+              'Invalid target for --instal-skill. Expected one of: claude, codex, openclaw.',
+          };
+        }
+        return { _tag: 'parsed', target };
+      }
+
+      if (rawValues.length === 2) {
+        const [skillName, target] = rawValues;
+        if (!isSkillInstallTarget(target)) {
+          return {
+            _tag: 'error',
+            message:
+              'Invalid target for --instal-skill. Expected one of: claude, codex, openclaw.',
+          };
+        }
+        return { _tag: 'parsed', skillName, target };
+      }
+
+      return {
+        _tag: 'error',
+        message:
+          'Too many arguments for --instal-skill. Usage: composio --instal-skill [skill-name] <claude|codex|openclaw>',
+      };
+    }
+
+    if (token === '--log-level') {
+      i += 1;
+      continue;
+    }
+
+    if (token.startsWith('--log-level=')) {
+      continue;
+    }
+
+    if (!token.startsWith('-')) {
+      return undefined;
+    }
+  }
+  return undefined;
+};
+
 const parseExecuteInputHelpSlug = (argv: ReadonlyArray<string>): string | undefined => {
   const args = argv.slice(2);
   const isRootExecute = args[0] === 'execute';
@@ -269,6 +358,16 @@ export const runWithConfig = Effect.gen(function* () {
     const normalizedArgv = normalizeHiddenDebugFlags(
       normalizeListenStreamFlag(normalizeVersionShortFlag(argv))
     );
+    const installSkillRequest = parseRootInstallSkillRequest(normalizedArgv);
+    if (installSkillRequest) {
+      if (installSkillRequest._tag === 'error') {
+        return Effect.fail(new Error(installSkillRequest.message));
+      }
+      return installSkill({
+        skillName: installSkillRequest.skillName,
+        target: installSkillRequest.target,
+      });
+    }
     if (isRootHelp(normalizedArgv)) {
       return printRootHelp(visibility);
     }

ts/packages/cli/src/commands/root-help.ts

@@ -1175,6 +1175,10 @@ export function printRootHelp(visibility: CommandVisibility): Effect.Effect<void
     `  ${dim('# Run a script with injected helpers')}`,
     `  ${name} run 'const me = await execute("GITHUB_GET_THE_AUTHENTICATED_USER"); console.log(me)'`,
     '',
+    `  ${dim('# Manually install the composio skill when auto-install fails')}`,
+    `  ${name} --instal-skill claude`,
+    `  ${name} --instal-skill composio-cli codex`,
+    '',
     `  ${dim('# Run a multi-step script with Promise.all')}`,
     `  ${name} run '`,
     `    const [emails, issues] = await Promise.all([`,
@@ -1209,6 +1213,8 @@ export function printRootHelp(visibility: CommandVisibility): Effect.Effect<void
     bold('FLAGS'),
     '  -h, --help     Show help for command',
     `  --version      Show ${name} version`,
+    '  --instal-skill [skill-name] <claude|codex|openclaw>',
+    '                  Manually install the composio skill for a supported agent',
     '',
     bold('LEARN MORE'),
     `  Use \`${name} <command> --help\` for more information about a command.`,

ts/packages/cli/src/effects/install-skill.ts

@@ -16,6 +16,15 @@ import decompress from 'decompress';
 const SKILL_NAME = 'composio-cli';
 const SKILL_ASSET_NAME = 'composio-skill.zip';
 export type SkillReleaseChannel = CliReleaseChannel;
+export type SkillInstallTarget = 'claude' | 'codex' | 'openclaw';
+
+const SKILL_NAME_PATTERN = /^[A-Za-z0-9._-]+$/;
+
+const SKILL_TARGET_LABELS: Record<SkillInstallTarget, string> = {
+  claude: 'Claude Code',
+  codex: 'Codex',
+  openclaw: 'OpenClaw',
+};
 
 type GitHubConfig = GitHubRepoConfig & {
   TAG: Option.Option<string>;
@@ -25,6 +34,44 @@ type GitHubConfig = GitHubRepoConfig & {
 const hasSkillAsset = (release: GitHubRelease) =>
   release.assets.some(asset => asset.name === SKILL_ASSET_NAME);
 
+export const resolveInstalledSkillName = (skillName?: string): string => {
+  const normalized = skillName?.trim();
+  if (!normalized) {
+    return SKILL_NAME;
+  }
+  if (
+    normalized === '.' ||
+    normalized === '..' ||
+    !SKILL_NAME_PATTERN.test(normalized)
+  ) {
+    throw new Error(
+      'Invalid skill name. Use letters, numbers, dots, underscores, or hyphens only.'
+    );
+  }
+  return normalized;
+};
+
+export const resolveTargetSkillPath = ({
+  home,
+  skillName,
+  target,
+}: {
+  home: string;
+  skillName: string;
+  target: SkillInstallTarget;
+}): string => {
+  switch (target) {
+    case 'claude':
+      return path.join(home, '.claude', 'skills', skillName);
+    case 'codex':
+      return path.join(home, '.codex', 'skills', skillName);
+    case 'openclaw':
+      return path.join(home, '.openclaw', 'skills', skillName);
+  }
+};
+
+const resolveTargetLabel = (target: SkillInstallTarget): string => SKILL_TARGET_LABELS[target];
+
 export const inferSkillReleaseChannel = (tagOrVersion: string): SkillReleaseChannel =>
   tagOrVersion.includes('-beta.') ? 'beta' : 'stable';
 
@@ -68,24 +115,28 @@ export const resolveSkillReleaseTag = ({
  * Install the composio-cli skill into the user's global agent skills directory.
  *
  * - Downloads composio-skill.zip from the matching CLI GitHub release
- * - Extracts to ~/.agents/skills/composio-cli/
- * - Creates a symlink at ~/.claude/skills/composio-cli → ../../.agents/skills/composio-cli
+ * - Extracts to ~/.agents/skills/<skill-name>/
+ * - Creates a symlink in the selected agent's skills directory
  *
  * Non-fatal: wrapped version catches all errors.
  */
 export const installSkill = (options?: {
   readonly releaseTag?: string;
   readonly channel?: SkillReleaseChannel;
+  readonly target?: SkillInstallTarget;
+  readonly skillName?: string;
 }) =>
   Effect.gen(function* () {
     const os = yield* NodeOs;
     const ui = yield* TerminalUI;
     const httpClient = yield* HttpClient.HttpClient;
     const githubConfig = yield* Config.all(GITHUB_CONFIG);
     const home = os.homedir;
+    const target = options?.target ?? 'claude';
+    const skillName = resolveInstalledSkillName(options?.skillName);
 
-    const agentSkillDir = path.join(home, '.agents', 'skills', SKILL_NAME);
-    const claudeSkillLink = path.join(home, '.claude', 'skills', SKILL_NAME);
+    const agentSkillDir = path.join(home, '.agents', 'skills', skillName);
+    const targetSkillPath = resolveTargetSkillPath({ home, skillName, target });
 
     const tag = yield* resolveSkillReleaseTag({
       channel: options?.channel,
@@ -161,25 +212,25 @@ export const installSkill = (options?: {
       fs.rmSync(tmpDir, { recursive: true, force: true });
     }
 
-    // Create symlink for Claude Code — always replace any existing entry
-    fs.mkdirSync(path.join(home, '.claude', 'skills'), { recursive: true });
+    // Create agent-specific symlink — always replace any existing entry.
+    fs.mkdirSync(path.dirname(targetSkillPath), { recursive: true });
     try {
-      const stat = fs.lstatSync(claudeSkillLink);
+      const stat = fs.lstatSync(targetSkillPath);
       // Entry exists (symlink, broken symlink, or directory) — remove it
       if (stat.isSymbolicLink()) {
-        fs.unlinkSync(claudeSkillLink);
+        fs.unlinkSync(targetSkillPath);
       } else if (stat.isDirectory()) {
-        fs.rmSync(claudeSkillLink, { recursive: true, force: true });
+        fs.rmSync(targetSkillPath, { recursive: true, force: true });
       } else {
-        fs.unlinkSync(claudeSkillLink);
+        fs.unlinkSync(targetSkillPath);
       }
     } catch {
       // lstatSync throws if nothing exists at the path — that's fine
     }
-    const relativeTarget = path.relative(path.dirname(claudeSkillLink), agentSkillDir);
-    fs.symlinkSync(relativeTarget, claudeSkillLink);
+    const relativeTarget = path.relative(path.dirname(targetSkillPath), agentSkillDir);
+    fs.symlinkSync(relativeTarget, targetSkillPath);
 
-    yield* ui.log.success('Installed composio-cli skill for Claude Code');
+    yield* ui.log.success(`Installed ${skillName} skill for ${resolveTargetLabel(target)}`);
   });
 
 /**
@@ -188,14 +239,17 @@ export const installSkill = (options?: {
 export const installSkillSafe = (options?: {
   readonly releaseTag?: string;
   readonly channel?: SkillReleaseChannel;
+  readonly target?: SkillInstallTarget;
+  readonly skillName?: string;
 }) =>
   installSkill(options).pipe(
     Effect.sandbox,
     Effect.catchAll(cause =>
       Effect.gen(function* () {
         const ui = yield* TerminalUI;
         yield* Effect.logDebug('Skill install failed:', cause);
-        yield* ui.log.warn('Could not install Claude Code skill (non-fatal)');
+        const targetLabel = resolveTargetLabel(options?.target ?? 'claude');
+        yield* ui.log.warn(`Could not install ${targetLabel} skill (non-fatal)`);
       })
     )
   );

ts/packages/cli/test/src/commands/install-skill-root-flag.test.ts

@@ -0,0 +1,73 @@
+import { describe, expect, it } from '@effect/vitest';
+import { parseRootInstallSkillRequest } from 'src/commands';
+
+describe('CLI: --instal-skill', () => {
+  it('parses the default skill name when only a target is provided', () => {
+    expect(parseRootInstallSkillRequest(['node', 'composio', '--instal-skill', 'claude'])).toEqual({
+      _tag: 'parsed',
+      target: 'claude',
+    });
+  });
+
+  it('parses an explicit skill name and target', () => {
+    expect(
+      parseRootInstallSkillRequest([
+        'node',
+        'composio',
+        '--instal-skill',
+        'composio-cli',
+        'codex',
+      ])
+    ).toEqual({
+      _tag: 'parsed',
+      skillName: 'composio-cli',
+      target: 'codex',
+    });
+  });
+
+  it('accepts the --install-skill alias', () => {
+    expect(parseRootInstallSkillRequest(['node', 'composio', '--install-skill', 'openclaw'])).toEqual(
+      {
+        _tag: 'parsed',
+        target: 'openclaw',
+      }
+    );
+  });
+
+  it('accepts the root flag after leading global options', () => {
+    expect(
+      parseRootInstallSkillRequest([
+        'node',
+        'composio',
+        '--log-level',
+        'debug',
+        '--instal-skill',
+        'claude',
+      ])
+    ).toEqual({
+      _tag: 'parsed',
+      target: 'claude',
+    });
+  });
+
+  it('does not intercept subcommand flags after a positional command', () => {
+    expect(
+      parseRootInstallSkillRequest(['node', 'composio', 'upgrade', '--install-skill', 'claude'])
+    ).toBeUndefined();
+  });
+
+  it('returns a helpful error when the target is missing', () => {
+    expect(parseRootInstallSkillRequest(['node', 'composio', '--instal-skill'])).toEqual({
+      _tag: 'error',
+      message:
+        'Missing target for --instal-skill. Usage: composio --instal-skill [skill-name] <claude|codex|openclaw>',
+    });
+  });
+
+  it('returns a helpful error for invalid targets', () => {
+    expect(parseRootInstallSkillRequest(['node', 'composio', '--instal-skill', 'cursor'])).toEqual({
+      _tag: 'error',
+      message: 'Invalid target for --instal-skill. Expected one of: claude, codex, openclaw.',
+    });
+  });
+});