feat: add --scope flag for project vs user skill installation

Author: vildanbina

package-lock.json

@@ -1,6 +1,6 @@
 {
     "name": "@yavydev/cli",
-    "version": "0.2.1",
+    "version": "0.2.2",
     "description": "Search and manage your AI-ready documentation on Yavy",
     "type": "module",
     "bin": {

package.json

@@ -6,13 +6,14 @@ import { getAccessToken } from '@/auth/store';
 import { error, warn } from '@/utils';
 import { configureTool, type ConfigureResult } from '@/commands/init/configure-tool';
 import { resolveToolFromFlag, scanForTools } from '@/commands/init/scan-tools';
-import { AiTool, TOOL_CONFIGS, type InitOptions } from '@/commands/init/types';
+import { AiTool, type Scope, TOOL_CONFIGS, type InitOptions } from '@/commands/init/types';
 
 export function initCommand(): Command {
     return new Command('init')
         .description('Set up Yavy for your AI tools (skills + MCP config)')
         .option('--tool <name>', 'Configure a specific tool only')
         .option('--projects <slugs>', 'Comma-separated project slugs to configure (skips interactive selection)')
+        .option('--scope <scope>', 'Install scope: "project" (default) or "user" (global, applies to all projects)')
         .option('--yes', 'Non-interactive mode: configure all detected tools + all projects')
         .action(async (options: InitOptions) => {
             try {
@@ -51,13 +52,15 @@ async function runInit(options: InitOptions): Promise<void> {
         process.exit(0);
     }
 
+    const scope = resolveScope(options, selectedTools);
+
     const s = p.spinner();
     s.start('Configuring tools...');
 
     const results: ConfigureResult[] = [];
     for (const tool of selectedTools) {
         try {
-            results.push(configureTool(tool, selectedProjects, process.cwd()));
+            results.push(configureTool(tool, selectedProjects, process.cwd(), scope));
         } catch (err) {
             warn(`Failed to configure ${TOOL_CONFIGS[tool].name}: ${err instanceof Error ? err.message : String(err)}`);
         }
@@ -70,7 +73,8 @@ async function runInit(options: InitOptions): Promise<void> {
             .map((r) => {
                 const config = TOOL_CONFIGS[r.tool];
                 const mcp = r.mcpConfigured ? ` + MCP` : '';
-                return `${chalk.bold(config.name)}: ${r.skillPath} (${r.projectFiles.length} project files${mcp})`;
+                const scopeLabel = r.scope === 'user' ? ' [user]' : ' [project]';
+                return `${chalk.bold(config.name)}: ${r.skillPath}${scopeLabel} (${r.projectFiles.length} project files${mcp})`;
             })
             .join('\n'),
         'Summary',
@@ -180,6 +184,27 @@ async function selectProjects(projects: ApiProject[], options: InitOptions): Pro
     return projects.filter((proj) => selectedSlugs.has(proj.slug));
 }
 
+function resolveScope(options: InitOptions, tools: AiTool[]): Scope {
+    if (options.scope) {
+        const normalized = options.scope.toLowerCase() as Scope;
+        if (normalized !== 'project' && normalized !== 'user') {
+            p.log.error(`Invalid scope: ${options.scope}. Use "project" or "user".`);
+            process.exit(1);
+        }
+
+        if (normalized === 'user') {
+            const unsupported = tools.filter((t) => !TOOL_CONFIGS[t].userSkillDir);
+            if (unsupported.length > 0) {
+                warn(`User scope not supported for: ${unsupported.map((t) => TOOL_CONFIGS[t].name).join(', ')}. Using project scope for those.`);
+            }
+        }
+
+        return normalized;
+    }
+
+    return 'project';
+}
+
 async function fetchProjects(client: YavyApiClient): Promise<ApiProject[]> {
     const s = p.spinner();
     s.start('Fetching projects...');

src/commands/init.ts

@@ -1,21 +1,31 @@
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
 import { dirname, join } from 'node:path';
+import { homedir } from 'node:os';
 import type { ApiProject } from '@/api/client';
 import { YAVY_BASE_URL } from '@/config';
 import { generateProjectContent, generateSkillContent, slugify } from '@/commands/init/generate-skill';
-import { type AiTool, TOOL_CONFIGS } from '@/commands/init/types';
+import { type AiTool, type Scope, TOOL_CONFIGS } from '@/commands/init/types';
 import { warn } from '@/utils';
 
 export interface ConfigureResult {
     tool: AiTool;
     skillPath: string;
+    scope: Scope;
     mcpConfigured: boolean;
     projectFiles: string[];
 }
 
-export function configureTool(tool: AiTool, projects: ApiProject[], cwd: string): ConfigureResult {
+export function configureTool(tool: AiTool, projects: ApiProject[], cwd: string, scope: Scope = 'project'): ConfigureResult {
     const config = TOOL_CONFIGS[tool];
-    const skillDir = join(cwd, config.skillDir);
+
+    let skillDir: string;
+    let effectiveScope: Scope = scope;
+    if (scope === 'user' && config.userSkillDir) {
+        skillDir = join(homedir(), config.userSkillDir);
+    } else {
+        skillDir = join(cwd, config.skillDir);
+        effectiveScope = 'project';
+    }
     const projectsDir = join(skillDir, 'projects');
 
     mkdirSync(projectsDir, { recursive: true });
@@ -44,7 +54,7 @@ export function configureTool(tool: AiTool, projects: ApiProject[], cwd: string)
         }
     }
 
-    return { tool, skillPath, mcpConfigured, projectFiles };
+    return { tool, skillPath, scope: effectiveScope, mcpConfigured, projectFiles };
 }
 
 function buildMcpUrl(projects: ApiProject[]): string {

src/commands/init/configure-tool.ts

@@ -6,10 +6,13 @@ export enum AiTool {
     OpenCode = 'opencode',
 }
 
+export type Scope = 'project' | 'user';
+
 export interface ToolConfig {
     name: string;
     detectDir: string;
     skillDir: string;
+    userSkillDir: string | null;
     mcpConfigPath: string | null;
     mcpFormat: 'json' | 'embedded' | null;
     mcpServerKey?: string;
@@ -18,6 +21,7 @@ export interface ToolConfig {
 export interface InitOptions {
     tool?: string;
     projects?: string;
+    scope?: Scope;
     yes?: boolean;
 }
 
@@ -26,34 +30,39 @@ export const TOOL_CONFIGS: Record<AiTool, ToolConfig> = {
         name: 'Claude Code',
         detectDir: '.claude',
         skillDir: '.claude/skills/yavy',
+        userSkillDir: '.claude/skills/yavy',
         mcpConfigPath: null,
         mcpFormat: null,
     },
     [AiTool.Cursor]: {
         name: 'Cursor',
         detectDir: '.cursor',
         skillDir: '.cursor/rules/yavy',
+        userSkillDir: null, // Cursor has no filesystem-based global rules path
         mcpConfigPath: '.cursor/mcp.json',
         mcpFormat: 'json',
     },
     [AiTool.Vscode]: {
         name: 'VS Code',
         detectDir: '.vscode',
         skillDir: '.github/instructions/yavy',
+        userSkillDir: '.copilot/instructions/yavy',
         mcpConfigPath: '.vscode/mcp.json',
         mcpFormat: 'json',
     },
     [AiTool.Windsurf]: {
         name: 'Windsurf',
         detectDir: '.windsurf',
         skillDir: '.windsurf/rules/yavy',
+        userSkillDir: null, // Windsurf uses a single global file, not a directory
         mcpConfigPath: null,
         mcpFormat: null,
     },
     [AiTool.OpenCode]: {
         name: 'OpenCode',
         detectDir: '.opencode',
         skillDir: '.opencode/skills/yavy',
+        userSkillDir: '.config/opencode/skills/yavy',
         mcpConfigPath: 'opencode.json',
         mcpFormat: 'embedded',
         mcpServerKey: 'mcp',

src/commands/init/types.ts

@@ -125,7 +125,7 @@ describe('initCommand', () => {
         await run(['--tool', 'claude-code']);
 
         expect(resolveToolFromFlag).toHaveBeenCalledWith('claude-code');
-        expect(configureTool).toHaveBeenCalledWith(AiTool.ClaudeCode, expect.any(Array), '/project');
+        expect(configureTool).toHaveBeenCalledWith(AiTool.ClaudeCode, expect.any(Array), '/project', 'project');
     });
 
     it('exits with error for unknown --tool', async () => {