feat: support non-interactive link command via --agents, --skills, --mode flags

Allow the link command to run fully non-interactively by passing CLI flags
that skip the interactive @clack/prompts, enabling scripted and AI agent usage.
Global mode skips the agent multiselect when --agents is provided. Project mode
skips all three prompts (skills, mode, agents) when the corresponding flags are
provided. Includes validation for unknown skills and invalid mode values.

Author: tc9011

AGENTS.md

@@ -37,8 +37,8 @@ export const SKILL_LOCK_PATH = join(homedir(), '.agents', '.skill-lock.json');
 ```
 push:  ~/.agents/ → git add → git commit → git push origin <branch>
 pull:  git pull --rebase → auto-run link
-link:  read .skill-lock.json → detect local agents → multiselect → create relative symlinks
-link --project: read .skill-lock.json → select skills → choose copy/symlink → select agents → group by projectPath → copy/link to CWD
+link:  read .skill-lock.json → [--agents or multiselect] → create relative symlinks
+link --project: read .skill-lock.json → [--skills or select skills] → [--mode or select copy/symlink] → [--agents or select agents] → group by projectPath → copy/link to CWD
 ```
 
 ## Critical Constraints

README.md

@@ -99,11 +99,19 @@ skills-manager link --agents cursor opencode claude-code
 
 | Option | Description |
 |--------|-------------|
-| `-a, --agents <ids...>` | Agent IDs to link (default: from lock file) |
+| `-a, --agents <ids...>` | Agent IDs to link (skips agent prompt when provided) |
 | `-p, --project` | Link skills to project directory (CWD) instead of global paths |
-
+| `-s, --skills <skills...>` | Skill names to link (project mode only, skips skill prompt) |
+| `--mode <mode>` | `copy` or `symlink` (project mode only, default: `copy`, skips prompt) |
 An interactive multiselect prompt lets you pick which agents to link. Only agents with local directories are pre-selected. Your selection is remembered for next time.
 
+When `--agents` is provided, the agent selection prompt is skipped entirely — useful for scripting and AI agent automation:
+
+```bash
+# Non-interactive: link all skills to specific agents
+skills-manager link --agents cursor opencode
+```
+
 **Symlink model:**
 
 ```
@@ -119,6 +127,12 @@ When using `--project` (or `-p`), you'll go through three interactive prompts:
 2. **Copy or symlink** — copy files (default, recommended) or create absolute symlinks
 3. **Select agents** — choose which agents to set up project-level skills for
 
+All three prompts can be skipped by providing `--skills`, `--mode`, and `--agents` on the command line:
+
+```bash
+# Fully non-interactive project link
+skills-manager link --project --agents cursor claude-code --skills my-skill --mode copy
+```
 Example project structure after `link --project`:
 ```
 ./project/

skills/skills-manager/SKILL.md

@@ -61,22 +61,23 @@ Read `.skill-lock.json`, create **relative** symlinks from each agent's global s
 
 ```bash
 npx @tc9011/skills-manager link                          # interactive multiselect
-npx @tc9011/skills-manager link --agents cursor opencode # specific agents
+npx @tc9011/skills-manager link --agents cursor opencode # non-interactive (skips prompt)
 ```
 
-Selection is remembered across runs.
+When `--agents` is provided, the prompt is skipped entirely. Selection is remembered across runs.
 
 ### link --project
 
-Link or copy skills to current working directory. Three-step interactive flow:
+Link or copy skills to current working directory. Three-step interactive flow (all skippable via flags):
 
-1. **Select skills** — choose which skills (none pre-selected)
-2. **Copy or symlink** — copy (recommended) or absolute symlinks
-3. **Select agents** — choose agents for project-level setup
+1. **Select skills** (`--skills`) — choose which skills (none pre-selected)
+2. **Copy or symlink** (`--mode`) — copy (default, recommended) or absolute symlinks
+3. **Select agents** (`--agents`) — choose agents for project-level setup
 
 ```bash
 cd /path/to/project
-npx @tc9011/skills-manager link --project
+npx @tc9011/skills-manager link --project                                              # interactive
+npx @tc9011/skills-manager link --project --agents cursor --skills my-skill --mode copy # non-interactive
 ```
 
 Agents sharing the same projectPath are deduplicated.

src/commands/link.test.ts

@@ -323,13 +323,49 @@ describe('linkCommand', () => {
         .mockReturnValueOnce(true);   // for agent multiselect check
 
       const { linkCommand } = await import('./link.js');
-      await linkCommand({ agents: ['cursor'], project: true });
+      // Do NOT pass agents so the interactive prompt is shown
+      await linkCommand({ project: true });
 
       expect(prompts.cancel).toHaveBeenCalledWith('No agents selected.');
       expect(copySkills).not.toHaveBeenCalled();
       expect(createProjectSymlinks).not.toHaveBeenCalled();
     });
 
+    it('skips all prompts in project mode when --agents, --skills, --mode provided', async () => {
+      vi.mocked(listCanonicalSkills).mockResolvedValue(['my-skill', 'other-skill']);
+      vi.mocked(copySkills).mockResolvedValue([
+        { skill: 'my-skill', status: 'copied' },
+      ]);
+
+      const { linkCommand } = await import('./link.js');
+      await linkCommand({ agents: ['cursor'], project: true, skills: ['my-skill'], mode: 'copy' });
+
+      // No interactive prompts should be called
+      expect(prompts.multiselect).not.toHaveBeenCalled();
+      expect(prompts.select).not.toHaveBeenCalled();
+      expect(copySkills).toHaveBeenCalledOnce();
+      const callArgs = vi.mocked(copySkills).mock.calls[0];
+      expect(callArgs[2]).toEqual(['my-skill']);
+    });
+
+    it('throws CliError for unknown skills in --skills', async () => {
+      vi.mocked(listCanonicalSkills).mockResolvedValue(['my-skill']);
+
+      const { linkCommand } = await import('./link.js');
+      await expect(
+        linkCommand({ agents: ['cursor'], project: true, skills: ['nonexistent'], mode: 'copy' }),
+      ).rejects.toThrow(CliError);
+    });
+
+    it('throws CliError for invalid --mode value', async () => {
+      vi.mocked(listCanonicalSkills).mockResolvedValue(['my-skill']);
+
+      const { linkCommand } = await import('./link.js');
+      await expect(
+        linkCommand({ agents: ['cursor'], project: true, skills: ['my-skill'], mode: 'invalid' }),
+      ).rejects.toThrow(CliError);
+    });
+
     it('does not show skill multiselect in global mode', async () => {
       vi.mocked(getLastSelectedAgents).mockResolvedValue(['cursor'] as AgentId[]);
       vi.mocked(prompts.multiselect).mockResolvedValue(['cursor']);
@@ -345,4 +381,18 @@ describe('linkCommand', () => {
       expect(prompts.multiselect).toHaveBeenCalledOnce();
     });
   });
+
+  it('skips agent prompt in global mode when --agents provided', async () => {
+    vi.mocked(listCanonicalSkills).mockResolvedValue(['my-skill']);
+    vi.mocked(createSkillSymlinks).mockResolvedValue([
+      { skill: 'my-skill', status: 'created' },
+    ]);
+
+    const { linkCommand } = await import('./link.js');
+    await linkCommand({ agents: ['cursor'] });
+
+    // No multiselect prompt — agents provided via CLI
+    expect(prompts.multiselect).not.toHaveBeenCalled();
+    expect(createSkillSymlinks).toHaveBeenCalledOnce();
+  });
 });

src/commands/link.ts

@@ -7,7 +7,7 @@ import { getLastSelectedAgents } from '../lockfile.js';
 import { createSkillSymlinks, listCanonicalSkills, copySkills, createProjectSymlinks } from '../linker.js';
 import * as p from '@clack/prompts';
 
-export async function linkCommand(options: { agents?: string[]; project?: boolean }): Promise<void> {
+export async function linkCommand(options: { agents?: string[]; project?: boolean; skills?: string[]; mode?: string }): Promise<void> {
   p.intro('skills-manager link');
 
   // 1. Read lock file for lastSelectedAgents
@@ -42,68 +42,94 @@ export async function linkCommand(options: { agents?: string[]; project?: boolea
   if (options.project) {
     // Project mode prompt order: skills → copy/symlink → agents
 
-    // 3a. Select skills (no pre-selection in project mode)
-    const skillChoices = skills.map(name => ({
-      value: name,
-      label: name,
-    }));
-
-    const pickedSkills = await p.multiselect<string>({
-      message: 'Select skills to link:',
-      options: skillChoices,
-      required: false,
-    });
-
-    if (p.isCancel(pickedSkills) || !pickedSkills.length) {
-      p.cancel('No skills selected.');
-      return;
-    }
+    // 3a. Select skills — skip prompt if --skills provided
+    let selectedSkills: string[];
+    if (options.skills?.length) {
+      const skillSet = new Set(skills);
+      const invalid = options.skills.filter(s => !skillSet.has(s));
+      if (invalid.length > 0) {
+        p.cancel(`Unknown skill(s): ${invalid.join(', ')}. Available: ${skills.join(', ')}`);
+        throw new CliError(`Unknown skill(s): ${invalid.join(', ')}`);
+      }
+      selectedSkills = options.skills;
+    } else {
+      const skillChoices = skills.map(name => ({
+        value: name,
+        label: name,
+      }));
+
+      const pickedSkills = await p.multiselect<string>({
+        message: 'Select skills to link:',
+        options: skillChoices,
+        required: false,
+      });
+
+      if (p.isCancel(pickedSkills) || !pickedSkills.length) {
+        p.cancel('No skills selected.');
+        return;
+      }
 
-    const selectedSkills = pickedSkills as string[];
-
-    // 3b. Select copy vs symlink
-    const mode = await p.select({
-      message: 'How should skills be added to the project?',
-      options: [
-        { value: 'copy', label: 'Copy files', hint: 'recommended — independent copies' },
-        { value: 'symlink', label: 'Create symlinks', hint: 'links to ~/.agents/skills' },
-      ],
-      initialValue: 'copy',
-    });
-
-    if (p.isCancel(mode)) {
-      p.cancel('Cancelled.');
-      return;
+      selectedSkills = pickedSkills as string[];
     }
 
-    // 3c. Select agents
-    const agentChoices = agents.map(id => {
-      const projectPath = agentRegistry[id].projectPath;
-      const targetDir = join(process.cwd(), projectPath);
-      const dirExists = existsSync(targetDir);
-      return {
-        value: id as string,
-        label: `${agentRegistry[id].displayName} (${id})`,
-        hint: dirExists ? projectPath : `${projectPath} — directory will be created`,
-      };
-    });
-
-    const selected = await p.multiselect<string>({
-      message: 'Select agents to link skills to:',
-      options: agentChoices,
-      initialValues: computeInitialValues(agents, agentChoices),
-      required: false,
-    });
-
-    if (p.isCancel(selected) || !selected.length) {
-      p.cancel('No agents selected.');
-      return;
+    // 3b. Select copy vs symlink — skip prompt if --mode provided
+    let mode: string;
+    if (options.mode) {
+      if (options.mode !== 'copy' && options.mode !== 'symlink') {
+        p.cancel(`Invalid mode '${options.mode}'. Must be 'copy' or 'symlink'.`);
+        throw new CliError(`Invalid mode '${options.mode}'. Must be 'copy' or 'symlink'.`);
+      }
+      mode = options.mode;
+    } else {
+      const modeResult = await p.select({
+        message: 'How should skills be added to the project?',
+        options: [
+          { value: 'copy', label: 'Copy files', hint: 'recommended — independent copies' },
+          { value: 'symlink', label: 'Create symlinks', hint: 'links to ~/.agents/skills' },
+        ],
+        initialValue: 'copy',
+      });
+
+      if (p.isCancel(modeResult)) {
+        p.cancel('Cancelled.');
+        return;
+      }
+      mode = modeResult as string;
     }
 
-    const validSelected = new Set(Object.keys(agentRegistry));
-    const selectedAgents = (selected as string[]).filter(
-      (id): id is AgentId => validSelected.has(id)
-    );
+    // 3c. Select agents — skip prompt if --agents provided
+    let selectedAgents: AgentId[];
+    if (options.agents?.length) {
+      selectedAgents = agents;
+    } else {
+      const agentChoices = agents.map(id => {
+        const projectPath = agentRegistry[id].projectPath;
+        const targetDir = join(process.cwd(), projectPath);
+        const dirExists = existsSync(targetDir);
+        return {
+          value: id as string,
+          label: `${agentRegistry[id].displayName} (${id})`,
+          hint: dirExists ? projectPath : `${projectPath} — directory will be created`,
+        };
+      });
+
+      const selected = await p.multiselect<string>({
+        message: 'Select agents to link skills to:',
+        options: agentChoices,
+        initialValues: computeInitialValues(agents, agentChoices),
+        required: false,
+      });
+
+      if (p.isCancel(selected) || !selected.length) {
+        p.cancel('No agents selected.');
+        return;
+      }
+
+      const validSelected = new Set(Object.keys(agentRegistry));
+      selectedAgents = (selected as string[]).filter(
+        (id): id is AgentId => validSelected.has(id)
+      );
+    }
 
     // 3d. Execute: group by projectPath, copy/link
     const groups = groupAgentsByProjectPath(selectedAgents);
@@ -151,33 +177,38 @@ export async function linkCommand(options: { agents?: string[]; project?: boolea
   } else {
     // Global mode: agents → link all skills
 
-    // 3a. Select agents
-    const agentChoices = agents.map(id => {
-      const globalPath = getAgentGlobalPath(id);
-      const dirExists = existsSync(globalPath);
-      return {
-        value: id as string,
-        label: `${agentRegistry[id].displayName} (${id})`,
-        hint: dirExists ? globalPath : `${globalPath} — directory will be created`,
-      };
-    });
-
-    const selected = await p.multiselect<string>({
-      message: 'Select agents to link skills to:',
-      options: agentChoices,
-      initialValues: computeInitialValues(agents, agentChoices),
-      required: false,
-    });
-
-    if (p.isCancel(selected) || !selected.length) {
-      p.cancel('No agents selected.');
-      return;
-    }
+    // 3a. Select agents — skip prompt if --agents provided
+    let selectedAgents: AgentId[];
+    if (options.agents?.length) {
+      selectedAgents = agents;
+    } else {
+      const agentChoices = agents.map(id => {
+        const globalPath = getAgentGlobalPath(id);
+        const dirExists = existsSync(globalPath);
+        return {
+          value: id as string,
+          label: `${agentRegistry[id].displayName} (${id})`,
+          hint: dirExists ? globalPath : `${globalPath} — directory will be created`,
+        };
+      });
 
-    const validSelected = new Set(Object.keys(agentRegistry));
-    const selectedAgents = (selected as string[]).filter(
-      (id): id is AgentId => validSelected.has(id)
-    );
+      const selected = await p.multiselect<string>({
+        message: 'Select agents to link skills to:',
+        options: agentChoices,
+        initialValues: computeInitialValues(agents, agentChoices),
+        required: false,
+      });
+
+      if (p.isCancel(selected) || !selected.length) {
+        p.cancel('No agents selected.');
+        return;
+      }
+
+      const validSelected = new Set(Object.keys(agentRegistry));
+      selectedAgents = (selected as string[]).filter(
+        (id): id is AgentId => validSelected.has(id)
+      );
+    }
 
     // 3b. Link all skills for each agent
     for (const agentId of selectedAgents) {

src/index.ts

@@ -34,6 +34,8 @@ program
   .description('Create symlinks from canonical skills to agent directories')
   .option('-a, --agents <agents...>', 'Agent IDs to link (default: from .skill-lock.json)')
   .option('-p, --project', 'Link skills to project directory (CWD)')
+  .option('-s, --skills <skills...>', 'Skill names to link (project mode only, skips prompt)')
+  .option('--mode <mode>', 'copy or symlink (project mode only, skips prompt)', 'copy')
   .action(linkCommand);