feat: add --universal flag and make project install default (v1.2.0)

Major changes:

1. Added --universal flag for .agent/skills installation
   - Default: .claude/skills (Claude Code compatible)
   - With --universal: .agent/skills (universal AGENTS.md for all agents)
   - Works with both project and global installs

2. Changed default from global to project install
   - No flags → .claude/skills (project, recommended)
   - --global → ~/.claude/skills (advanced users)
   - Project install is now the default behavior

3. Support for 4 installation locations with priority
   - .agent/skills (project universal) - priority 1
   - ~/.agent/skills (global universal) - priority 2
   - .claude/skills (project) - priority 3
   - ~/.claude/skills (global) - priority 4

4. Deduplication in list/read commands
   - Skills with same name only show once (highest priority wins)
   - Prevents duplicates when skills exist in both .agent and .claude

Breaking changes:
- Removed --project flag, replaced with --global flag
- Default install location changed from global to project

Migration:
- Old: openskills install X --project
- New: openskills install X (project is now default)
- Old: openskills install X
- New: openskills install X --global

Use cases:
- Claude Code + other agents: Use --universal to install to .agent/skills
- Claude Code only: Use default (installs to .claude/skills)
- Share skills across projects: Use --global

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>

Author: Numman Ali

package.json

@@ -1,6 +1,6 @@
 {
   "name": "openskills",
-  "version": "1.1.0",
+  "version": "1.2.0",
   "description": "Universal skills loader for AI coding agents - install and load Anthropic SKILL.md format skills in any agent",
   "type": "module",
   "main": "./dist/cli.js",

src/cli.ts

@@ -13,7 +13,7 @@ const program = new Command();
 program
   .name('openskills')
   .description('Universal skills loader for AI coding agents')
-  .version('1.0.0')
+  .version('1.2.0')
   .showHelpAfterError(false)
   .exitOverride((err) => {
     // Handle all commander errors gracefully (no stack traces)
@@ -40,7 +40,8 @@ program
 program
   .command('install <source>')
   .description('Install skill from GitHub or Git URL')
-  .option('-p, --project', 'Install to project .claude/skills/ (recommended)')
+  .option('-g, --global', 'Install globally (default: project install)')
+  .option('-u, --universal', 'Install to .agent/skills/ (for universal AGENTS.md usage)')
   .option('-y, --yes', 'Skip interactive selection, install all skills found')
   .action(installSkill);
 

src/commands/install.ts

@@ -14,13 +14,15 @@ import type { InstallOptions } from '../types.js';
  * Install skill from GitHub or Git URL
  */
 export async function installSkill(source: string, options: InstallOptions): Promise<void> {
-  const targetDir = options.project
-    ? join(process.cwd(), '.claude/skills')
-    : join(homedir(), '.claude/skills');
+  const folder = options.universal ? '.agent/skills' : '.claude/skills';
+  const isProject = !options.global; // Default to project unless --global specified
+  const targetDir = isProject
+    ? join(process.cwd(), folder)
+    : join(homedir(), folder);
 
-  const location = options.project
-    ? chalk.blue('project (.claude/skills)')
-    : chalk.dim('global (~/.claude/skills)');
+  const location = isProject
+    ? chalk.blue(`project (${folder})`)
+    : chalk.dim(`global (~/${folder})`);
 
   console.log(`Installing from: ${chalk.cyan(source)}`);
   console.log(`Location: ${location}\n`);
@@ -63,7 +65,7 @@ export async function installSkill(source: string, options: InstallOptions): Pro
 
     if (skillSubpath) {
       // Specific skill path provided - install directly
-      await installSpecificSkill(repoDir, skillSubpath, targetDir, options.project || false);
+      await installSpecificSkill(repoDir, skillSubpath, targetDir, isProject);
     } else {
       // Find all skills in repo
       await installFromRepo(repoDir, targetDir, options);
@@ -74,7 +76,7 @@ export async function installSkill(source: string, options: InstallOptions): Pro
   }
 
   console.log(`\n${chalk.dim('Read skill:')} ${chalk.cyan('openskills read <skill-name>')}`);
-  if (options.project) {
+  if (isProject) {
     console.log(`${chalk.dim('Sync to AGENTS.md:')} ${chalk.cyan('openskills sync')}`);
   }
 }

src/commands/list.ts

@@ -12,8 +12,8 @@ export function listSkills(): void {
   if (skills.length === 0) {
     console.log('No skills installed.\n');
     console.log('Install skills:');
-    console.log(`  ${chalk.cyan('openskills install anthropics/skills --project')}    ${chalk.dim('# Recommended')}`);
-    console.log(`  ${chalk.cyan('openskills install owner/unique-skill')}             ${chalk.dim('# Global (advanced)')}`);
+    console.log(`  ${chalk.cyan('openskills install anthropics/skills')}         ${chalk.dim('# Project (default)')}`);
+    console.log(`  ${chalk.cyan('openskills install owner/skill --global')}     ${chalk.dim('# Global (advanced)')}`);
     return;
   }
 

src/commands/manage.ts

@@ -46,7 +46,7 @@ export async function manageSkills(): Promise<void> {
       const skill = findSkill(skillName);
       if (skill) {
         rmSync(skill.baseDir, { recursive: true, force: true });
-        const location = skill.source.includes('/.claude/skills') ? 'project' : 'global';
+        const location = skill.source.includes(process.cwd()) ? 'project' : 'global';
         console.log(chalk.green(`✅ Removed: ${skillName} (${location})`));
       }
     }

src/commands/read.ts

@@ -10,6 +10,8 @@ export function readSkill(skillName: string): void {
   if (!skill) {
     console.error(`Error: Skill '${skillName}' not found`);
     console.error('\nSearched:');
+    console.error('  .agent/skills/ (project universal)');
+    console.error('  ~/.agent/skills/ (global universal)');
     console.error('  .claude/skills/ (project)');
     console.error('  ~/.claude/skills/ (global)');
     console.error('\nInstall skills: openskills install owner/repo');

src/types.ts

@@ -12,7 +12,8 @@ export interface SkillLocation {
 }
 
 export interface InstallOptions {
-  project?: boolean;
+  global?: boolean;
+  universal?: boolean;
   yes?: boolean;
 }
 

src/utils/dirs.ts

@@ -4,18 +4,22 @@ import { homedir } from 'os';
 /**
  * Get skills directory path
  */
-export function getSkillsDir(projectLocal: boolean = false): string {
+export function getSkillsDir(projectLocal: boolean = false, universal: boolean = false): string {
+  const folder = universal ? '.agent/skills' : '.claude/skills';
   return projectLocal
-    ? join(process.cwd(), '.claude/skills')
-    : join(homedir(), '.claude/skills');
+    ? join(process.cwd(), folder)
+    : join(homedir(), folder);
 }
 
 /**
  * Get all searchable skill directories in priority order
+ * Priority: project .agent > global .agent > project .claude > global .claude
  */
 export function getSearchDirs(): string[] {
   return [
-    join(process.cwd(), '.claude/skills'),  // Project-local first
-    join(homedir(), '.claude/skills'),       // Global second
+    join(process.cwd(), '.agent/skills'),   // 1. Project universal (.agent)
+    join(homedir(), '.agent/skills'),        // 2. Global universal (.agent)
+    join(process.cwd(), '.claude/skills'),  // 3. Project claude
+    join(homedir(), '.claude/skills'),       // 4. Global claude
   ];
 }

src/utils/skills.ts

@@ -9,6 +9,7 @@ import type { Skill, SkillLocation } from '../types.js';
  */
 export function findAllSkills(): Skill[] {
   const skills: Skill[] = [];
+  const seen = new Set<string>();
   const dirs = getSearchDirs();
 
   for (const dir of dirs) {
@@ -18,17 +19,22 @@ export function findAllSkills(): Skill[] {
 
     for (const entry of entries) {
       if (entry.isDirectory()) {
+        // Deduplicate: only add if we haven't seen this skill name yet
+        if (seen.has(entry.name)) continue;
+
         const skillPath = join(dir, entry.name, 'SKILL.md');
         if (existsSync(skillPath)) {
           const content = readFileSync(skillPath, 'utf-8');
-          const isProjectLocal = dir === join(process.cwd(), '.claude/skills');
+          const isProjectLocal = dir.includes(process.cwd());
 
           skills.push({
             name: entry.name,
             description: extractYamlField(content, 'description'),
             location: isProjectLocal ? 'project' : 'global',
             path: join(dir, entry.name),
           });
+
+          seen.add(entry.name);
         }
       }
     }

tests/utils/dirs.test.ts

@@ -4,22 +4,34 @@ import { homedir } from 'os';
 import { getSkillsDir, getSearchDirs } from '../../src/utils/dirs.js';
 
 describe('getSkillsDir', () => {
-  it('should return global dir by default', () => {
+  it('should return global .claude dir by default', () => {
     const dir = getSkillsDir();
     expect(dir).toBe(join(homedir(), '.claude/skills'));
   });
 
-  it('should return project dir when projectLocal is true', () => {
+  it('should return project .claude dir when projectLocal is true', () => {
     const dir = getSkillsDir(true);
     expect(dir).toBe(join(process.cwd(), '.claude/skills'));
   });
+
+  it('should return global .agent dir when universal is true', () => {
+    const dir = getSkillsDir(false, true);
+    expect(dir).toBe(join(homedir(), '.agent/skills'));
+  });
+
+  it('should return project .agent dir when both projectLocal and universal are true', () => {
+    const dir = getSkillsDir(true, true);
+    expect(dir).toBe(join(process.cwd(), '.agent/skills'));
+  });
 });
 
 describe('getSearchDirs', () => {
-  it('should return dirs in priority order', () => {
+  it('should return all 4 dirs in priority order', () => {
     const dirs = getSearchDirs();
-    expect(dirs).toHaveLength(2);
-    expect(dirs[0]).toBe(join(process.cwd(), '.claude/skills'));
-    expect(dirs[1]).toBe(join(homedir(), '.claude/skills'));
+    expect(dirs).toHaveLength(4);
+    expect(dirs[0]).toBe(join(process.cwd(), '.agent/skills'));   // 1. Project universal
+    expect(dirs[1]).toBe(join(homedir(), '.agent/skills'));        // 2. Global universal
+    expect(dirs[2]).toBe(join(process.cwd(), '.claude/skills'));  // 3. Project claude
+    expect(dirs[3]).toBe(join(homedir(), '.claude/skills'));       // 4. Global claude
   });
 });