Skip to content

Composio powers 1000+ toolkits, tool search, context management, authentication, and a sandboxed workbench to help you build AI agents that turn intent into action.

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

Rahul Tarak5c27c0050a02
diff --git a/ts/packages/cli/README.md b/ts/packages/cli/README.md
index f22a1d499..e37aacd61 100644
--- a/ts/packages/cli/README.md
+++ b/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
diff --git a/ts/packages/cli/src/commands/index.ts b/ts/packages/cli/src/commands/index.ts
index 08b7a89c9..1f0093f9d 100644
--- a/ts/packages/cli/src/commands/index.ts
+++ b/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);
}
diff --git a/ts/packages/cli/src/commands/root-help.ts b/ts/packages/cli/src/commands/root-help.ts
index e7ad64c59..2cd85267d 100644
--- a/ts/packages/cli/src/commands/root-help.ts
+++ b/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.`,
diff --git a/ts/packages/cli/src/effects/install-skill.ts b/ts/packages/cli/src/effects/install-skill.ts
index c5be37b40..3bf59e1b4 100644
--- a/ts/packages/cli/src/effects/install-skill.ts
+++ b/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,14 +115,16 @@ 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;
@@ -83,9 +132,11 @@ export const installSkill = (options?: {
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,6 +239,8 @@ 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,
@@ -195,7 +248,8 @@ export const installSkillSafe = (options?: {
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)`);
})
)
);
diff --git a/ts/packages/cli/test/src/commands/install-skill-root-flag.test.ts b/ts/packages/cli/test/src/commands/install-skill-root-flag.test.ts
new file mode 100644
index 000000000..257f672bf
--- /dev/null
+++ b/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.',
+ });
+ });
+});
diff --git a/ts/packages/cli/test/src/effects/install-skill.test.ts b/ts/packages/cli/test/src/effects/install-skill.test.ts
index 0766e80d1..b804ba8e2 100644
--- a/ts/packages/cli/test/src/effects/install-skill.test.ts
+++ b/ts/packages/cli/test/src/effects/install-skill.test.ts
@@ -4,7 +4,9 @@ import { FetchHttpClient, HttpClient } from '@effect/platform';
import { withHttpServer } from 'test/__utils__/http-server';
import {
inferSkillReleaseChannel,
+ resolveInstalledSkillName,
resolveSkillReleaseTag,
+ resolveTargetSkillPath,
type SkillReleaseChannel,
} from 'src/effects/install-skill';
import { GITHUB_CONFIG } from 'src/effects/github-config';
@@ -43,6 +45,41 @@ describe('install-skill', () => {
expect(inferSkillReleaseChannel('@composio/[email protected]')).toBe('beta');
});
+ it('defaults the installed skill name to composio-cli', () => {
+ expect(resolveInstalledSkillName()).toBe('composio-cli');
+ expect(resolveInstalledSkillName(' ')).toBe('composio-cli');
+ });
+
+ it('rejects unsafe installed skill names', () => {
+ expect(() => resolveInstalledSkillName('../bad')).toThrow(/Invalid skill name/);
+ expect(() => resolveInstalledSkillName('.')).toThrow(/Invalid skill name/);
+ expect(() => resolveInstalledSkillName('..')).toThrow(/Invalid skill name/);
+ });
+
+ it('resolves the agent-specific skill path', () => {
+ expect(
+ resolveTargetSkillPath({
+ home: '/tmp/test-home',
+ skillName: 'composio-cli',
+ target: 'claude',
+ })
+ ).toBe('/tmp/test-home/.claude/skills/composio-cli');
+ expect(
+ resolveTargetSkillPath({
+ home: '/tmp/test-home',
+ skillName: 'composio-cli',
+ target: 'codex',
+ })
+ ).toBe('/tmp/test-home/.codex/skills/composio-cli');
+ expect(
+ resolveTargetSkillPath({
+ home: '/tmp/test-home',
+ skillName: 'composio-cli',
+ target: 'openclaw',
+ })
+ ).toBe('/tmp/test-home/.openclaw/skills/composio-cli');
+ });
+
it('resolves the latest stable release when the stable channel is requested', async () => {
vi.stubGlobal('Bun', { which: vi.fn(() => null) });