ccski 2.3.1 → 2.4.0

package/README.md

@@ -8,10 +8,12 @@ Documentation site: https://jixoai-labs.github.io/ccski/
 
 - [Install](#install)
 - [Quick start](#quick-start)
+  - [Connect ccski to your agent prompt](#connect-ccski-to-your-agent-prompt)
   - [Run MCP server](#run-mcp-server)
   - [Core CLI commands](#core-cli-commands)
   - [Install examples](#install-examples)
   - [Enable/disable](#enabledisable)
+  - [Discovery roots and priority](#discovery-roots-and-priority)
 - [More](#more)
 - [Acknowledgements](#acknowledgements)
 - [API Reference](#api-reference)
@@ -31,6 +33,52 @@ ccski --help
 
 ## Quick start
 
+### Connect ccski to your agent prompt
+
+ccski works best when your agent is told how to discover local skills at the
+start of a new context. The installer writes a managed English workflow block
+into common agent instruction files:
+
+```bash
+npx -y ccski install
+```
+
+By default this installs at user scope for known agents:
+
+- Codex: `~/.codex/AGENTS.md`
+- Claude Code: `~/.claude/CLAUDE.md`
+- Gemini CLI: `~/.gemini/GEMINI.md`
+- OpenCode: `~/.config/opencode/AGENTS.md`
+
+Limit the target or install only into the current project:
+
+```bash
+# one agent, user scope
+npx -y ccski install --agent=codex
+
+# one project file in the current directory
+npx -y ccski install --agent=gemini --project
+
+# preview changes
+npx -y ccski install --dry-run --json
+```
+
+The installer is idempotent. It replaces only the managed
+`<workflow name="ccski">...</workflow>` block and preserves the rest of your
+prompt file.
+
+Manual install is also fine. Add this block to your user or project instruction
+file, such as `~/.codex/AGENTS.md`, `~/.claude/CLAUDE.md`, or
+`~/.gemini/GEMINI.md`:
+
+```md
+<workflow name="ccski">
+When starting a new context, run `bunx ccski list --no-color` to discover extra local skills available on this machine, especially shared `agents:user` skills and agent-specific skills such as `claude:user`, `codex:user`, and `gemini:user`.
+If the user names a skill, or a task clearly matches a skill that is not already exposed in the current session, do not assume the skill is unavailable. First run `bunx ccski list --no-color`, then run `bunx ccski info <name>` and load the `SKILL.md` path reported by the output.
+`ccski` may emit compatibility warnings while reading local agent or plugin metadata, such as `installed_plugins.json`. These warnings do not necessarily block `list` or `info`; prefer `--no-color` for readable output and downstream parsing.
+</workflow>
+```
+
 ### Run MCP server
 
 ```bash
@@ -55,15 +103,16 @@ MCP plugin config example (Codex/Cursor/Windsurf/VS Code):
 
 ### Core CLI commands
 
-| Command                                         | Purpose                                                                        |
-| ----------------------------------------------- | ------------------------------------------------------------------------------ |
-| `ccski list`                                    | List discovered skills (project, user, plugin)                                 |
-| `ccski info <name>`                             | Show metadata and content preview                                              |
-| `ccski install <source> [-i\|--all\|--path]`    | Install from git/dir/marketplace/SKILL.md; interactive picker available        |
-| `ccski enable [names...] [-i\|--all]`           | Enable skills (`.SKILL.md` -> `SKILL.md`)                                      |
-| `ccski disable [names...] [-i\|--all]`          | Disable skills (`SKILL.md` -> `.SKILL.md`)                                     |
-| `ccski validate <path>`                         | Validate SKILL.md or skill directory                                           |
-| `ccski mcp`                                     | Start MCP server (stdio/http/sse)                                              |
+| Command                                      | Purpose                                                                 |
+| -------------------------------------------- | ----------------------------------------------------------------------- |
+| `ccski list`                                 | List discovered skills (project, user, plugin)                          |
+| `ccski info <name>`                          | Show metadata and content preview                                       |
+| `ccski install`                              | Install the ccski workflow block into agent instruction files           |
+| `ccski install <source> [-i\|--all\|--path]` | Install from git/dir/marketplace/SKILL.md; interactive picker available |
+| `ccski enable [names...] [-i\|--all]`        | Enable skills (`.SKILL.md` -> `SKILL.md`)                               |
+| `ccski disable [names...] [-i\|--all]`       | Disable skills (`SKILL.md` -> `.SKILL.md`)                              |
+| `ccski validate <path>`                      | Validate SKILL.md or skill directory                                    |
+| `ccski mcp`                                  | Start MCP server (stdio/http/sse)                                       |
 
 ### Install examples
 
@@ -87,6 +136,27 @@ ccski enable -i
 ccski disable --all
 ```
 
+### Discovery roots and priority
+
+By default ccski scans shared and agent-specific skill roots in the workspace and user
+home directory. Built-in agent roots include `.claude/skills`, `.codex/skills`,
+`.gemini/skills`, and `.openclaw/skills`; ccski also discovers shallow dynamic
+agent roots such as `.<agent>/skills`.
+
+When `auto` selection sees the same skill name in multiple roots, ccski keeps every
+copy internally but chooses one by source priority:
+
+1. `--skill-dir` custom roots
+2. `<workspace>/.<agent>/skills`
+3. `<workspace>/.agents/skills`
+4. `<workspace>/skills`
+5. `~/.<agent>/skills`
+6. `~/.agents/skills`
+7. Claude plugin skills
+
+If two copies have the same source priority, the newer `SKILL.md` or `.SKILL.md`
+mtime wins. If mtimes also tie, provider ordering is deterministic.
+
 ## More
 
 - Programmatic API is available from the package export; see [API Reference](#api-reference) (or the docs site) for usage examples.

package/dist/cli.mjs

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
 import { x as __require } from "./create-prompt-CIJV_96B.mjs";
-import { $ as AmbiguousSkillNameError, A as highlight, C as formatSkillLabel, D as error, E as duplicateBadge, F as tone, I as warn, L as containsCaseInsensitive, M as renderList, N as setColorEnabled, O as formatBytes, P as success, R as rankStrings, S as SkillRegistry, T as dim, U as compareSkillProviders, W as providerNamesFromSkills, _ as listSkills, a as InstallCancelledError, b as computeDuplicateGroups, f as validateSkill, g as resolveSkill, h as getSkillInfo, i as toggleSkills, j as info, k as heading, l as installSkills, n as MultiSelectError, nt as SkillNotFoundError, o as MultiSkillSelectionError, p as searchSkills, r as ToggleCancelledError, s as createConsoleInstallOutput, t as startMCPServer, u as registerInstallCleanupHandlers, v as buildRegistryOptions, w as colors, x as parseFilters, y as applyFilters } from "./server-y5_8eQ5a.mjs";
+import { A as colors, B as success, C as resolveSkill, D as parseFilters, E as computeDuplicateGroups, F as heading, H as warn, I as highlight, L as info, M as duplicateBadge, N as error, O as SkillRegistry, P as formatBytes, R as renderList, S as getSkillInfo, T as applyFilters, U as containsCaseInsensitive, V as tone, W as rankStrings, X as providerNamesFromSkills, Y as compareSkillProviders, at as AmbiguousSkillNameError, b as promptMultiSelect, c as ToggleCancelledError, ct as SkillNotFoundError, f as startMCPServer, g as createConsoleInstallOutput, h as MultiSkillSelectionError, i as listAgentInstructionTargets, j as dim, k as formatSkillLabel, l as toggleSkills, m as InstallCancelledError, o as validateSkill, p as listSkills, r as installCcskiWorkflow, s as MultiSelectError, u as searchSkills, v as installSkills, w as buildRegistryOptions, y as registerInstallCleanupHandlers, z as setColorEnabled } from "./workflow-install-D85Tfr9z.mjs";
 import { readFileSync, statSync } from "node:fs";
 import { readFileSync as readFileSync$1, readdirSync as readdirSync$1, statSync as statSync$1, writeFile } from "fs";
 import { homedir } from "node:os";
@@ -4193,6 +4193,68 @@ async function infoCommand(argv) {
 	}
 }
 
+//#endregion
+//#region src/cli/commands/install-workflow.ts
+async function installWorkflowCommand(argv) {
+	try {
+		const scope = resolveWorkflowScope(argv);
+		const explicitAgents = [...normalizeArray(argv.agents), ...normalizeArray(argv.agent)];
+		const agents = explicitAgents.length > 0 ? explicitAgents : await maybePromptAgents(argv);
+		const result = installCcskiWorkflow({
+			...agents.length > 0 ? { agents } : {},
+			scope,
+			...argv.userDir !== void 0 ? { userDir: argv.userDir } : {},
+			...argv.dryRun !== void 0 ? { dryRun: argv.dryRun } : {}
+		});
+		if (argv.json) console.log(JSON.stringify(result, null, 2));
+		else printWorkflowInstallSummary(result);
+		if (result.failed > 0) process.exitCode = 1;
+	} catch (err) {
+		console.error(error(`Install failed: ${err instanceof Error ? err.message : String(err)}`));
+		process.exitCode = 1;
+	}
+}
+function resolveWorkflowScope(argv) {
+	if (argv.project && argv.user) throw new Error("Use only one of --project or --user.");
+	if (argv.project) return "project";
+	if (argv.user) return "user";
+	return argv.scope ?? "user";
+}
+function normalizeArray(values) {
+	if (!values) return [];
+	return Array.isArray(values) ? values.map(String) : [String(values)];
+}
+async function maybePromptAgents(argv) {
+	if (!argv.interactive) return [];
+	if (!process.stdin.isTTY || !process.stdout.isTTY) throw new Error("Interactive workflow install requires a TTY. Use --agent instead.");
+	return promptMultiSelect({
+		message: "Select agent prompt target(s)",
+		choices: listAgentInstructionTargets().map((target) => ({
+			value: target.id,
+			label: `${tone.bold(target.label)} ${dim(target.id)}`,
+			description: `${target.userPath.join("/")} / ${target.projectPath.join("/")}`,
+			checked: true
+		})),
+		defaultChecked: true,
+		command: {
+			base: "ccski install",
+			label: "Command",
+			argPrefix: "--agent"
+		}
+	});
+}
+function printWorkflowInstallSummary(summary) {
+	console.log(info(`Installing ccski workflow instructions (${summary.scope} scope)\n`));
+	for (const result of summary.results) {
+		const status = result.status === "installed" ? tone.success("✓ installed") : result.status === "updated" ? tone.warning("↻ updated") : result.status === "unchanged" ? dim("○ unchanged") : tone.danger("✗ failed");
+		const errorText = result.error ? ` ${tone.danger(result.error)}` : "";
+		console.log(`${tone.bold(result.label)}: ${status} ${dim(result.path)}${errorText}`);
+	}
+	console.log();
+	console.log(dim(`Known targets: ${listAgentInstructionTargets().map((target) => target.id).join(", ")}`));
+	console.log(dim("Use --agent=<name> to limit targets, --project for the current directory, or --dry-run."));
+}
+
 //#endregion
 //#region src/cli/commands/install.ts
 async function installCommand(argv) {
@@ -4200,8 +4262,13 @@ async function installCommand(argv) {
 	if (argv.color) setColorEnabled(true);
 	registerInstallCleanupHandlers();
 	const skills = Array.isArray(argv._) ? argv._.slice(1).map(String) : [];
+	const source = typeof argv.source === "string" ? argv.source : skills.shift();
+	if (!source) {
+		await installWorkflowCommand(argv);
+		return;
+	}
 	const options = {
-		source: argv.source,
+		source,
 		skills,
 		...argv.force !== void 0 ? { force: argv.force } : {},
 		...argv.override !== void 0 ? { override: argv.override } : {},
@@ -4756,11 +4823,28 @@ const mcpModule = {
 	handler: mcpCommand
 };
 const installModule = {
-	command: "install <source>",
-	describe: "Install a skill into .claude/skills",
+	command: "install [source]",
+	describe: "Install ccski workflow instructions, or install skills from a source",
 	builder: (cmd) => cmd.positional("source", {
 		type: "string",
-		demandOption: true
+		description: "Optional git/dir/marketplace/SKILL.md source. Omit to install ccski workflow instructions."
+	}).option("agent", {
+		alias: "A",
+		type: "array",
+		string: true,
+		description: "Agent prompt target for workflow install (repeatable, default: all)"
+	}).option("scope", {
+		choices: ["user", "project"],
+		default: "user",
+		description: "Workflow install scope when no source is provided"
+	}).option("user", {
+		type: "boolean",
+		default: false,
+		description: "Install workflow instructions at user scope"
+	}).option("project", {
+		type: "boolean",
+		default: false,
+		description: "Install workflow instructions in the current project"
 	}).option("out-dir", {
 		type: "array",
 		string: true,