Skip to content

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

feat(cli): enumerate popularity and trust in skill search results (#2192)

Fahreddin Özcan62dc278b7672
diff --git a/.changeset/crisp-dots-bake.md b/.changeset/crisp-dots-bake.md
new file mode 100644
index 00000000..34d935b8
--- /dev/null
+++ b/.changeset/crisp-dots-bake.md
@@ -0,0 +1,7 @@
+---
+"ctx7": patch
+---
+
+- feat(cli): enumerate popularity with a 4-star scale in skill search, install, and suggest results
+- feat(cli): show install count range and trust score in skill hover details
+- fix(cli): rename "docs" skill to "find-docs" in setup output and prompts
diff --git a/packages/cli/src/commands/setup.ts b/packages/cli/src/commands/setup.ts
index 5ca470bd..be70da2e 100644
--- a/packages/cli/src/commands/setup.ts
+++ b/packages/cli/src/commands/setup.ts
@@ -138,12 +138,12 @@ async function resolveMode(options: SetupOptions): Promise<SetupMode> {
message: "How should your agent access Context7?",
choices: [
{
- name: `MCP server\n ${pc.dim("Agent calls Context7 tools via MCP protocol to retrieve up-to-date library docs")}`,
- value: "mcp" as SetupMode,
+ name: `CLI + Skills\n ${pc.dim("Installs a find-docs skill that guides your agent to fetch up-to-date library docs using ")}${pc.dim(pc.bold("ctx7"))}${pc.dim(" CLI commands")}`,
+ value: "cli" as SetupMode,
},
{
- name: `CLI + Skills\n ${pc.dim("Installs a docs skill that guides your agent to fetch up-to-date library docs using ")}${pc.dim(pc.bold("ctx7"))}${pc.dim(" CLI commands")}`,
- value: "cli" as SetupMode,
+ name: `MCP server\n ${pc.dim("Agent calls Context7 tools via MCP protocol to retrieve up-to-date library docs")}`,
+ value: "mcp" as SetupMode,
},
],
theme: {
@@ -204,7 +204,9 @@ async function promptAgents(scope: Scope, mode: SetupMode): Promise<SetupAgent[]
}
const message =
- mode === "cli" ? "Install docs skill for which agents?" : "Which agents do you want to set up?";
+ mode === "cli"
+ ? "Install find-docs skill for which agents?"
+ : "Which agents do you want to set up?";
try {
return await checkboxWithHover(
@@ -376,7 +378,7 @@ async function setupCli(options: SetupOptions): Promise<void> {
}
log.blank();
- const spinner = ora("Downloading docs skill...").start();
+ const spinner = ora("Downloading find-docs skill...").start();
const downloadData = await downloadSkill("/upstash/context7", "find-docs");
if (downloadData.error || downloadData.files.length === 0) {
@@ -401,7 +403,7 @@ async function setupCli(options: SetupOptions): Promise<void> {
log.blank();
for (const dir of targetDirs) {
log.itemAdd(
- `docs ${pc.dim("Guides your agent to fetch up-to-date library docs on demand using ctx7 CLI commands")}`
+ `find-docs ${pc.dim("Guides your agent to fetch up-to-date library docs on demand using ctx7 CLI commands")}`
);
log.plain(` ${pc.dim(dir)}`);
}
diff --git a/packages/cli/src/commands/skill.ts b/packages/cli/src/commands/skill.ts
index d6cbdba2..bd1c09f4 100644
--- a/packages/cli/src/commands/skill.ts
+++ b/packages/cli/src/commands/skill.ts
@@ -24,8 +24,10 @@ import {
import {
checkboxWithHover,
terminalLink,
- formatInstallCount,
- formatTrustScore,
+ formatPopularity,
+ formatTrust,
+ formatInstallRange,
+ getTrustLabel,
} from "../utils/prompts.js";
import { installSkillFiles, symlinkSkill } from "../utils/installer.js";
import { trackEvent } from "../utils/tracking.js";
@@ -279,15 +281,12 @@ 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 popularityColWidth = 13;
const choices = skillsWithRepo.map((s, index) => {
const indexStr = pc.dim(`${(index + 1).toString().padStart(indexWidth)}.`);
const paddedName = s.name.padEnd(maxNameLen);
- const installsRaw = s.installCount ? String(s.installCount) : "-";
- const paddedInstalls =
- formatInstallCount(s.installCount, pc.dim("-")) +
- " ".repeat(installsColWidth - installsRaw.length);
- const trust = formatTrustScore(s.trustScore);
+ const popularity = formatPopularity(s.installCount) + " ".repeat(popularityColWidth - 4);
+ const trust = formatTrust(s.trustScore);
const skillUrl = `https://context7.com/skills${s.project}/${s.name}`;
const skillLink = terminalLink(s.name, skillUrl, pc.white);
@@ -297,12 +296,14 @@ async function installCommand(
"",
`${pc.yellow("Skill:")} ${skillLink}`,
`${pc.yellow("Repo:")} ${repoLink}`,
+ `${pc.yellow("Installs:")} ${pc.white(formatInstallRange(s.installCount))}`,
+ `${pc.yellow("Trust:")} ${s.trustScore !== undefined && s.trustScore >= 0 ? pc.white(s.trustScore.toFixed(1)) : pc.dim("-")}`,
`${pc.yellow("Description:")}`,
pc.white(s.description || "No description"),
];
return {
- name: `${indexStr} ${paddedName} ${paddedInstalls}${trust}`,
+ name: `${indexStr} ${paddedName} ${popularity}${trust}`,
value: s,
description: metadataLines.join("\n"),
};
@@ -313,7 +314,7 @@ async function installCommand(
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)");
+ headerPad + pc.dim("Popularity".padEnd(popularityColWidth)) + pc.dim("Trust");
try {
selectedSkills = await checkboxWithHover({
@@ -456,16 +457,13 @@ async function searchCommand(query: string): Promise<void> {
const nameWithRepo = (s: SkillSearchResult) => `${s.name} ${pc.dim(`(${s.project})`)}`;
const nameWithRepoLen = (s: SkillSearchResult) => `${s.name} (${s.project})`.length;
const maxNameLen = Math.max(...data.results.map(nameWithRepoLen));
- const installsColWidth = 10;
+ const popularityColWidth = 13;
const choices = data.results.map((s, index) => {
const indexStr = pc.dim(`${(index + 1).toString().padStart(indexWidth)}.`);
const rawLen = nameWithRepoLen(s);
const displayName = nameWithRepo(s) + " ".repeat(maxNameLen - rawLen);
- const installsRaw = s.installCount ? String(s.installCount) : "-";
- const paddedInstalls =
- formatInstallCount(s.installCount, pc.dim("-")) +
- " ".repeat(installsColWidth - installsRaw.length);
- const trust = formatTrustScore(s.trustScore);
+ const popularity = formatPopularity(s.installCount) + " ".repeat(popularityColWidth - 4);
+ const trust = formatTrust(s.trustScore);
const skillLink = terminalLink(
s.name,
@@ -478,12 +476,14 @@ async function searchCommand(query: string): Promise<void> {
"",
`${pc.yellow("Skill:")} ${skillLink}`,
`${pc.yellow("Repo:")} ${repoLink}`,
+ `${pc.yellow("Installs:")} ${pc.white(formatInstallRange(s.installCount))}`,
+ `${pc.yellow("Trust:")} ${s.trustScore !== undefined && s.trustScore >= 0 ? pc.white(s.trustScore.toFixed(1)) : pc.dim("-")}`,
`${pc.yellow("Description:")}`,
pc.white(s.description || "No description"),
];
return {
- name: `${indexStr} ${displayName} ${paddedInstalls}${trust}`,
+ name: `${indexStr} ${displayName} ${popularity}${trust}`,
value: s,
description: metadataLines.join("\n"),
};
@@ -491,8 +491,7 @@ async function searchCommand(query: string): Promise<void> {
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 headerLine = headerPad + pc.dim("Popularity".padEnd(popularityColWidth)) + pc.dim("Trust");
let selectedSkills: SkillSearchResult[];
try {
@@ -790,8 +789,8 @@ async function suggestCommand(options: SuggestOptions): Promise<void> {
const nameWithRepo = (s: SkillSearchResult) => `${s.name} ${pc.dim(`(${s.project})`)}`;
const nameWithRepoLen = (s: SkillSearchResult) => `${s.name} (${s.project})`.length;
const maxNameLen = Math.max(...skills.map(nameWithRepoLen));
- const installsColWidth = 10;
- const trustColWidth = 12;
+ const popularityColWidth = 13;
+ const trustColWidth = 8;
const maxMatchedLen = Math.max(...skills.map((s) => s.matchedDep.length));
const indexWidth = skills.length.toString().length;
@@ -799,13 +798,9 @@ async function suggestCommand(options: SuggestOptions): Promise<void> {
const indexStr = pc.dim(`${(index + 1).toString().padStart(indexWidth)}.`);
const rawLen = nameWithRepoLen(s);
const displayName = nameWithRepo(s) + " ".repeat(maxNameLen - rawLen);
- const installsRaw = s.installCount ? String(s.installCount) : "-";
- const paddedInstalls =
- formatInstallCount(s.installCount, pc.dim("-")) +
- " ".repeat(installsColWidth - installsRaw.length);
- const trustRaw =
- s.trustScore !== undefined && s.trustScore >= 0 ? s.trustScore.toFixed(1) : "-";
- const trust = formatTrustScore(s.trustScore) + " ".repeat(trustColWidth - trustRaw.length);
+ const popularity = formatPopularity(s.installCount) + " ".repeat(popularityColWidth - 4);
+ const trustLabel = getTrustLabel(s.trustScore);
+ const trust = formatTrust(s.trustScore) + " ".repeat(trustColWidth - trustLabel.length);
const matched = pc.yellow(s.matchedDep.padEnd(maxMatchedLen));
const skillLink = terminalLink(
@@ -819,13 +814,15 @@ async function suggestCommand(options: SuggestOptions): Promise<void> {
"",
`${pc.yellow("Skill:")} ${skillLink}`,
`${pc.yellow("Repo:")} ${repoLink}`,
+ `${pc.yellow("Installs:")} ${pc.white(formatInstallRange(s.installCount))}`,
+ `${pc.yellow("Trust:")} ${s.trustScore !== undefined && s.trustScore >= 0 ? pc.white(s.trustScore.toFixed(1)) : pc.dim("-")}`,
`${pc.yellow("Relevant:")} ${pc.white(s.matchedDep)}`,
`${pc.yellow("Description:")}`,
pc.white(s.description || "No description"),
];
return {
- name: `${indexStr} ${displayName} ${paddedInstalls}${trust}${matched}`,
+ name: `${indexStr} ${displayName} ${popularity}${trust}${matched}`,
value: s,
description: metadataLines.join("\n"),
};
@@ -835,8 +832,8 @@ async function suggestCommand(options: SuggestOptions): Promise<void> {
const headerPad = " ".repeat(checkboxPrefixWidth + indexWidth + 1 + 1 + maxNameLen + 1);
const headerLine =
headerPad +
- pc.dim("Installs".padEnd(installsColWidth)) +
- pc.dim("Trust(0-10)".padEnd(trustColWidth)) +
+ pc.dim("Popularity".padEnd(popularityColWidth)) +
+ pc.dim("Trust".padEnd(trustColWidth)) +
pc.dim("Relevant");
let selectedSkills: SkillSearchResult[];
diff --git a/packages/cli/src/utils/prompts.ts b/packages/cli/src/utils/prompts.ts
index 80b8395f..11e75b6d 100644
--- a/packages/cli/src/utils/prompts.ts
+++ b/packages/cli/src/utils/prompts.ts
@@ -14,19 +14,56 @@ export function terminalLink(text: string, url: string, color?: (s: string) => s
}
/**
- * Formats install count for display.
+ * Formats install count into a popularity star rating (4 stars).
+ * 0/unknown → ☆☆☆☆, <100 → ★☆☆☆, <500 → ★★☆☆, <1000 → ★★★☆, 1000+ → ★★★★
*/
-export function formatInstallCount(count: number | undefined, placeholder = ""): string {
- if (count === undefined || count === 0) return placeholder;
+export function formatPopularity(count: number | undefined): string {
+ const filled = "★";
+ const empty = "☆";
+ const max = 4;
+ let stars: number;
+ if (count === undefined || count === 0) stars = 0;
+ else if (count < 100) stars = 1;
+ else if (count < 500) stars = 2;
+ else if (count < 1000) stars = 3;
+ else stars = 4;
- return pc.yellow(String(count));
+ const filledPart = filled.repeat(stars);
+ const emptyPart = empty.repeat(max - stars);
+ if (stars === 0) return pc.dim(emptyPart);
+ return pc.yellow(filledPart) + pc.dim(emptyPart);
}
-export function formatTrustScore(score: number | undefined): string {
+/**
+ * Returns the install count as a human-readable range string.
+ */
+export function formatInstallRange(count: number | undefined): string {
+ if (count === undefined || count === 0) return "Unknown";
+ if (count < 100) return "<100";
+ if (count < 500) return "<500";
+ if (count < 1000) return "<1,000";
+ return "1,000+";
+}
+
+/**
+ * Formats trust score as High / Medium / Low label.
+ * Uses MCP reputation thresholds: >=7 High, >=4 Medium, <4 Low.
+ */
+export function formatTrust(score: number | undefined): string {
if (score === undefined || score < 0) return pc.dim("-");
+ if (score >= 7) return pc.green("High");
+ if (score >= 4) return pc.yellow("Medium");
+ return pc.red("Low");
+}
- if (score < 3) return pc.red(score.toFixed(1));
- return pc.yellow(score.toFixed(1));
+/**
+ * Returns the raw trust label string (uncolored) for width calculations.
+ */
+export function getTrustLabel(score: number | undefined): string {
+ if (score === undefined || score < 0) return "-";
+ if (score >= 7) return "High";
+ if (score >= 4) return "Medium";
+ return "Low";
}
export interface CheckboxWithHoverOptions<T> {
/** Function to extract display name from value. Defaults to (v) => v.name */