feat(claude): add skills-first agent activation [ACORE-SKILLS]

Author: rafaelscosta

.aiox-core/core-config.yaml

@@ -312,6 +312,7 @@ ideSync:
     claude-code:
       enabled: true
       path: .claude/commands/AIOX/agents
+      skillsPath: .claude/skills
       format: full-markdown-yaml
     codex:
       enabled: true

.aiox-core/core/doctor/checks/ide-sync.js

@@ -1,8 +1,8 @@
 /**
  * Doctor Check: IDE Sync
  *
- * Validates agents in .claude/commands/AIOX/agents/ match
- * .aiox-core/development/agents/ (count and names).
+ * Validates Claude agent skills and legacy command files match
+ * .aiox-core/development/agents/ during the skills-first transition.
  *
  * @module aiox-core/doctor/checks/ide-sync
  * @story INS-4.1
@@ -15,7 +15,8 @@ const name = 'ide-sync';
 
 async function run(context) {
   const agentsSourceDir = path.join(context.projectRoot, '.aiox-core', 'development', 'agents');
-  const agentsIdeDir = path.join(context.projectRoot, '.claude', 'commands', 'AIOX', 'agents');
+  const agentsCommandDir = path.join(context.projectRoot, '.claude', 'commands', 'AIOX', 'agents');
+  const agentsSkillDir = path.join(context.projectRoot, '.claude', 'skills', 'AIOX', 'agents');
 
   if (!fs.existsSync(agentsSourceDir)) {
     return {
@@ -26,16 +27,7 @@ async function run(context) {
     };
   }
 
-  if (!fs.existsSync(agentsIdeDir)) {
-    return {
-      check: name,
-      status: 'WARN',
-      message: 'IDE agents directory not found (.claude/commands/AIOX/agents/)',
-      fixCommand: 'npx aiox-core install --force',
-    };
-  }
-
-  let sourceAgents, ideFiles;
+  let sourceAgents;
   try {
     sourceAgents = fs.readdirSync(agentsSourceDir)
       .filter((f) => f.endsWith('.md'))
@@ -49,35 +41,43 @@ async function run(context) {
     };
   }
 
-  try {
-    ideFiles = fs.readdirSync(agentsIdeDir)
-      .filter((f) => f.endsWith('.md'));
-  } catch (_err) {
+  const commandAgents = fs.existsSync(agentsCommandDir)
+    ? fs.readdirSync(agentsCommandDir)
+      .filter((f) => f.endsWith('.md'))
+      .map((f) => f.replace('.md', ''))
+    : [];
+  const skillAgents = fs.existsSync(agentsSkillDir)
+    ? fs.readdirSync(agentsSkillDir, { withFileTypes: true })
+      .filter((entry) => entry.isDirectory() && fs.existsSync(path.join(agentsSkillDir, entry.name, 'SKILL.md')))
+      .map((entry) => entry.name)
+    : [];
+
+  const sourceCount = sourceAgents.length;
+  const commandCount = commandAgents.length;
+  const skillCount = skillAgents.length;
+
+  if (skillCount !== sourceCount) {
     return {
       check: name,
       status: 'WARN',
-      message: 'Cannot read IDE agents directory',
+      message: `Claude skills have ${skillCount} agents, source has ${sourceCount}`,
       fixCommand: 'npx aiox-core install --force',
     };
   }
 
-  const ideAgents = ideFiles.map((f) => f.replace('.md', ''));
-  const sourceCount = sourceAgents.length;
-  const ideCount = ideAgents.length;
-
-  if (sourceCount === ideCount) {
+  if (commandCount === sourceCount) {
     return {
       check: name,
       status: 'PASS',
-      message: `${ideCount}/${sourceCount} agents synced`,
+      message: `${skillCount}/${sourceCount} Claude skills synced; ${commandCount}/${sourceCount} legacy commands synced`,
       fixCommand: null,
     };
   }
 
   return {
     check: name,
     status: 'WARN',
-    message: `IDE has ${ideCount} agents, source has ${sourceCount}`,
+    message: `${skillCount}/${sourceCount} Claude skills synced; legacy commands have ${commandCount}/${sourceCount}`,
     fixCommand: 'npx aiox-core install --force',
   };
 }

.aiox-core/core/doctor/checks/skills-count.js

@@ -1,8 +1,10 @@
 /**
  * Doctor Check: Skills Count
  *
- * Counts skill directories in .claude/skills/ that contain SKILL.md.
- * PASS: >=7, WARN: 1-6, FAIL: 0 or directory missing.
+ * Counts SKILL.md files in .claude/skills/ recursively.
+ * PASS: >=7 total skills and all AIOX agent skills present.
+ * WARN: skills exist but AIOX agent skills are incomplete.
+ * FAIL: 0 or directory missing.
  *
  * @module aiox-core/doctor/checks/skills-count
  * @story INS-4.8
@@ -13,8 +15,58 @@ const fs = require('fs');
 
 const name = 'skills-count';
 
+function countSkillFiles(dir) {
+  let count = 0;
+  let entries;
+
+  try {
+    entries = fs.readdirSync(dir, { withFileTypes: true });
+  } catch {
+    return 0;
+  }
+
+  for (const entry of entries) {
+    const fullPath = path.join(dir, entry.name);
+    if (entry.isDirectory()) {
+      count += countSkillFiles(fullPath);
+    } else if (entry.isFile() && entry.name === 'SKILL.md') {
+      count++;
+    }
+  }
+
+  return count;
+}
+
+function countAgentSkillFiles(agentSkillsDir) {
+  let entries;
+
+  try {
+    entries = fs.readdirSync(agentSkillsDir, { withFileTypes: true });
+  } catch {
+    return 0;
+  }
+
+  return entries.filter((entry) => (
+    entry.isDirectory() && fs.existsSync(path.join(agentSkillsDir, entry.name, 'SKILL.md'))
+  )).length;
+}
+
+function countSourceAgents(sourceAgentsDir) {
+  let entries;
+
+  try {
+    entries = fs.readdirSync(sourceAgentsDir, { withFileTypes: true });
+  } catch {
+    return 0;
+  }
+
+  return entries.filter((entry) => entry.isFile() && entry.name.endsWith('.md')).length;
+}
+
 async function run(context) {
   const skillsDir = path.join(context.projectRoot, '.claude', 'skills');
+  const agentSkillsDir = path.join(skillsDir, 'AIOX', 'agents');
+  const sourceAgentsDir = path.join(context.projectRoot, '.aiox-core', 'development', 'agents');
 
   if (!fs.existsSync(skillsDir)) {
     return {
@@ -25,29 +77,24 @@ async function run(context) {
     };
   }
 
-  let entries;
-  try {
-    entries = fs.readdirSync(skillsDir, { withFileTypes: true });
-  } catch {
+  const count = countSkillFiles(skillsDir);
+  const agentSkillCount = countAgentSkillFiles(agentSkillsDir);
+  const sourceAgentCount = countSourceAgents(sourceAgentsDir);
+
+  if (count === 0) {
     return {
       check: name,
       status: 'FAIL',
-      message: 'Cannot read skills directory',
+      message: 'No skills found (expected >=7)',
       fixCommand: 'npx aiox-core install --force',
     };
   }
 
-  const skills = entries.filter(
-    (d) => d.isDirectory() && fs.existsSync(path.join(skillsDir, d.name, 'SKILL.md')),
-  );
-
-  const count = skills.length;
-
-  if (count === 0) {
+  if (sourceAgentCount > 0 && agentSkillCount !== sourceAgentCount) {
     return {
       check: name,
-      status: 'FAIL',
-      message: 'No skills found (expected >=7)',
+      status: 'WARN',
+      message: `${count} skills found, but AIOX agent skills are incomplete (${agentSkillCount}/${sourceAgentCount})`,
       fixCommand: 'npx aiox-core install --force',
     };
   }
@@ -56,17 +103,23 @@ async function run(context) {
     return {
       check: name,
       status: 'PASS',
-      message: `${count} skills found`,
+      message: `${count} skills found (${agentSkillCount}/${sourceAgentCount} AIOX agent skills)`,
       fixCommand: null,
     };
   }
 
   return {
     check: name,
     status: 'WARN',
-    message: `Only ${count}/7 skills found`,
+    message: `Only ${count}/7 skills found (${agentSkillCount}/${sourceAgentCount} AIOX agent skills)`,
     fixCommand: 'npx aiox-core install --force',
   };
 }
 
-module.exports = { name, run };
+module.exports = {
+  name,
+  run,
+  countSkillFiles,
+  countAgentSkillFiles,
+  countSourceAgents,
+};

.aiox-core/framework-config.yaml

@@ -122,6 +122,7 @@ ide_sync_system:
     claude-code:
       enabled: true
       path: ".claude/commands/AIOX/agents"
+      skillsPath: ".claude/skills"
       format: "full-markdown-yaml"
     codex:
       enabled: true

.aiox-core/infrastructure/scripts/codex-skills-sync/validate.js

@@ -7,6 +7,8 @@ const path = require('path');
 const { parseAllAgents } = require('../ide-sync/agent-parser');
 const { getSkillId } = require('./index');
 
+const GENERATED_MARKER = '<!-- AIOX-CODEX-LOCAL-SKILLS: generated -->';
+
 function getDefaultOptions() {
   const projectRoot = process.cwd();
   return {
@@ -59,14 +61,32 @@ function validateSkillContent(content, expected) {
   return issues;
 }
 
+function extractGeneratedSquadSource(content) {
+  const match = String(content || '').match(/`(squads\/[^`]+\/agents\/[^`]+\.md)`/);
+  return match ? match[1] : '';
+}
+
+function isGeneratedSquadSkill(content, projectRoot) {
+  if (!String(content || '').includes(GENERATED_MARKER)) {
+    return false;
+  }
+
+  const sourcePath = extractGeneratedSquadSource(content);
+  if (!sourcePath) {
+    return false;
+  }
+
+  return fs.existsSync(path.join(projectRoot, sourcePath));
+}
+
 function validateCodexSkills(options = {}) {
   const resolved = { ...getDefaultOptions(), ...options };
   const errors = [];
   const warnings = [];
 
   if (!fs.existsSync(resolved.skillsDir)) {
     errors.push(`Skills directory not found: ${resolved.skillsDir}`);
-    return { ok: false, checked: 0, expected: 0, errors, warnings, missing: [], orphaned: [] };
+    return { ok: false, checked: 0, expected: 0, errors, warnings, missing: [], orphaned: [], ignored: [] };
   }
 
   const agents = parseAllAgents(resolved.sourceDir).filter(isParsableAgent);
@@ -100,12 +120,26 @@ function validateCodexSkills(options = {}) {
 
   const expectedIds = new Set(expected.map(item => item.skillId));
   const orphaned = [];
+  const ignored = [];
   if (resolved.strict) {
     const dirs = fs.readdirSync(resolved.skillsDir, { withFileTypes: true })
       .filter(entry => entry.isDirectory() && entry.name.startsWith('aiox-'))
       .map(entry => entry.name);
     for (const dir of dirs) {
       if (!expectedIds.has(dir)) {
+        const skillPath = path.join(resolved.skillsDir, dir, 'SKILL.md');
+        let content = '';
+        try {
+          content = fs.readFileSync(skillPath, 'utf8');
+        } catch (_error) {
+          content = '';
+        }
+
+        if (isGeneratedSquadSkill(content, resolved.projectRoot)) {
+          ignored.push(dir);
+          continue;
+        }
+
         orphaned.push(dir);
         errors.push(`Orphaned skill directory: ${path.join(path.relative(resolved.projectRoot, resolved.skillsDir), dir)}`);
       }
@@ -124,6 +158,7 @@ function validateCodexSkills(options = {}) {
     warnings,
     missing,
     orphaned,
+    ignored,
   };
 }
 
@@ -167,6 +202,8 @@ if (require.main === module) {
 module.exports = {
   validateCodexSkills,
   validateSkillContent,
+  extractGeneratedSquadSource,
+  isGeneratedSquadSkill,
   parseArgs,
   getDefaultOptions,
 };