skilld 0.15.2 → 0.15.4

package/dist/_chunks/prompts.mjs

@@ -6,6 +6,7 @@ import { dirname, join, relative } from "pathe";
 import { existsSync, lstatSync, mkdirSync, symlinkSync, unlinkSync, writeFileSync } from "node:fs";
 import { spawnSync } from "node:child_process";
 import { isWindows } from "std-env";
+/** Common frontmatter fields from agentskills.io spec */
 const SPEC_FRONTMATTER = {
 	"name": {
 		name: "name",
@@ -41,6 +42,7 @@ const SPEC_FRONTMATTER = {
 		description: "Space-delimited pre-approved tools (experimental)"
 	}
 };
+/** Shared defaults for all agent targets */
 const BASE_DEFAULTS = {
 	skillFilename: "SKILL.md",
 	nameMatchesDir: true,
@@ -49,6 +51,7 @@ const BASE_DEFAULTS = {
 	extensions: [],
 	notes: []
 };
+/** Define an agent target with shared defaults applied */
 function defineTarget(target) {
 	return {
 		...BASE_DEFAULTS,
@@ -56,6 +59,18 @@ function defineTarget(target) {
 	};
 }
 const configHome$2 = process.env.XDG_CONFIG_HOME || join(homedir(), ".config");
+/**
+* Amp (Sourcegraph)
+*
+* Uses .agents/skills/ as primary project path. Also reads .claude/skills/.
+* Skills can bundle MCP servers via mcp.json in the skill directory.
+*
+* AGENTS.md (or AGENT.md / CLAUDE.md fallback) for general instructions,
+* supports @-mentions to reference other files and glob-based conditional includes.
+*
+* @see https://ampcode.com/news/agent-skills
+* @see https://ampcode.com/manual
+*/
 const amp = defineTarget({
 	agent: "amp",
 	displayName: "Amp",
@@ -90,6 +105,19 @@ const amp = defineTarget({
 	]
 });
 const home$6 = homedir();
+/**
+* Antigravity (Google)
+*
+* Agent-first IDE (VS Code fork) powered by Gemini. Skills live in
+* .agent/skills/ (workspace) or ~/.gemini/antigravity/skills/ (global).
+* Uses semantic matching on description to auto-invoke skills.
+*
+* Adopted the Agent Skills open standard (agentskills.io) in Jan 2026.
+* Only `name` and `description` are used for routing; body loads on demand.
+*
+* @see https://antigravity.google/docs/skills
+* @see https://codelabs.developers.google.com/getting-started-with-antigravity-skills
+*/
 const antigravity = defineTarget({
 	agent: "antigravity",
 	displayName: "Antigravity",
@@ -117,6 +145,18 @@ const antigravity = defineTarget({
 	]
 });
 const claudeHome = process.env.CLAUDE_CONFIG_DIR || join(homedir(), ".claude");
+/**
+* Claude Code (Anthropic CLI)
+*
+* Follows the Agent Skills open standard (agentskills.io) plus Claude-specific
+* extensions like `disable-model-invocation`, `user-invocable`, `context`, etc.
+*
+* Skills are discovered at startup — only `name` + `description` are read initially.
+* Full SKILL.md body loads when the agent invokes the skill (via Skill tool or auto-match).
+*
+* @see https://code.claude.com/docs/en/skills
+* @see https://agentskills.io/specification
+*/
 const claudeCode = defineTarget({
 	agent: "claude-code",
 	displayName: "Claude Code",
@@ -198,6 +238,19 @@ const claudeCode = defineTarget({
 	]
 });
 const home$5 = homedir();
+/**
+* Cline (VS Code extension)
+*
+* Has TWO systems: Rules (.clinerules/) and Skills (.cline/skills/).
+* We target Skills. Cline also reads .claude/skills/ as a fallback,
+* so emitting to .claude/skills/ covers both Claude Code and Cline.
+*
+* Only `name` and `description` are parsed from frontmatter.
+* All other fields are stripped/ignored.
+*
+* @see https://docs.cline.bot/features/skills
+* @see https://docs.cline.bot/features/cline-rules
+*/
 const cline = defineTarget({
 	agent: "cline",
 	displayName: "Cline",
@@ -228,6 +281,19 @@ const cline = defineTarget({
 	]
 });
 const codexHome = process.env.CODEX_HOME || join(homedir(), ".codex");
+/**
+* OpenAI Codex CLI
+*
+* IMPORTANT: Codex uses `.agents/skills/` for project-level skills,
+* NOT `.codex/skills/`. The `.codex/` directory is for config (config.toml).
+* `~/.codex/skills/` works only as a legacy user-global path.
+*
+* Codex also has AGENTS.md (or AGENTS.override.md) for general instructions,
+* which walks from git root to CWD concatenating found files.
+*
+* @see https://developers.openai.com/codex/skills
+* @see https://developers.openai.com/codex/guides/agents-md/
+*/
 const codex = defineTarget({
 	agent: "codex",
 	displayName: "Codex",
@@ -273,6 +339,19 @@ const codex = defineTarget({
 	]
 });
 const home$4 = homedir();
+/**
+* Cursor (AI code editor)
+*
+* Has TWO systems: Rules (.cursor/rules/*.mdc) and Skills (.cursor/skills/).
+* We target the Skills system which follows the Agent Skills spec.
+*
+* Cursor natively scans .claude/skills/ and .codex/skills/ in addition to
+* its own .cursor/skills/ — so .claude/skills/ output works for both
+* Claude Code and Cursor with zero duplication.
+*
+* @see https://cursor.com/docs/context/skills
+* @see https://cursor.com/docs/context/rules
+*/
 const cursor = defineTarget({
 	agent: "cursor",
 	displayName: "Cursor",
@@ -316,6 +395,18 @@ const cursor = defineTarget({
 	]
 });
 const home$3 = homedir();
+/**
+* Google Gemini CLI
+*
+* Follows the Agent Skills open standard (agentskills.io).
+* Skills are activated via `activate_skill` tool with user confirmation.
+*
+* Also has GEMINI.md context files (analogous to CLAUDE.md) which support
+* @file.md import syntax for modular composition.
+*
+* @see https://geminicli.com/docs/cli/skills/
+* @see https://geminicli.com/docs/cli/creating-skills/
+*/
 const geminiCli = defineTarget({
 	agent: "gemini-cli",
 	displayName: "Gemini CLI",
@@ -349,6 +440,18 @@ const geminiCli = defineTarget({
 	]
 });
 const home$2 = homedir();
+/**
+* GitHub Copilot
+*
+* Has TWO systems: Instructions (.github/instructions/*.instructions.md)
+* and Skills (.github/skills/). We target Skills.
+*
+* Copilot also auto-detects .claude/skills/ as a legacy path,
+* so .claude/skills/ output works for Claude Code, Cursor, Cline, AND Copilot.
+*
+* @see https://docs.github.com/en/copilot/concepts/agents/about-agent-skills
+* @see https://docs.github.com/copilot/customizing-copilot/adding-custom-instructions-for-github-copilot
+*/
 const githubCopilot = defineTarget({
 	agent: "github-copilot",
 	displayName: "GitHub Copilot",
@@ -387,6 +490,15 @@ const githubCopilot = defineTarget({
 	]
 });
 const configHome$1 = process.env.XDG_CONFIG_HOME || join(homedir(), ".config");
+/**
+* Goose (Block)
+*
+* Scans 6 directories for skills, including .claude/skills/ and .agents/skills/
+* for cross-agent compatibility. Later directories override earlier ones on
+* name conflict.
+*
+* @see https://block.github.io/goose/docs/guides/context-engineering/using-skills/
+*/
 const goose = defineTarget({
 	agent: "goose",
 	displayName: "Goose",
@@ -421,6 +533,18 @@ const goose = defineTarget({
 	]
 });
 const configHome = process.env.XDG_CONFIG_HOME || join(homedir(), ".config");
+/**
+* OpenCode (SST)
+*
+* Walks from CWD up to git worktree root searching for skill dirs.
+* Reads .claude/skills/ and .agents/skills/ in addition to .opencode/skills/.
+*
+* Has a rich agent system: .opencode/agents/ with per-agent model/tool configuration.
+* Skills can be permission-controlled per-agent with allow/deny/ask + glob patterns.
+*
+* @see https://opencode.ai/docs/skills/
+* @see https://opencode.ai/docs/rules/
+*/
 const opencode = defineTarget({
 	agent: "opencode",
 	displayName: "OpenCode",
@@ -462,6 +586,18 @@ const opencode = defineTarget({
 	]
 });
 const home$1 = homedir();
+/**
+* Roo Code (VS Code extension)
+*
+* IMPORTANT: Roo does NOT read .claude/skills/ or .agents/skills/.
+* It requires its own .roo/skills/ directory — no cross-compat shortcuts.
+*
+* Unique feature: mode-specific skill directories (.roo/skills-{modeSlug}/)
+* allow targeting skills to specific modes (code, architect, etc.).
+*
+* @see https://docs.roocode.com/features/skills
+* @see https://docs.roocode.com/features/custom-instructions
+*/
 const roo = defineTarget({
 	agent: "roo",
 	displayName: "Roo Code",
@@ -494,6 +630,18 @@ const roo = defineTarget({
 	]
 });
 const home = homedir();
+/**
+* Windsurf (Codeium editor)
+*
+* Has TWO systems: Rules (.windsurf/rules/*.md) and Skills (.windsurf/skills/).
+* We target Skills. Rules have a separate frontmatter schema with trigger/globs.
+*
+* Skills only document `name` and `description` as frontmatter fields.
+* Cascade uses "progressive disclosure" for supporting files.
+*
+* @see https://docs.windsurf.com/windsurf/cascade/skills
+* @see https://docs.windsurf.com/windsurf/cascade/memories
+*/
 const windsurf = defineTarget({
 	agent: "windsurf",
 	displayName: "Windsurf",
@@ -537,15 +685,28 @@ const targets = {
 	"roo": roo,
 	"antigravity": antigravity
 };
+/**
+* Detect which agents are installed on the system
+*/
 function detectInstalledAgents() {
 	return Object.entries(targets).filter(([_, config]) => config.detectInstalled()).map(([type]) => type);
 }
+/**
+* Detect the target agent (where skills are installed) from env vars and cwd.
+* This is NOT the generator LLM — it determines the skills directory.
+*
+* Priority: env vars first (running inside agent), then project dirs.
+* Iteration order of the agents record determines priority.
+*/
 function detectTargetAgent() {
 	for (const [type, target] of Object.entries(targets)) if (target.detectEnv()) return type;
 	const cwd = process.cwd();
 	for (const [type, target] of Object.entries(targets)) if (target.detectProject(cwd)) return type;
 	return null;
 }
+/**
+* Get the version of an agent's CLI (if available)
+*/
 function getAgentVersion(agentType) {
 	const agent = targets[agentType];
 	if (!agent.cli) return null;
@@ -568,14 +729,30 @@ function getAgentVersion(agentType) {
 		return null;
 	}
 }
+/**
+* Dynamic budget allocation for skill sections.
+*
+* Total SKILL.md body should stay under ~300 lines (≈5,000 words per Agent Skills guide).
+* When more sections are enabled, each gets proportionally less space.
+* When a package has many releases, API changes budget scales up to capture more churn.
+*/
+/** Scale max lines based on enabled section count. Solo sections get full budget, 4 sections ~60%. */
 function maxLines(min, max, sectionCount) {
 	const scale = budgetScale(sectionCount);
 	return Math.max(min, Math.round(max * scale));
 }
+/** Scale item count based on enabled section count. */
 function maxItems(min, max, sectionCount) {
 	const scale = budgetScale(sectionCount);
 	return Math.max(min, Math.round(max * scale));
 }
+/**
+* Boost budget for high-churn packages based on API-level release density.
+* Combines major/minor release count with current minor version as a churn signal.
+*
+* @param significantReleases - Count of major/minor releases (patch releases excluded)
+* @param minorVersion - Current minor version number (e.g., 15 for v3.15.0)
+*/
 function releaseBoost(significantReleases, minorVersion) {
 	const combined = (!significantReleases ? 0 : significantReleases <= 5 ? 0 : significantReleases <= 15 ? 1 : 2) + (!minorVersion ? 0 : minorVersion <= 3 ? 0 : minorVersion <= 10 ? 1 : 2);
 	if (combined <= 0) return 1;
@@ -588,27 +765,32 @@ function budgetScale(sectionCount) {
 	if (sectionCount === 3) return .7;
 	return .6;
 }
+/** Warns if content exceeds 150% of max lines */
 function checkLineCount(content, max) {
 	const lines = content.split("\n").length;
 	if (lines > Math.round(max * 1.5)) return [{ warning: `Output ${lines} lines exceeds ${max} max by >50%` }];
 	return [];
 }
+/** Warns if content is fewer than 3 lines */
 function checkSparseness(content) {
 	const lines = content.split("\n").length;
 	if (lines < 3) return [{ warning: `Output only ${lines} lines — likely too sparse` }];
 	return [];
 }
+/** Warns if sourced/bullets ratio is below minRatio */
 function checkSourceCoverage(content, minRatio = .8) {
 	const bullets = (content.match(/^- /gm) || []).length;
 	const sourced = (content.match(/\[source\]/g) || []).length;
 	if (bullets > 2 && sourced / bullets < minRatio) return [{ warning: `Only ${sourced}/${bullets} items have source citations (need ${Math.round(minRatio * 100)}% coverage)` }];
 	return [];
 }
+/** Warns if source links are missing .skilld/ prefix */
 function checkSourcePaths(content) {
 	const badPaths = content.match(/\[source\]\(\.\/(docs|issues|discussions|releases|pkg|guide)\//g);
 	if (badPaths?.length) return [{ warning: `${badPaths.length} source links missing .skilld/ prefix` }];
 	return [];
 }
+/** Warns if source links use absolute filesystem paths instead of relative ./.skilld/ paths */
 function checkAbsolutePaths(content) {
 	const absPaths = content.match(/\[source\]\(\/[^)]+\)/g);
 	if (absPaths?.length) return [{ warning: `${absPaths.length} source links use absolute paths — must use relative ./.skilld/ paths` }];
@@ -849,16 +1031,22 @@ Content addressing the user's instructions above, using concise examples and sou
 		rules: [`- **Custom section "${heading}":** MAX ${customMaxLines} lines, use \`## ${heading}\` heading`]
 	};
 }
+/** Output file per section (inside .skilld/) */
 const SECTION_OUTPUT_FILES = {
 	"best-practices": "_BEST_PRACTICES.md",
 	"api-changes": "_API_CHANGES.md",
 	"custom": "_CUSTOM.md"
 };
+/** Merge order for final SKILL.md body */
 const SECTION_MERGE_ORDER = [
 	"api-changes",
 	"best-practices",
 	"custom"
 ];
+/**
+* Group files by parent directory with counts
+* e.g. `/path/to/docs/api/ (15 .md files)`
+*/
 function formatDocTree(files) {
 	const dirs = /* @__PURE__ */ new Map();
 	for (const f of files) {
@@ -895,6 +1083,7 @@ Filters: \`docs:\`, \`issues:\`, \`releases:\` prefix narrows by source type.` :
 
 ${table}`;
 }
+/** Shared preamble: Security, references table, Quality Principles, doc tree */
 function buildPreamble(opts) {
 	const { packageName, skillDir, hasIssues, hasDiscussions, hasReleases, hasChangelog, docFiles, docsType = "docs", hasShippedDocs = false, versionContext } = opts;
 	const docsSection = docFiles?.length ? `<external-docs>\n**Documentation** (use Read tool to explore):\n${formatDocTree(docFiles)}\n</external-docs>` : "";
@@ -928,12 +1117,19 @@ function getSectionDef(section, ctx, customPrompt) {
 		case "custom": return customPrompt ? customSection(customPrompt, ctx.enabledSectionCount) : null;
 	}
 }
+/**
+* Get the validate function for a section using default context (validators use fixed thresholds).
+* Returns null if section has no validator.
+*/
 function getSectionValidator(section) {
 	return getSectionDef(section, { packageName: "" }, section === "custom" ? {
 		heading: "Custom",
 		body: ""
 	} : void 0)?.validate ?? null;
 }
+/**
+* Build prompt for a single section
+*/
 function buildSectionPrompt(opts) {
 	const { packageName, hasIssues, hasDiscussions, hasReleases, hasChangelog, version, section, customPrompt, skillDir } = opts;
 	const versionContext = version ? ` v${version}` : "";
@@ -998,6 +1194,9 @@ Write your final output to the file \`${skillDir}/.skilld/${outputFile}\` using
 After writing, run \`${cmd} validate ${skillDir}/.skilld/${outputFile}\` and fix any warnings before finishing. If unavailable, use \`${fallbackCmd} validate ${skillDir}/.skilld/${outputFile}\`.
 `;
 }
+/**
+* Build prompts for all selected sections, sharing the computed preamble
+*/
 function buildAllSectionPrompts(opts) {
 	const result = /* @__PURE__ */ new Map();
 	for (const section of opts.sections) {
@@ -1010,12 +1209,28 @@ function buildAllSectionPrompts(opts) {
 	}
 	return result;
 }
+/**
+* Sanitize skill name for filesystem
+*/
 function sanitizeName(name) {
 	return name.toLowerCase().replace(/[^a-z0-9._]+/g, "-").replace(/^[.\-]+|[.\-]+$/g, "").slice(0, 255) || "unnamed-skill";
 }
+/**
+* Compute skill directory name from package name with -skilld suffix.
+* No collisions for monorepo packages (each gets a unique name).
+*
+* Examples:
+*   vue → vue-skilld
+*   @unhead/vue → unhead-vue-skilld
+*   @unhead/react → unhead-react-skilld
+*/
 function computeSkillDirName(packageName) {
 	return `${sanitizeName(packageName)}-skilld`;
 }
+/**
+* Install a skill directly to agent skill directories
+* Writes to each agent's skill folder in the project (e.g., .claude/skills/package-name/)
+*/
 function installSkillForAgents(skillName, skillContent, options = {}) {
 	const isGlobal = options.global ?? false;
 	const cwd = options.cwd || process.cwd();
@@ -1039,6 +1254,11 @@ function installSkillForAgents(skillName, skillContent, options = {}) {
 		paths
 	};
 }
+/**
+* Create relative symlinks from each detected agent's skills dir to the shared .skills/ dir.
+* Only targets agents whose config dir already exists in the project.
+* Replaces existing symlinks, skips real directories (user's custom skills).
+*/
 function linkSkillToAgents(skillName, sharedDir, cwd) {
 	for (const [, agent] of Object.entries(targets)) {
 		const agentSkillsDir = join(cwd, agent.skillsDir);
@@ -1057,6 +1277,9 @@ function linkSkillToAgents(skillName, sharedDir, cwd) {
 		symlinkSync(relative(agentSkillsDir, join(sharedDir, skillName)), target);
 	}
 }
+/**
+* Remove per-agent symlinks for a skill when removing from shared dir.
+*/
 function unlinkSkillFromAgents(skillName, cwd) {
 	for (const [, agent] of Object.entries(targets)) {
 		const target = join(cwd, agent.skillsDir, skillName);
@@ -1077,6 +1300,7 @@ function generateSkillMd(opts) {
 	const footer = generateFooter(opts.relatedSkills);
 	return sanitizeMarkdown(repairMarkdown(`${generateFrontmatter(opts)}${content}\n${footer}`));
 }
+/** Format ISO date as short absolute date: "Jan 2025", "Dec 2024" */
 function formatShortDate(isoDate) {
 	const date = new Date(isoDate);
 	if (Number.isNaN(date.getTime())) return "";
@@ -1137,6 +1361,10 @@ function generatePackageHeader({ name, description, version, releasedAt, depende
 	if (refs.length > 0) lines.push(`**References:** ${refs.join(" • ")}`);
 	return lines.join("\n");
 }
+/**
+* Expand a package name into keyword variants for better trigger matching.
+* e.g. "@nuxt/ui" → ["nuxt ui", "nuxt/ui"], "vue-router" → ["vue router"]
+*/
 function expandPackageName(name) {
 	const variants = /* @__PURE__ */ new Set();
 	const unscoped = name.replace(/^@/, "");
@@ -1151,6 +1379,10 @@ function expandPackageName(name) {
 	variants.delete(name);
 	return [...variants];
 }
+/**
+* Extract and expand GitHub repo name into keyword variants.
+* e.g. "motion-v" → ["motion-v", "motion v"]
+*/
 function expandRepoName(repoUrl) {
 	const variants = /* @__PURE__ */ new Set();
 	const repoName = repoUrl.startsWith("http") ? repoUrl.split("/").pop() : repoUrl.split("/").pop();