feat(cli): standardize on .agents/skills/ and root AGENTS.md for universal agent discovery

packages/cli/src/commands/skills.ts

@@ -112,7 +112,7 @@ export async function handleSkillsShow(skillId: string, options: OutputOptions =
 }
 
 export interface SkillInstallOptions extends OutputOptions {
-  target?: 'gemini' | 'cursor' | 'claude' | 'auto';
+  target?: 'agents' | 'gemini' | 'cursor' | 'claude' | 'auto';
   global?: boolean;
   yes?: boolean;
 }
@@ -132,16 +132,17 @@ export async function handleSkillsInstall(skillId: string, options: SkillInstall
         name: 'target',
         message: `Select target agent environment for skill '${skillId}':`,
         choices: [
-          { title: 'Antigravity / Gemini (~/.gemini/skills/ or .gemini/skills/)', value: 'gemini' },
+          { title: 'Universal Agent Standard (.agents/skills/ — Recommended)', value: 'agents' },
           { title: 'Cursor (.cursor/rules/)', value: 'cursor' },
           { title: 'Claude Code (.claude/skills/)', value: 'claude' },
+          { title: 'Gemini (~/.gemini/skills/)', value: 'gemini' },
         ],
       });
       target = response.target;
     }
 
     const result = materializeService.materialize(workspaceRoot, skillId, {
-      target: target || 'gemini',
+      target: target || 'agents',
       global: options.global,
     });
 

packages/cli/src/services/materialize-service.ts

@@ -15,11 +15,11 @@ export class MaterializeService {
     workspaceRoot: string,
     skillId: string,
     options?: {
-      target?: 'gemini' | 'cursor' | 'claude' | 'auto';
+      target?: 'agents' | 'gemini' | 'cursor' | 'claude' | 'auto';
       global?: boolean;
     }
   ): MaterializeResult {
-    const targetAgent = options?.target && options.target !== 'auto' ? options.target : 'gemini';
+    const targetAgent = options?.target && options.target !== 'auto' ? options.target : 'agents';
     const isGlobal = !!options?.global;
 
     // Locate skill in cache
@@ -36,7 +36,11 @@ export class MaterializeService {
     let destDir = '';
     let primaryFile = '';
 
-    if (targetAgent === 'gemini') {
+    if (targetAgent === 'agents') {
+      const base = isGlobal ? path.join(os.homedir(), '.agents', 'skills') : path.join(workspaceRoot, '.agents', 'skills');
+      destDir = path.join(base, skillId);
+      primaryFile = path.join(destDir, 'SKILL.md');
+    } else if (targetAgent === 'gemini') {
       const base = isGlobal ? path.join(os.homedir(), '.gemini', 'skills') : path.join(workspaceRoot, '.gemini', 'skills');
       destDir = path.join(base, skillId);
       primaryFile = path.join(destDir, 'SKILL.md');
@@ -65,7 +69,7 @@ export class MaterializeService {
           filesCopied++;
         }
       } else {
-        // For Gemini & Claude, copy directory structure
+        // For universal .agents, Gemini & Claude, copy directory structure
         const subPath = file.startsWith(`${skillDirRel}/`)
           ? file.slice(`${skillDirRel}/`.length)
           : 'SKILL.md';

packages/cli/src/services/meta-skill-service.ts

@@ -2,16 +2,8 @@ import fs from 'node:fs';
 import path from 'node:path';
 
 export const META_SKILL_CONTENT = `---
-name: knowiki-operator
-description: Query, inspect, modify, and publish shared project knowledge, runbooks, and conventions using the Knowiki CLI.
-whenToUse: Use when the developer asks about project architecture, conventions, workflows, database rules, or asks to save, update, or propose runbooks and skills.
-triggers:
-  - "what is our convention for"
-  - "how do we deploy/migrate/test"
-  - "update the runbook"
-  - "save this knowledge/skill"
-  - "propose a rule change"
-  - "knowiki"
+name: knowiki
+description: Query, inspect, modify, and publish shared project knowledge, runbooks, and conventions using the Knowiki CLI. Use whenever asking about project conventions, architecture, runbooks, or saving shared knowledge.
 ---
 
 # Knowiki Agent Operator Guide
@@ -35,44 +27,40 @@ When the user asks to save, update, or create a skill or knowledge doc:
 4. Confirm the resulting commit SHA or Pull Request URL to the user.
 `;
 
-export const CURSOR_RULE_CONTENT = `---
-description: Knowiki project intelligence operator rule
-globs: .knowiki/**
----
+export const AGENTS_MD_SECTION = `
+# Project Intelligence (Knowiki)
 
-# Knowiki Project Intelligence Guide
+This repository uses **Knowiki** for shared project knowledge, conventions, and operational runbooks.
 
-Use the Knowiki CLI to read, inspect, and update shared project intelligence:
-- Query status: \`knowiki status --json\`
-- View knowledge: \`knowiki knowledge list\` / \`knowiki knowledge show <path>\`
-- View skills: \`knowiki skills list\` / \`knowiki skills show <skill-id>\`
-- Modify files in \`.knowiki/cache/\`, check \`knowiki diff\`, and publish via \`knowiki push -m "..."\` or \`knowiki propose\`.
+- **Local Knowledge Cache**: \`.knowiki/cache/\`
+- **Query CLI**: \`knowiki status --json\`, \`knowiki knowledge show <path>\`, \`knowiki skills list\`
+- **Skill Runbooks**: \`.agents/skills/\` (Activate the \`knowiki\` skill for runbook operations)
+- **Modifications**: When asked to update, save, or propose rules/skills, edit the file in \`.knowiki/cache/\`, inspect \`knowiki diff\`, and publish via \`knowiki push -m "..."\` (maintainers) or \`knowiki propose\` (PR review).
 `;
 
 export class MetaSkillService {
   bootstrapMetaSkill(workspaceRoot: string): { installedLocations: string[] } {
     const installedLocations: string[] = [];
 
-    // 1. Antigravity / Gemini: .gemini/skills/knowiki/SKILL.md
-    const geminiSkillDir = path.join(workspaceRoot, '.gemini', 'skills', 'knowiki');
-    fs.mkdirSync(geminiSkillDir, { recursive: true });
-    const geminiSkillFile = path.join(geminiSkillDir, 'SKILL.md');
-    fs.writeFileSync(geminiSkillFile, META_SKILL_CONTENT, 'utf8');
-    installedLocations.push('.gemini/skills/knowiki/SKILL.md');
-
-    // 2. Cursor: .cursor/rules/knowiki.mdc
-    const cursorDir = path.join(workspaceRoot, '.cursor', 'rules');
-    fs.mkdirSync(cursorDir, { recursive: true });
-    const cursorFile = path.join(cursorDir, 'knowiki.mdc');
-    fs.writeFileSync(cursorFile, CURSOR_RULE_CONTENT, 'utf8');
-    installedLocations.push('.cursor/rules/knowiki.mdc');
+    // 1. Universal Agent Standard: .agents/skills/knowiki/SKILL.md
+    const agentsSkillDir = path.join(workspaceRoot, '.agents', 'skills', 'knowiki');
+    fs.mkdirSync(agentsSkillDir, { recursive: true });
+    const agentsSkillFile = path.join(agentsSkillDir, 'SKILL.md');
+    fs.writeFileSync(agentsSkillFile, META_SKILL_CONTENT, 'utf8');
+    installedLocations.push('.agents/skills/knowiki/SKILL.md');
 
-    // 3. Claude: .claude/skills/knowiki/SKILL.md
-    const claudeDir = path.join(workspaceRoot, '.claude', 'skills', 'knowiki');
-    fs.mkdirSync(claudeDir, { recursive: true });
-    const claudeFile = path.join(claudeDir, 'SKILL.md');
-    fs.writeFileSync(claudeFile, META_SKILL_CONTENT, 'utf8');
-    installedLocations.push('.claude/skills/knowiki/SKILL.md');
+    // 2. Project Root Context: AGENTS.md
+    const agentsMdPath = path.join(workspaceRoot, 'AGENTS.md');
+    if (fs.existsSync(agentsMdPath)) {
+      const existing = fs.readFileSync(agentsMdPath, 'utf8');
+      if (!existing.includes('Project Intelligence (Knowiki)')) {
+        fs.appendFileSync(agentsMdPath, `\n${AGENTS_MD_SECTION.trim()}\n`, 'utf8');
+        installedLocations.push('AGENTS.md (updated)');
+      }
+    } else {
+      fs.writeFileSync(agentsMdPath, AGENTS_MD_SECTION.trim() + '\n', 'utf8');
+      installedLocations.push('AGENTS.md');
+    }
 
     return { installedLocations };
   }

packages/cli/test/materialize-service.test.ts

@@ -16,23 +16,23 @@ describe('MaterializeService', () => {
     fs.rmSync(testDir, { recursive: true, force: true });
   });
 
-  it('materializes skill into Gemini environment', () => {
+  it('materializes skill into universal .agents environment by default', () => {
     cacheService.writeCachedFile(
       testDir,
       'skills/db-migrate/SKILL.md',
       '---\nname: db-migrate\n---\n# DB Migration Runbook'
     );
 
-    const result = materializeService.materialize(testDir, 'db-migrate', { target: 'gemini' });
-    expect(result.targetAgent).toBe('gemini');
+    const result = materializeService.materialize(testDir, 'db-migrate');
+    expect(result.targetAgent).toBe('agents');
     expect(result.filesCopied).toBe(1);
 
-    const destFile = path.join(testDir, '.gemini', 'skills', 'db-migrate', 'SKILL.md');
+    const destFile = path.join(testDir, '.agents', 'skills', 'db-migrate', 'SKILL.md');
     expect(fs.existsSync(destFile)).toBe(true);
     expect(fs.readFileSync(destFile, 'utf8')).toContain('DB Migration Runbook');
   });
 
-  it('materializes skill into Cursor environment as .mdc rule', () => {
+  it('materializes skill into Cursor environment as .mdc rule when requested', () => {
     cacheService.writeCachedFile(
       testDir,
       'skills/testing/SKILL.md',

packages/cli/test/meta-skill-service.test.ts

@@ -15,17 +15,21 @@ describe('MetaSkillService', () => {
     fs.rmSync(testDir, { recursive: true, force: true });
   });
 
-  it('bootstraps meta-skill files across Gemini, Cursor, and Claude target paths', () => {
+  it('bootstraps universal .agents/skills/knowiki/SKILL.md and project AGENTS.md', () => {
     const result = metaSkillService.bootstrapMetaSkill(testDir);
 
-    expect(result.installedLocations).toContain('.gemini/skills/knowiki/SKILL.md');
-    expect(result.installedLocations).toContain('.cursor/rules/knowiki.mdc');
-    expect(result.installedLocations).toContain('.claude/skills/knowiki/SKILL.md');
+    expect(result.installedLocations).toContain('.agents/skills/knowiki/SKILL.md');
+    expect(result.installedLocations).toContain('AGENTS.md');
 
-    const geminiSkillPath = path.join(testDir, '.gemini', 'skills', 'knowiki', 'SKILL.md');
-    expect(fs.existsSync(geminiSkillPath)).toBe(true);
-    const content = fs.readFileSync(geminiSkillPath, 'utf8');
-    expect(content).toContain('name: knowiki-operator');
-    expect(content).toContain('knowiki status');
+    const agentsSkillPath = path.join(testDir, '.agents', 'skills', 'knowiki', 'SKILL.md');
+    expect(fs.existsSync(agentsSkillPath)).toBe(true);
+    const skillContent = fs.readFileSync(agentsSkillPath, 'utf8');
+    expect(skillContent).toContain('name: knowiki');
+    expect(skillContent).toContain('knowiki status');
+
+    const agentsMdPath = path.join(testDir, 'AGENTS.md');
+    expect(fs.existsSync(agentsMdPath)).toBe(true);
+    const mdContent = fs.readFileSync(agentsMdPath, 'utf8');
+    expect(mdContent).toContain('Project Intelligence (Knowiki)');
   });
 });