Skip to content

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

feat: improve skill selection UX with metadata panel and install counts (#1563)

Fahreddin Özcana0bb5a57057e
diff --git a/.changeset/ten-islands-kick.md b/.changeset/ten-islands-kick.md
deleted file mode 100644
index 6d89c16e..00000000
--- a/.changeset/ten-islands-kick.md
+++ /dev/null
@@ -1,5 +0,0 @@
----
-"ctx7": patch
----
-
-Fix circular scrolling in list prompts - navigation now stops at list boundaries instead of wrapping around
diff --git a/packages/cli/CHANGELOG.md b/packages/cli/CHANGELOG.md
index 98544cf0..88d84d79 100644
--- a/packages/cli/CHANGELOG.md
+++ b/packages/cli/CHANGELOG.md
@@ -1,5 +1,16 @@
# Changelog
+## 0.1.5
+
+### Improvements
+- Improved skill selection UX with metadata panel showing Skill, Repo, and Description
+- Clickable links in metadata (Skill → context7.com, Repo → GitHub)
+- Display install counts next to skill names (e.g., `↓100+`, `↓50+`)
+- Numbered list items for easier reference
+- Select hovered item on Enter without needing to Space-select first
+- Green highlight for hovered row
+- Fix circular scrolling - navigation now stops at list boundaries
+
## 0.1.4
- Add prompt injection detection with warning messages for blocked skills
diff --git a/packages/cli/package.json b/packages/cli/package.json
index f2905f6a..e2039324 100644
--- a/packages/cli/package.json
+++ b/packages/cli/package.json
@@ -1,6 +1,6 @@
{
"name": "ctx7",
- "version": "0.1.4",
+ "version": "0.1.5",
"description": "Context7 CLI - Manage AI coding skills and documentation context",
"type": "module",
"bin": {
diff --git a/packages/cli/src/commands/skill.ts b/packages/cli/src/commands/skill.ts
index d8b1fe77..04f46111 100644
--- a/packages/cli/src/commands/skill.ts
+++ b/packages/cli/src/commands/skill.ts
@@ -1,6 +1,5 @@
import { Command } from "commander";
import pc from "picocolors";
-import { checkbox } from "@inquirer/prompts";
import ora from "ora";
import { readdir, rm } from "fs/promises";
import { join } from "path";
@@ -22,6 +21,7 @@ import {
getSelectedIdes,
hasExplicitIdeOption,
} from "../utils/ide.js";
+import { checkboxWithHover, terminalLink, formatInstallCount } from "../utils/prompts.js";
import { installSkillFiles, symlinkSkill } from "../utils/installer.js";
import type {
Skill,
@@ -226,33 +226,41 @@ async function installCommand(
if (options.all || data.skills.length === 1) {
selectedSkills = skillsWithRepo;
} else {
- const maxNameLen = Math.min(25, Math.max(...data.skills.map((s) => s.name.length)));
- const choices = skillsWithRepo.map((s) => {
+ const indexWidth = data.skills.length.toString().length;
+ const maxNameLen = Math.max(...data.skills.map((s) => s.name.length));
+ const choices = skillsWithRepo.map((s, index) => {
+ const indexStr = pc.dim(`${(index + 1).toString().padStart(indexWidth)}.`);
const paddedName = s.name.padEnd(maxNameLen);
- const desc = s.description?.trim()
- ? s.description.slice(0, 60) + (s.description.length > 60 ? "..." : "")
- : "";
+ const installs = formatInstallCount(s.installCount);
+
+ // 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);
+ const metadataLines = [
+ pc.dim("─".repeat(50)),
+ "",
+ `${pc.yellow("Skill:")} ${skillLink}`,
+ `${pc.yellow("Repo:")} ${repoLink}`,
+ `${pc.yellow("Description:")}`,
+ pc.white(s.description || "No description"),
+ ];
return {
- name: desc ? `${paddedName} ${pc.dim(desc)}` : s.name,
+ name: installs ? `${indexStr} ${paddedName} ${installs}` : `${indexStr} ${paddedName}`,
value: s,
+ description: metadataLines.join("\n"),
};
});
log.blank();
try {
- selectedSkills = await checkbox({
+ selectedSkills = await checkboxWithHover({
message: "Select skills:",
choices,
pageSize: 15,
loop: false,
- theme: {
- style: {
- renderSelectedChoices: (selected: Array<{ name?: string; value: unknown }>) =>
- selected.map((c) => (c.value as { name: string }).name).join(", "),
- },
- },
});
} catch {
log.warn("Installation cancelled");
@@ -373,17 +381,33 @@ async function searchCommand(query: string): Promise<void> {
spinner.succeed(`Found ${data.results.length} skill(s)`);
- const maxNameLen = Math.min(25, Math.max(...data.results.map((s) => s.name.length)));
- const choices = data.results.map((s) => {
+ const indexWidth = data.results.length.toString().length;
+ const maxNameLen = Math.max(...data.results.map((s) => s.name.length));
+ const choices = data.results.map((s, index) => {
+ const indexStr = pc.dim(`${(index + 1).toString().padStart(indexWidth)}.`);
const paddedName = s.name.padEnd(maxNameLen);
- const repoName = pc.dim(`(${s.project})`);
- const desc = s.description?.trim()
- ? s.description.slice(0, 50) + (s.description.length > 50 ? "..." : "")
- : "";
+ const installs = formatInstallCount(s.installCount);
+
+ // Build metadata panel shown when item is hovered
+ const skillLink = terminalLink(
+ s.name,
+ `https://context7.com/skills${s.project}/${s.name}`,
+ pc.white
+ );
+ const repoLink = terminalLink(s.project, `https://github.com${s.project}`, pc.white);
+ const metadataLines = [
+ pc.dim("─".repeat(50)),
+ "",
+ `${pc.yellow("Skill:")} ${skillLink}`,
+ `${pc.yellow("Repo:")} ${repoLink}`,
+ `${pc.yellow("Description:")}`,
+ pc.white(s.description || "No description"),
+ ];
return {
- name: desc ? `${paddedName} ${repoName} ${pc.dim(desc)}` : `${paddedName} ${repoName}`,
+ name: installs ? `${indexStr} ${paddedName} ${installs}` : `${indexStr} ${paddedName}`,
value: s,
+ description: metadataLines.join("\n"),
};
});
@@ -391,17 +415,11 @@ async function searchCommand(query: string): Promise<void> {
let selectedSkills: SkillSearchResult[];
try {
- selectedSkills = await checkbox({
+ selectedSkills = await checkboxWithHover({
message: "Select skills to install:",
choices,
pageSize: 15,
loop: false,
- theme: {
- style: {
- renderSelectedChoices: (selected: Array<{ name?: string; value: unknown }>) =>
- selected.map((c) => (c.value as SkillSearchResult).name).join(", "),
- },
- },
});
} catch {
log.warn("Installation cancelled");
diff --git a/packages/cli/src/types.ts b/packages/cli/src/types.ts
index bbfd2ccc..db91ea43 100644
--- a/packages/cli/src/types.ts
+++ b/packages/cli/src/types.ts
@@ -7,10 +7,12 @@ export interface Skill {
name: string;
description: string;
url: string;
+ installCount?: number;
}
export interface SkillSearchResult extends Skill {
project: string;
+ installCount?: number;
}
export interface ListSkillsResponse {
diff --git a/packages/cli/src/utils/ide.ts b/packages/cli/src/utils/ide.ts
index ae24a783..9d791b6f 100644
--- a/packages/cli/src/utils/ide.ts
+++ b/packages/cli/src/utils/ide.ts
@@ -140,6 +140,7 @@ export async function promptForInstallTargets(options: AddOptions): Promise<Inst
choices: ideChoices,
required: true,
loop: false,
+ theme: { style: { highlight: (text: string) => pc.green(text) } },
});
} catch {
return null;
@@ -177,6 +178,7 @@ export async function promptForSingleTarget(
choices: ideChoices,
default: DEFAULT_CONFIG.defaultIde,
loop: false,
+ theme: { style: { highlight: (text: string) => pc.green(text) } },
});
} catch {
return null;
@@ -201,6 +203,7 @@ export async function promptForSingleTarget(
],
default: DEFAULT_CONFIG.defaultScope,
loop: false,
+ theme: { style: { highlight: (text: string) => pc.green(text) } },
});
} catch {
return null;
diff --git a/packages/cli/src/utils/prompts.ts b/packages/cli/src/utils/prompts.ts
new file mode 100644
index 00000000..9ace3ac6
--- /dev/null
+++ b/packages/cli/src/utils/prompts.ts
@@ -0,0 +1,89 @@
+import pc from "picocolors";
+import { checkbox, type Separator } from "@inquirer/prompts";
+import readline from "readline";
+
+type CheckboxConfig<T> = Parameters<typeof checkbox<T>>[0];
+type CheckboxChoice<T> = Exclude<CheckboxConfig<T>["choices"][number], Separator | string>;
+
+/**
+ * Creates a clickable terminal hyperlink using OSC 8 escape sequence.
+ */
+export function terminalLink(text: string, url: string, color?: (s: string) => string): string {
+ const colorFn = color ?? ((s: string) => s);
+ return `\x1b]8;;${url}\x07${colorFn(text)}\x1b]8;;\x07`;
+}
+
+/**
+ * Formats install count with rounded display showing highest round number.
+ * Examples: 5→"5", 15→"10+", 67→"50+", 150→"100+", 350→"300+", 1500→"1k+"
+ */
+export function formatInstallCount(count: number | undefined): string {
+ if (count === undefined || count === 0) return "";
+
+ let display: string;
+ if (count >= 1000) {
+ display = `${Math.floor(count / 1000)}k+`;
+ } else if (count >= 100) {
+ const hundreds = Math.floor(count / 100) * 100;
+ display = `${hundreds}+`;
+ } else if (count >= 10) {
+ const tens = Math.floor(count / 10) * 10;
+ display = `${tens}+`;
+ } else {
+ display = String(count);
+ }
+
+ return `\x1b[38;5;214m↓${display}\x1b[0m`;
+}
+export async function checkboxWithHover<T extends { name: string }>(
+ config: CheckboxConfig<T>
+): Promise<T[]> {
+ const choices = config.choices.filter(
+ (c): c is CheckboxChoice<T> =>
+ typeof c === "object" && c !== null && !("type" in c && c.type === "separator")
+ );
+ const values = choices.map((c) => c.value);
+ const totalItems = values.length;
+ let cursorPosition = 0;
+
+ const keypressHandler = (_str: string | undefined, key: readline.Key) => {
+ if (key.name === "up" && cursorPosition > 0) {
+ cursorPosition--;
+ } else if (key.name === "down" && cursorPosition < totalItems - 1) {
+ cursorPosition++;
+ }
+ };
+
+ readline.emitKeypressEvents(process.stdin);
+ process.stdin.on("keypress", keypressHandler);
+
+ const customConfig = {
+ ...config,
+ theme: {
+ ...config.theme,
+ style: {
+ ...config.theme?.style,
+ highlight: (text: string) => pc.green(text),
+ renderSelectedChoices: (
+ selected: CheckboxChoice<T>[],
+ _allChoices: CheckboxChoice<T>[]
+ ): string => {
+ if (selected.length === 0) {
+ return pc.dim(values[cursorPosition].name);
+ }
+ return selected.map((c) => c.value.name).join(", ");
+ },
+ },
+ },
+ };
+
+ try {
+ const selected = await checkbox(customConfig);
+ if (selected.length === 0) {
+ return [values[cursorPosition]];
+ }
+ return selected;
+ } finally {
+ process.stdin.removeListener("keypress", keypressHandler);
+ }
+}