Skip to content

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

Add JSON output for skills list (#2658)

TT7cacc9460a77
diff --git a/.changeset/skills-list-json.md b/.changeset/skills-list-json.md
new file mode 100644
index 00000000..ba78f904
--- /dev/null
+++ b/.changeset/skills-list-json.md
@@ -0,0 +1,5 @@
+---
+"ctx7": patch
+---
+
+Add `--json` flag to `ctx7 skills list` for machine-parseable output. Emits `{ skills: [{ name, path, source }] }` where `path` is absolute and `source` is the agent type (`universal`, `claude`, `cursor`, `antigravity`). Matches the existing `--json` pattern on `ctx7 library` and `ctx7 docs`.
diff --git a/packages/cli/src/__tests__/skill-list.test.ts b/packages/cli/src/__tests__/skill-list.test.ts
new file mode 100644
index 00000000..c622141a
--- /dev/null
+++ b/packages/cli/src/__tests__/skill-list.test.ts
@@ -0,0 +1,75 @@
+import { afterEach, beforeEach, describe, expect, test, vi } from "vitest";
+import { Command } from "commander";
+import { mkdir, rm, realpath } from "fs/promises";
+import { join } from "path";
+import { tmpdir } from "os";
+
+const trackEvent = vi.fn();
+let logOutput: string[];
+
+vi.mock("../utils/tracking.js", () => ({
+ trackEvent: (...args: unknown[]) => trackEvent(...args),
+}));
+
+import { registerSkillCommands } from "../commands/skill.js";
+
+let tempDir: string;
+let originalCwd: string;
+
+async function runCommand(...args: string[]): Promise<void> {
+ const program = new Command();
+ program.exitOverride();
+ registerSkillCommands(program);
+ await program.parseAsync(["node", "test", ...args]);
+}
+
+beforeEach(async () => {
+ vi.clearAllMocks();
+ logOutput = [];
+ vi.spyOn(console, "log").mockImplementation((...args: unknown[]) => {
+ logOutput.push(args.join(" "));
+ });
+ vi.spyOn(console, "error").mockImplementation(() => {});
+ originalCwd = process.cwd();
+ const rawTempDir = join(tmpdir(), `ctx7-skills-list-${Date.now()}`);
+ await mkdir(rawTempDir, { recursive: true });
+ tempDir = await realpath(rawTempDir);
+ process.chdir(tempDir);
+});
+
+afterEach(async () => {
+ process.chdir(originalCwd);
+ await rm(tempDir, { recursive: true, force: true });
+ vi.restoreAllMocks();
+});
+
+describe("skills list command", () => {
+ test("outputs installed skills as JSON", async () => {
+ await mkdir(join(tempDir, ".agents", "skills", "find-docs"), { recursive: true });
+ await mkdir(join(tempDir, ".cursor", "skills", "cursor-helper"), { recursive: true });
+
+ await runCommand("skills", "list", "--json");
+
+ expect(JSON.parse(logOutput.join("\n"))).toEqual({
+ skills: [
+ {
+ name: "find-docs",
+ path: join(tempDir, ".agents", "skills", "find-docs"),
+ source: "universal",
+ },
+ {
+ name: "cursor-helper",
+ path: join(tempDir, ".cursor", "skills", "cursor-helper"),
+ source: "cursor",
+ },
+ ],
+ });
+ expect(trackEvent).toHaveBeenCalledWith("command", { name: "list" });
+ });
+
+ test("outputs an empty JSON list when no skills are installed", async () => {
+ await runCommand("skills", "list", "--json");
+
+ expect(JSON.parse(logOutput.join("\n"))).toEqual({ skills: [] });
+ });
+});
diff --git a/packages/cli/src/commands/skill.ts b/packages/cli/src/commands/skill.ts
index 77b5b483..756089f9 100644
--- a/packages/cli/src/commands/skill.ts
+++ b/packages/cli/src/commands/skill.ts
@@ -124,6 +124,7 @@ export function registerSkillCommands(program: Command): void {
skill
.command("list")
.alias("ls")
+ .option("--json", "Output as JSON")
.option("--global", "List global skills")
.option("--claude", "Claude Code (.claude/skills/)")
.option("--cursor", "Cursor (.cursor/skills/)")
@@ -639,7 +640,13 @@ async function listCommand(options: ListOptions): Promise<void> {
const scope: Scope = options.global ? "global" : "project";
const baseDir = scope === "global" ? homedir() : process.cwd();
- const results: { label: string; path: string; skills: string[] }[] = [];
+ const results: {
+ label: string;
+ displayPath: string;
+ dir: string;
+ source: string;
+ skills: string[];
+ }[] = [];
// Helper to scan a skills directory
async function scanDir(dir: string): Promise<string[]> {
@@ -662,7 +669,7 @@ async function listCommand(options: ListOptions): Promise<void> {
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 });
+ results.push({ label, displayPath: dir, dir, source: ide, skills });
}
}
} else {
@@ -671,7 +678,13 @@ async function listCommand(options: ListOptions): Promise<void> {
const universalDir = join(baseDir, universalPath);
const universalSkills = await scanDir(universalDir);
if (universalSkills.length > 0) {
- results.push({ label: UNIVERSAL_AGENTS_LABEL, path: universalPath, skills: universalSkills });
+ results.push({
+ label: UNIVERSAL_AGENTS_LABEL,
+ displayPath: universalPath,
+ dir: universalDir,
+ source: "universal",
+ skills: universalSkills,
+ });
}
for (const ide of VENDOR_SPECIFIC_AGENTS) {
@@ -679,11 +692,30 @@ async function listCommand(options: ListOptions): Promise<void> {
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 });
+ results.push({
+ label: IDE_NAMES[ide],
+ displayPath: pathMap[ide],
+ dir,
+ source: ide,
+ skills,
+ });
}
}
}
+ if (options.json) {
+ const skills = results.flatMap((result) =>
+ result.skills.map((name) => ({
+ name,
+ path: join(result.dir, name),
+ source: result.source,
+ }))
+ );
+
+ console.log(JSON.stringify({ skills }, null, 2));
+ return;
+ }
+
if (results.length === 0) {
log.warn("No skills installed");
return;
@@ -691,8 +723,8 @@ async function listCommand(options: ListOptions): Promise<void> {
log.blank();
- for (const { label, path, skills } of results) {
- log.plain(`${pc.bold(label)} ${pc.dim(path)}`);
+ for (const { label, displayPath, skills } of results) {
+ log.plain(`${pc.bold(label)} ${pc.dim(displayPath)}`);
for (const skill of skills) {
log.plain(` ${pc.green(skill)}`);
}
diff --git a/packages/cli/src/types.ts b/packages/cli/src/types.ts
index 5cd1d48d..5ed08307 100644
--- a/packages/cli/src/types.ts
+++ b/packages/cli/src/types.ts
@@ -142,7 +142,7 @@ export interface ScopeOptions {
export type AddOptions = IDEOptions & ScopeOptions & { all?: boolean; yes?: boolean };
export type SuggestOptions = IDEOptions & ScopeOptions;
-export type ListOptions = IDEOptions & ScopeOptions;
+export type ListOptions = IDEOptions & ScopeOptions & { json?: boolean };
export type RemoveOptions = IDEOptions & ScopeOptions;
export type GenerateOptions = IDEOptions &
ScopeOptions & {