Skip to content

Context7 Platform -- Up-to-date docs for AI agents

feat(cli): adopt .agents/skills as universal install target (#1730)

Fahreddin Özcan4663c1555232
diff --git a/.changeset/purple-hats-swim.md b/.changeset/purple-hats-swim.md
new file mode 100644
index 00000000..4f9c08bc
--- /dev/null
+++ b/.changeset/purple-hats-swim.md
@@ -0,0 +1,7 @@
+---
+"ctx7": patch
+---
+
+- Adopt `.agents/skills` as universal install target, supporting multiple agents with a single installation
+- Replace `--codex`, `--opencode`, and `--amp` flags with single `--universal` flag
+- Improve checkbox UI with aligned column headers for better readability
diff --git a/.gitignore b/.gitignore
index cec4734d..285bbde0 100644
--- a/.gitignore
+++ b/.gitignore
@@ -175,6 +175,7 @@ dist
!plugins/cursor/context7/.cursor
.opencode
.claude
+.agents
# Finder (MacOS) folder config
.DS_Store
diff --git a/docs/skills.mdx b/docs/skills.mdx
index 4339ae06..fd4676d0 100644
--- a/docs/skills.mdx
+++ b/docs/skills.mdx
@@ -108,9 +108,7 @@ npx ctx7 skills install /anthropics/skills --all
```bash
npx ctx7 skills install /anthropics/skills pdf --claude
npx ctx7 skills install /anthropics/skills pdf --cursor
-npx ctx7 skills install /anthropics/skills pdf --codex
-npx ctx7 skills install /anthropics/skills pdf --opencode
-npx ctx7 skills install /anthropics/skills pdf --amp
+npx ctx7 skills install /anthropics/skills pdf --universal
npx ctx7 skills install /anthropics/skills pdf --antigravity
```
@@ -153,6 +151,7 @@ npx ctx7 skills suggest
# Suggest and install to a specific client
npx ctx7 skills suggest --claude
npx ctx7 skills suggest --cursor
+npx ctx7 skills suggest --universal
# Suggest and install globally
npx ctx7 skills suggest --global
@@ -188,6 +187,7 @@ npx ctx7 skills list
# List for a specific client
npx ctx7 skills list --claude
npx ctx7 skills list --cursor
+npx ctx7 skills list --universal
# List globally installed skills
npx ctx7 skills list --global
@@ -217,6 +217,7 @@ npx ctx7 skills remove pdf
# Remove from a specific client
npx ctx7 skills remove pdf --claude
+npx ctx7 skills remove pdf --universal
# Remove from global directory
npx ctx7 skills remove pdf --global
@@ -248,6 +249,7 @@ npx ctx7 skills generate
# Generate for a specific client
npx ctx7 skills generate --cursor
npx ctx7 skills generate --claude
+npx ctx7 skills generate --universal
# Generate as a global skill
npx ctx7 skills generate --global
@@ -271,11 +273,9 @@ The CLI automatically detects installed AI coding assistants and offers to insta
| Client | Project Directory | Global Directory |
|--------|-------------------|------------------|
+| Universal (Amp, Codex, Gemini CLI, GitHub Copilot, OpenCode + more) | `.agents/skills/` | `~/.config/agents/skills/` |
| Claude Code | `.claude/skills/` | `~/.claude/skills/` |
| Cursor | `.cursor/skills/` | `~/.cursor/skills/` |
-| Codex | `.codex/skills/` | `~/.codex/skills/` |
-| OpenCode | `.opencode/skills/` | `~/.config/opencode/skills/` |
-| Amp | `.agents/skills/` | `~/.agents/skills/` |
| Antigravity | `.agent/skills/` | `~/.agent/skills/` |
**Project vs Global:**
diff --git a/packages/cli/README.md b/packages/cli/README.md
index aab962d2..b2062190 100644
--- a/packages/cli/README.md
+++ b/packages/cli/README.md
@@ -50,6 +50,7 @@ ctx7 skills g
# Generate and install to a specific client
ctx7 skills generate --cursor
ctx7 skills generate --claude
+ctx7 skills generate --universal
# Generate globally
ctx7 skills generate --global
@@ -96,6 +97,7 @@ ctx7 skills install /anthropics/skills pdf commit
# Install to a specific client
ctx7 skills install /anthropics/skills pdf --cursor
ctx7 skills install /anthropics/skills pdf --claude
+ctx7 skills install /anthropics/skills pdf --universal
# Install globally (home directory instead of current project)
ctx7 skills install /anthropics/skills pdf --global
@@ -119,6 +121,7 @@ View skills installed in your project or globally.
ctx7 skills list
ctx7 skills list --claude
ctx7 skills list --cursor
+ctx7 skills list --universal
ctx7 skills list --global
```
@@ -137,6 +140,7 @@ Uninstall a skill from your project.
```bash
ctx7 skills remove pdf
ctx7 skills remove pdf --claude
+ctx7 skills remove pdf --universal
ctx7 skills remove pdf --global
```
@@ -146,11 +150,9 @@ The CLI automatically detects which AI coding assistants you have installed and
| Client | Skills Directory |
|--------|-----------------|
+| Universal (Amp, Codex, Gemini CLI, GitHub Copilot, OpenCode + more) | `.agents/skills/` |
| Claude Code | `.claude/skills/` |
| Cursor | `.cursor/skills/` |
-| Codex | `.codex/skills/` |
-| OpenCode | `.opencode/skills/` |
-| Amp | `.agents/skills/` |
| Antigravity | `.agent/skills/` |
## Shortcuts
diff --git a/packages/cli/src/commands/generate.ts b/packages/cli/src/commands/generate.ts
index ab0646d9..0aab3888 100644
--- a/packages/cli/src/commands/generate.ts
+++ b/packages/cli/src/commands/generate.ts
@@ -45,9 +45,7 @@ export function registerGenerateCommand(skillCommand: Command): void {
.option("--global", "Generate in global skills directory")
.option("--claude", "Claude Code (.claude/skills/)")
.option("--cursor", "Cursor (.cursor/skills/)")
- .option("--codex", "Codex (.codex/skills/)")
- .option("--opencode", "OpenCode (.opencode/skills/)")
- .option("--amp", "Amp (.agents/skills/)")
+ .option("--universal", "Universal (.agents/skills/)")
.option("--antigravity", "Antigravity (.agent/skills/)")
.description("Generate a skill for a library using AI")
.action(async (options: GenerateOptions) => {
diff --git a/packages/cli/src/commands/skill.ts b/packages/cli/src/commands/skill.ts
index 37ef81e2..d96d6281 100644
--- a/packages/cli/src/commands/skill.ts
+++ b/packages/cli/src/commands/skill.ts
@@ -38,9 +38,17 @@ import type {
RemoveOptions,
SuggestOptions,
InstallTargets,
+ Scope,
+} from "../types.js";
+import {
+ IDE_NAMES,
+ IDE_PATHS,
+ IDE_GLOBAL_PATHS,
+ UNIVERSAL_SKILLS_PATH,
+ UNIVERSAL_SKILLS_GLOBAL_PATH,
+ UNIVERSAL_AGENTS_LABEL,
+ VENDOR_SPECIFIC_AGENTS,
} from "../types.js";
-import { IDE_NAMES, IDE_PATHS, IDE_GLOBAL_PATHS } from "../types.js";
-import type { IDE, Scope } from "../types.js";
import { homedir } from "os";
import { detectProjectDependencies } from "../utils/deps.js";
import { loadTokens, isTokenExpired } from "../utils/auth.js";
@@ -51,16 +59,27 @@ function logInstallSummary(
skillNames: string[]
): void {
log.blank();
+ const hasUniversal = targets.ides.some((ide) => ide === "universal");
+ const vendorIdes = targets.ides.filter((ide) => ide !== "universal");
+
let dirIndex = 0;
- for (const ide of targets.ides) {
- for (let i = 0; i < targets.scopes.length; i++) {
- const dir = targetDirs[dirIndex++];
- log.dim(`${IDE_NAMES[ide]}: ${dir}`);
- for (const name of skillNames) {
- log.itemAdd(name);
- }
+ if (hasUniversal && dirIndex < targetDirs.length) {
+ log.plain(`${pc.bold("Universal")} ${pc.dim(targetDirs[dirIndex])}`);
+ for (const name of skillNames) {
+ log.itemAdd(name);
+ }
+ dirIndex++;
+ }
+
+ for (const ide of vendorIdes) {
+ if (dirIndex >= targetDirs.length) break;
+ log.plain(`${pc.bold(IDE_NAMES[ide])} ${pc.dim(targetDirs[dirIndex])}`);
+ for (const name of skillNames) {
+ log.itemAdd(name);
}
+ dirIndex++;
}
+
log.blank();
}
@@ -80,9 +99,7 @@ export function registerSkillCommands(program: Command): void {
.option("--global", "Install globally instead of current directory")
.option("--claude", "Claude Code (.claude/skills/)")
.option("--cursor", "Cursor (.cursor/skills/)")
- .option("--codex", "Codex (.codex/skills/)")
- .option("--opencode", "OpenCode (.opencode/skills/)")
- .option("--amp", "Amp (.agents/skills/)")
+ .option("--universal", "Universal (.agents/skills/)")
.option("--antigravity", "Antigravity (.agent/skills/)")
.description("Install skills from a repository")
.action(async (project: string, skillName: string | undefined, options: AddOptions) => {
@@ -104,9 +121,7 @@ export function registerSkillCommands(program: Command): void {
.option("--global", "List global skills")
.option("--claude", "Claude Code (.claude/skills/)")
.option("--cursor", "Cursor (.cursor/skills/)")
- .option("--codex", "Codex (.codex/skills/)")
- .option("--opencode", "OpenCode (.opencode/skills/)")
- .option("--amp", "Amp (.agents/skills/)")
+ .option("--universal", "Universal (.agents/skills/)")
.option("--antigravity", "Antigravity (.agent/skills/)")
.description("List installed skills")
.action(async (options: ListOptions) => {
@@ -121,9 +136,7 @@ export function registerSkillCommands(program: Command): void {
.option("--global", "Remove from global skills")
.option("--claude", "Claude Code (.claude/skills/)")
.option("--cursor", "Cursor (.cursor/skills/)")
- .option("--codex", "Codex (.codex/skills/)")
- .option("--opencode", "OpenCode (.opencode/skills/)")
- .option("--amp", "Amp (.agents/skills/)")
+ .option("--universal", "Universal (.agents/skills/)")
.option("--antigravity", "Antigravity (.agent/skills/)")
.description("Remove an installed skill")
.action(async (name: string, options: RemoveOptions) => {
@@ -143,9 +156,7 @@ export function registerSkillCommands(program: Command): void {
.option("--global", "Install globally instead of current directory")
.option("--claude", "Claude Code (.claude/skills/)")
.option("--cursor", "Cursor (.cursor/skills/)")
- .option("--codex", "Codex (.codex/skills/)")
- .option("--opencode", "OpenCode (.opencode/skills/)")
- .option("--amp", "Amp (.agents/skills/)")
+ .option("--universal", "Universal (.agents/skills/)")
.option("--antigravity", "Antigravity (.agent/skills/)")
.description("Suggest skills based on your project dependencies")
.action(async (options: SuggestOptions) => {
@@ -162,9 +173,7 @@ export function registerSkillAliases(program: Command): void {
.option("--global", "Install globally instead of current directory")
.option("--claude", "Claude Code (.claude/skills/)")
.option("--cursor", "Cursor (.cursor/skills/)")
- .option("--codex", "Codex (.codex/skills/)")
- .option("--opencode", "OpenCode (.opencode/skills/)")
- .option("--amp", "Amp (.agents/skills/)")
+ .option("--universal", "Universal (.agents/skills/)")
.option("--antigravity", "Antigravity (.agent/skills/)")
.description("Install skills (alias for: skills install)")
.action(async (project: string, skillName: string | undefined, options: AddOptions) => {
@@ -184,9 +193,7 @@ export function registerSkillAliases(program: Command): void {
.option("--global", "Install globally instead of current directory")
.option("--claude", "Claude Code (.claude/skills/)")
.option("--cursor", "Cursor (.cursor/skills/)")
- .option("--codex", "Codex (.codex/skills/)")
- .option("--opencode", "OpenCode (.opencode/skills/)")
- .option("--amp", "Amp (.agents/skills/)")
+ .option("--universal", "Universal (.agents/skills/)")
.option("--antigravity", "Antigravity (.agent/skills/)")
.description("Suggest skills (alias for: skills suggest)")
.action(async (options: SuggestOptions) => {
@@ -272,12 +279,16 @@ async function installCommand(
} else {
const indexWidth = data.skills.length.toString().length;
const maxNameLen = Math.max(...data.skills.map((s) => s.name.length));
+ const installsColWidth = 10;
const choices = skillsWithRepo.map((s, index) => {
const indexStr = pc.dim(`${(index + 1).toString().padStart(indexWidth)}.`);
const paddedName = s.name.padEnd(maxNameLen);
- const installs = formatInstallCount(s.installCount);
+ const installsRaw = s.installCount ? String(s.installCount) : "-";
+ const paddedInstalls =
+ formatInstallCount(s.installCount, pc.dim("-")) +
+ " ".repeat(installsColWidth - installsRaw.length);
+ const trust = formatTrustScore(s.trustScore);
- // Build metadata panel shown when item is hovered
const skillUrl = `https://context7.com/skills${s.project}/${s.name}`;
const skillLink = terminalLink(s.name, skillUrl, pc.white);
const repoLink = terminalLink(s.project, `https://github.com${s.project}`, pc.white);
@@ -291,7 +302,7 @@ async function installCommand(
];
return {
- name: installs ? `${indexStr} ${paddedName} ${installs}` : `${indexStr} ${paddedName}`,
+ name: `${indexStr} ${paddedName} ${paddedInstalls}${trust}`,
value: s,
description: metadataLines.join("\n"),
};
@@ -299,18 +310,25 @@ async function installCommand(
log.blank();
- // Align "installs" column header with the count values
- // "? " prefix = 2 chars, checkbox prefix "❯◯ " = 4 chars, index + dot + space, padded name + space
- const installsOffset = 4 + indexWidth + 1 + 1 + maxNameLen + 1 - 3;
- const message =
- "Select skills:" + " ".repeat(Math.max(1, installsOffset - 14)) + pc.dim("installs");
+ const checkboxPrefixWidth = 3;
+ const headerPad = " ".repeat(checkboxPrefixWidth + indexWidth + 1 + 1 + maxNameLen + 1);
+ const headerLine =
+ headerPad + pc.dim("Installs".padEnd(installsColWidth)) + pc.dim("Trust(0-10)");
try {
selectedSkills = await checkboxWithHover({
- message,
+ message: `Select skills to install:\n${headerLine}`,
choices,
pageSize: 15,
loop: false,
+ theme: {
+ style: {
+ message: (text: string, status: string) => {
+ if (status === "done") return pc.dim(text.split("\n")[0]);
+ return pc.bold(text);
+ },
+ },
+ },
});
} catch {
log.warn("Installation cancelled");
@@ -432,6 +450,7 @@ async function searchCommand(query: string): Promise<void> {
spinner.succeed(`Found ${data.results.length} skill(s)`);
trackEvent("search_query", { query, resultCount: data.results.length });
+ log.blank();
const indexWidth = data.results.length.toString().length;
const maxNameLen = Math.max(...data.results.map((s) => s.name.length));
@@ -467,21 +486,26 @@ async function searchCommand(query: string): Promise<void> {
};
});
- log.blank();
-
const checkboxPrefixWidth = 3; // "❯◯ " or " ◯ "
const headerPad = " ".repeat(checkboxPrefixWidth + indexWidth + 1 + 1 + maxNameLen + 1);
const headerLine =
headerPad + pc.dim("Installs".padEnd(installsColWidth)) + pc.dim("Trust(0-10)");
- const message = "Select skills to install:\n" + headerLine;
let selectedSkills: SkillSearchResult[];
try {
selectedSkills = await checkboxWithHover({
- message,
+ message: `Select skills to install:\n${headerLine}`,
choices,
pageSize: 15,
loop: false,
+ theme: {
+ style: {
+ message: (text: string, status: string) => {
+ if (status === "done") return pc.dim(text.split("\n")[0]);
+ return pc.bold(text);
+ },
+ },
+ },
});
} catch {
log.warn("Installation cancelled");
@@ -581,27 +605,50 @@ async function searchCommand(query: string): Promise<void> {
async function listCommand(options: ListOptions): Promise<void> {
trackEvent("command", { name: "list" });
const scope: Scope = options.global ? "global" : "project";
- const pathMap = scope === "global" ? IDE_GLOBAL_PATHS : IDE_PATHS;
const baseDir = scope === "global" ? homedir() : process.cwd();
- const idesToCheck: IDE[] = hasExplicitIdeOption(options)
- ? getSelectedIdes(options)
- : (Object.keys(IDE_NAMES) as IDE[]);
-
- const results: { ide: IDE; skills: string[] }[] = [];
+ const results: { label: string; path: string; skills: string[] }[] = [];
- for (const ide of idesToCheck) {
- const skillsDir = join(baseDir, pathMap[ide]);
+ // Helper to scan a skills directory
+ async function scanDir(dir: string): Promise<string[]> {
try {
- const entries = await readdir(skillsDir, { withFileTypes: true });
- const skillFolders = entries
- .filter((e) => e.isDirectory() || e.isSymbolicLink())
- .map((e) => e.name);
- if (skillFolders.length > 0) {
- results.push({ ide, skills: skillFolders });
- }
+ const entries = await readdir(dir, { withFileTypes: true });
+ return entries.filter((e) => e.isDirectory() || e.isSymbolicLink()).map((e) => e.name);
} catch {
- // Directory doesn't exist, skip
+ return [];
+ }
+ }
+
+ if (hasExplicitIdeOption(options)) {
+ // Explicit flag mode — check the specific IDE paths
+ const ides = getSelectedIdes(options);
+ for (const ide of ides) {
+ const dir =
+ ide === "universal"
+ ? join(baseDir, scope === "global" ? UNIVERSAL_SKILLS_GLOBAL_PATH : UNIVERSAL_SKILLS_PATH)
+ : join(baseDir, (scope === "global" ? IDE_GLOBAL_PATHS : IDE_PATHS)[ide]);
+ const label = ide === "universal" ? UNIVERSAL_AGENTS_LABEL : IDE_NAMES[ide];
+ const skills = await scanDir(dir);
+ if (skills.length > 0) {
+ results.push({ label, path: dir, skills });
+ }
+ }
+ } else {
+ // Default: check universal + vendor-specific
+ const universalPath = scope === "global" ? UNIVERSAL_SKILLS_GLOBAL_PATH : UNIVERSAL_SKILLS_PATH;
+ const universalDir = join(baseDir, universalPath);
+ const universalSkills = await scanDir(universalDir);
+ if (universalSkills.length > 0) {
+ results.push({ label: UNIVERSAL_AGENTS_LABEL, path: universalPath, skills: universalSkills });
+ }
+
+ for (const ide of VENDOR_SPECIFIC_AGENTS) {
+ const pathMap = scope === "global" ? IDE_GLOBAL_PATHS : IDE_PATHS;
+ const dir = join(baseDir, pathMap[ide]);
+ const skills = await scanDir(dir);
+ if (skills.length > 0) {
+ results.push({ label: IDE_NAMES[ide], path: pathMap[ide], skills });
+ }
}
}
@@ -612,10 +659,8 @@ async function listCommand(options: ListOptions): Promise<void> {
log.blank();
- for (const { ide, skills } of results) {
- const ideName = IDE_NAMES[ide];
- const path = pathMap[ide];
- log.plain(`${pc.bold(ideName)} ${pc.dim(path)}`);
+ for (const { label, path, skills } of results) {
+ log.plain(`${pc.bold(label)} ${pc.dim(path)}`);
for (const skill of skills) {
log.plain(` ${pc.green(skill)}`);
}
@@ -737,7 +782,6 @@ async function suggestCommand(options: SuggestOptions): Promise<void> {
searchSpinner.succeed(`Found ${skills.length} relevant skill(s)`);
trackEvent("suggest_results", { depCount: deps.length, skillCount: skills.length });
-
log.blank();
const maxNameLen = Math.max(...skills.map((s) => s.name.length));
@@ -781,7 +825,6 @@ async function suggestCommand(options: SuggestOptions): Promise<void> {
};
});
- // Build header
const checkboxPrefixWidth = 3; // "❯◯ " or " ◯ "
const headerPad = " ".repeat(checkboxPrefixWidth + indexWidth + 1 + 1 + maxNameLen + 1);
const headerLine =
@@ -789,15 +832,22 @@ async function suggestCommand(options: SuggestOptions): Promise<void> {
pc.dim("Installs".padEnd(installsColWidth)) +
pc.dim("Trust(0-10)".padEnd(trustColWidth)) +
pc.dim("Relevant");
- const message = "Select skills to install:\n" + headerLine;
let selectedSkills: SkillSearchResult[];
try {
selectedSkills = await checkboxWithHover({
- message,
+ message: `Select skills to install:\n${headerLine}`,
choices,
pageSize: 15,
loop: false,
+ theme: {
+ style: {
+ message: (text: string, status: string) => {
+ if (status === "done") return pc.dim(text.split("\n")[0]);
+ return pc.bold(text);
+ },
+ },
+ },
});
} catch {
log.warn("Installation cancelled");
diff --git a/packages/cli/src/types.ts b/packages/cli/src/types.ts
index 069929f7..23d08832 100644
--- a/packages/cli/src/types.ts
+++ b/packages/cli/src/types.ts
@@ -124,16 +124,14 @@ export interface ErrorEvent {
export type GenerateStreamEvent = ProgressEvent | ToolResultEvent | CompleteEvent | ErrorEvent;
-export type IDE = "claude" | "cursor" | "codex" | "opencode" | "amp" | "antigravity";
+export type IDE = "claude" | "cursor" | "antigravity" | "universal";
export type Scope = "project" | "global";
export interface IDEOptions {
claude?: boolean;
cursor?: boolean;
- codex?: boolean;
- opencode?: boolean;
- amp?: boolean;
+ universal?: boolean;
antigravity?: boolean;
}
@@ -159,37 +157,42 @@ export interface InstallTargets {
export const IDE_PATHS: Record<IDE, string> = {
claude: ".claude/skills",
cursor: ".cursor/skills",
- codex: ".codex/skills",
- opencode: ".opencode/skills",
- amp: ".agents/skills",
antigravity: ".agent/skills",
+ universal: ".agents/skills",
};
export const IDE_GLOBAL_PATHS: Record<IDE, string> = {
claude: ".claude/skills",
cursor: ".cursor/skills",
- codex: ".codex/skills",
- opencode: ".config/opencode/skills",
- amp: ".config/agents/skills",
antigravity: ".agent/skills",
+ universal: ".config/agents/skills",
};
export const IDE_NAMES: Record<IDE, string> = {
claude: "Claude Code",
cursor: "Cursor",
- codex: "Codex",
- opencode: "OpenCode",
- amp: "Amp",
antigravity: "Antigravity",
+ universal: "Universal",
};
+// Universal .agents/skills standard
+// These agents read from .agents/skills/ natively — one install covers all of them.
+export const UNIVERSAL_SKILLS_PATH = ".agents/skills";
+export const UNIVERSAL_SKILLS_GLOBAL_PATH = ".config/agents/skills";
+
+// Display label for agents that read .agents/skills/ (includes agents beyond our IDE type)
+export const UNIVERSAL_AGENTS_LABEL = "Amp, Codex, Gemini CLI, GitHub Copilot, OpenCode + more";
+
+// Agents that still require their own vendor-specific skill directory.
+export const VENDOR_SPECIFIC_AGENTS: IDE[] = ["claude", "cursor", "antigravity"];
+
export interface C7Config {
defaultIde: IDE;
defaultScope: "project" | "global";
}
export const DEFAULT_CONFIG: C7Config = {
- defaultIde: "claude",
+ defaultIde: "universal",
defaultScope: "project",
};
diff --git a/packages/cli/src/utils/ide.ts b/packages/cli/src/utils/ide.ts
index 9d791b6f..52e5c9b2 100644
--- a/packages/cli/src/utils/ide.ts
+++ b/packages/cli/src/utils/ide.ts
@@ -1,10 +1,11 @@
import pc from "picocolors";
-import { select, checkbox, confirm } from "@inquirer/prompts";
+import { select, confirm } from "@inquirer/prompts";
import { access } from "fs/promises";
-import { join } from "path";
+import { join, dirname } from "path";
import { homedir } from "os";
import { log } from "./logger.js";
+import { checkboxWithHover } from "./prompts.js";
import type {
IDE,
IDEOptions,
@@ -14,70 +15,52 @@ import type {
RemoveOptions,
InstallTargets,
} from "../types.js";
-import { IDE_PATHS, IDE_GLOBAL_PATHS, IDE_NAMES, DEFAULT_CONFIG } from "../types.js";
-import { dirname } from "path";
+import {
+ IDE_PATHS,
+ IDE_GLOBAL_PATHS,
+ IDE_NAMES,
+ UNIVERSAL_SKILLS_PATH,
+ UNIVERSAL_SKILLS_GLOBAL_PATH,
+ UNIVERSAL_AGENTS_LABEL,
+ VENDOR_SPECIFIC_AGENTS,
+ DEFAULT_CONFIG,
+} from "../types.js";
export function getSelectedIdes(options: IDEOptions): IDE[] {
const ides: IDE[] = [];
if (options.claude) ides.push("claude");
if (options.cursor) ides.push("cursor");
- if (options.codex) ides.push("codex");
- if (options.opencode) ides.push("opencode");
- if (options.amp) ides.push("amp");
+ if (options.universal) ides.push("universal");
if (options.antigravity) ides.push("antigravity");
return ides;
}
export function hasExplicitIdeOption(options: IDEOptions): boolean {
- return !!(
- options.claude ||
- options.cursor ||
- options.codex ||
- options.opencode ||
- options.amp ||
- options.antigravity
- );
-}
-
-interface DetectedIdes {
- ides: IDE[];
- scope: Scope;
+ return !!(options.claude || options.cursor || options.universal || options.antigravity);
}
-export async function detectInstalledIdes(preferredScope?: Scope): Promise<DetectedIdes | null> {
- const allIdes = Object.keys(IDE_PATHS) as IDE[];
-
- if (preferredScope === "global") {
- const globalIdes: IDE[] = [];
- for (const ide of allIdes) {
- const detectionPath = dirname(IDE_GLOBAL_PATHS[ide]);
- const globalParent = join(homedir(), detectionPath);
- try {
- await access(globalParent);
- globalIdes.push(ide);
- } catch {}
- }
- if (globalIdes.length > 0) {
- return { ides: globalIdes, scope: "global" };
- }
- return null;
- }
+/** Detect vendor-specific agents whose parent directory exists. */
+async function detectVendorSpecificAgents(scope: Scope): Promise<IDE[]> {
+ const baseDir = scope === "global" ? homedir() : process.cwd();
+ const pathMap = scope === "global" ? IDE_GLOBAL_PATHS : IDE_PATHS;
+ const detected: IDE[] = [];
- const projectIdes: IDE[] = [];
- for (const ide of allIdes) {
- const detectionPath = dirname(IDE_PATHS[ide]);
- const projectParent = join(process.cwd(), detectionPath);
+ for (const ide of VENDOR_SPECIFIC_AGENTS) {
+ const parentDir = dirname(pathMap[ide]);
try {
- await access(projectParent);
- projectIdes.push(ide);
+ await access(join(baseDir, parentDir));
+ detected.push(ide);
} catch {}
}
- if (projectIdes.length > 0) {
- return { ides: projectIdes, scope: "project" };
- }
+ return detected;
+}
- return null;
+export function getUniversalDir(scope: Scope): string {
+ if (scope === "global") {
+ return join(homedir(), UNIVERSAL_SKILLS_GLOBAL_PATH);
+ }
+ return join(process.cwd(), UNIVERSAL_SKILLS_PATH);
}
export async function promptForInstallTargets(options: AddOptions): Promise<InstallTargets | null> {
@@ -90,22 +73,40 @@ export async function promptForInstallTargets(options: AddOptions): Promise<Inst
};
}
- const preferredScope: Scope | undefined = options.global ? "global" : undefined;
- const detected = await detectInstalledIdes(preferredScope);
+ const scope: Scope = options.global ? "global" : "project";
+ const baseDir = scope === "global" ? homedir() : process.cwd();
+ const pathMap = scope === "global" ? IDE_GLOBAL_PATHS : IDE_PATHS;
+ const universalPath = scope === "global" ? UNIVERSAL_SKILLS_GLOBAL_PATH : UNIVERSAL_SKILLS_PATH;
- if (detected) {
- const scope: Scope = options.global ? "global" : detected.scope;
- const pathMap = scope === "global" ? IDE_GLOBAL_PATHS : IDE_PATHS;
- const baseDir = scope === "global" ? homedir() : process.cwd();
+ // Detect universal (.agents/) and vendor-specific agent directories
+ const detectedVendor = await detectVendorSpecificAgents(scope);
+ let hasUniversalDir = false;
+ try {
+ await access(join(baseDir, dirname(universalPath)));
+ hasUniversalDir = true;
+ } catch {}
- const paths = detected.ides.map((ide) => join(baseDir, pathMap[ide]));
- const pathList = paths.join("\n");
+ const detectedIdes: IDE[] = [
+ ...(hasUniversalDir ? (["universal"] as IDE[]) : []),
+ ...detectedVendor,
+ ];
+
+ if (detectedIdes.length > 0) {
+ // Detected — just confirm
+ const pathLines: string[] = [];
+ if (hasUniversalDir) {
+ pathLines.push(join(baseDir, universalPath));
+ }
+ for (const ide of detectedVendor) {
+ pathLines.push(join(baseDir, pathMap[ide]));
+ }
log.blank();
+
let confirmed: boolean;
try {
confirmed = await confirm({
- message: `Install to detected location(s)?\n${pc.dim(pathList)}`,
+ message: `Install to detected location(s)?\n${pc.dim(pathLines.join("\n"))}`,
default: true,
});
} catch {
@@ -117,41 +118,52 @@ export async function promptForInstallTargets(options: AddOptions): Promise<Inst
return null;
}
- return { ides: detected.ides, scopes: [scope] };
+ return { ides: detectedIdes, scopes: [scope] };
}
- // No IDE detected - prompt user to select which client(s) to install for
- log.blank();
+ // Nothing detected — show checkbox to pick
+ const universalLabel = `Universal \u2014 ${UNIVERSAL_AGENTS_LABEL} ${pc.dim(`(${universalPath})`)}`;
+ const choices: { name: string; value: IDE; checked: boolean }[] = [
+ { name: universalLabel, value: "universal", checked: true },
+ ];
- const scope: Scope = options.global ? "global" : "project";
- const pathMap = scope === "global" ? IDE_GLOBAL_PATHS : IDE_PATHS;
- const baseDir = scope === "global" ? homedir() : process.cwd();
+ for (const ide of VENDOR_SPECIFIC_AGENTS) {
+ choices.push({
+ name: `${IDE_NAMES[ide]} ${pc.dim(`(${pathMap[ide]})`)}`,
+ value: ide,
+ checked: false,
+ });
+ }
- const ideChoices = (Object.keys(IDE_NAMES) as IDE[]).map((ide) => ({
- name: `${IDE_NAMES[ide]} ${pc.dim(`(${pathMap[ide]})`)}`,
- value: ide,
- checked: ide === DEFAULT_CONFIG.defaultIde,
- }));
+ log.blank();
let selectedIdes: IDE[];
try {
- selectedIdes = await checkbox({
- message: `Which clients do you want to install the skill(s) for?\n${pc.dim(baseDir)}`,
- choices: ideChoices,
- required: true,
- loop: false,
- theme: { style: { highlight: (text: string) => pc.green(text) } },
- });
+ selectedIdes = await checkboxWithHover(
+ {
+ message: `Which agents do you want to install to?\n${pc.dim(` ${baseDir}`)}`,
+ choices,
+ loop: false,
+ theme: {
+ style: {
+ highlight: (text: string) => pc.green(text),
+ message: (text: string, status: string) => {
+ if (status === "done") return pc.dim(text.split("\n")[0]);
+ return pc.bold(text);
+ },
+ },
+ },
+ },
+ { getName: (ide: IDE) => IDE_NAMES[ide] }
+ );
} catch {
return null;
}
- if (selectedIdes.length === 0) {
- log.warn("You must select at least one client");
- return null;
- }
+ // Universal is always included
+ const ides: IDE[] = ["universal", ...selectedIdes.filter((ide) => ide !== "universal")];
- return { ides: selectedIdes, scopes: [scope] };
+ return { ides, scopes: [scope] };
}
export async function promptForSingleTarget(
@@ -166,16 +178,21 @@ export async function promptForSingleTarget(
log.blank();
- const ideChoices = (Object.keys(IDE_NAMES) as IDE[]).map((ide) => ({
- name: `${IDE_NAMES[ide]} ${pc.dim(`(${IDE_PATHS[ide]})`)}`,
- value: ide,
- }));
+ const universalLabel = `Universal ${pc.dim(`(${UNIVERSAL_SKILLS_PATH})`)}`;
+ const choices: { name: string; value: IDE }[] = [{ name: universalLabel, value: "universal" }];
+
+ for (const ide of VENDOR_SPECIFIC_AGENTS) {
+ choices.push({
+ name: `${IDE_NAMES[ide]} ${pc.dim(`(${IDE_PATHS[ide]})`)}`,
+ value: ide,
+ });
+ }
let selectedIde: IDE;
try {
selectedIde = await select({
- message: "Which client?",
- choices: ideChoices,
+ message: "Which location?",
+ choices,
default: DEFAULT_CONFIG.defaultIde,
loop: false,
theme: { style: { highlight: (text: string) => pc.green(text) } },
@@ -214,27 +231,31 @@ export async function promptForSingleTarget(
}
export function getTargetDirs(targets: InstallTargets): string[] {
- // Prioritize Claude to receive original files (others get symlinks)
- const sortedIdes = [...targets.ides].sort((a, b) => {
- if (a === "claude") return -1;
- if (b === "claude") return 1;
- return 0;
- });
-
+ const hasUniversal = targets.ides.some((ide) => ide === "universal");
const dirs: string[] = [];
- for (const ide of sortedIdes) {
- for (const scope of targets.scopes) {
- if (scope === "global") {
- dirs.push(join(homedir(), IDE_GLOBAL_PATHS[ide]));
- } else {
- dirs.push(join(process.cwd(), IDE_PATHS[ide]));
- }
+
+ for (const scope of targets.scopes) {
+ const baseDir = scope === "global" ? homedir() : process.cwd();
+
+ if (hasUniversal) {
+ const uniPath = scope === "global" ? UNIVERSAL_SKILLS_GLOBAL_PATH : UNIVERSAL_SKILLS_PATH;
+ dirs.push(join(baseDir, uniPath));
+ }
+
+ for (const ide of targets.ides) {
+ if (ide === "universal") continue;
+ const pathMap = scope === "global" ? IDE_GLOBAL_PATHS : IDE_PATHS;
+ dirs.push(join(baseDir, pathMap[ide]));
}
}
+
return dirs;
}
export function getTargetDirFromSelection(ide: IDE, scope: Scope): string {
+ if (ide === "universal") {
+ return getUniversalDir(scope);
+ }
if (scope === "global") {
return join(homedir(), IDE_GLOBAL_PATHS[ide]);
}