antigravity-ide 4.2.0 → 4.2.1

package/scripts/internal/automation/auto-release.js

@@ -0,0 +1,177 @@
+/**
+ * @script auto-release.js
+ * @version 4.2.0
+ * @layer automation
+ * @protocol unified-protocol-v1
+ * @description Tự động cập nhật version và số liệu thống kê trên toàn bộ dự án.
+ */
+
+const fs = require('fs');
+const path = require('path');
+const { execSync } = require('child_process');
+
+function logError(error, context) {
+    const errorLogPath = path.join(process.cwd(), 'ERRORS.md');
+    const timestamp = new Date().toISOString().replace('T', ' ').substring(0, 16);
+    const entry = `
+## [${timestamp}] - Auto-Release Script Failure
+
+- **Type**: Runtime
+- **Severity**: High
+- **File**: \`.agent/scripts/automation/auto-release.js\`
+- **Agent**: Senior Automation Engine
+- **Root Cause**: ${context}
+- **Error Message**: 
+  \`\`\`
+  ${error.message || error}
+  \`\`\`
+- **Fix Applied**: N/A - Diagnostic logged
+- **Prevention**: Check project state and Git permissions
+- **Status**: Investigating
+
+---
+`;
+    fs.appendFileSync(errorLogPath, entry);
+}
+
+// 1. Cấu hình các file cần cập nhật Version
+const VERSION_FILES = [
+    {
+        path: 'package.json',
+        regex: /"version": "\d+\.\d+\.\d+"/g,
+        template: (ver) => `"version": "${ver}"`
+    },
+    {
+        path: 'VERSION',
+        regex: /\d+\.\d+\.\d+/g,
+        template: (ver) => `${ver}`
+    },
+    {
+        path: 'MASTER_GUIDE.md',
+        regex: /\*\*Version\*\*: \d+\.\d+\.\d+/g,
+        template: (ver) => `**Version**: ${ver}`
+    },
+    {
+        path: 'README.md',
+        regex: /antigravity-ide@\d+\.\d+\.\d+/g, // Update npx command example if generic
+        template: (ver) => `antigravity-ide@${ver}`
+    }
+];
+
+// 2. Cấu hình các file cần cập nhật Số liệu (Stats)
+const STATS_FILES = [
+    'README.md',
+    'README.vi.md',
+    'GEMINI_GUIDE.md',
+    'SKILLS.md'
+];
+
+// Helper: Đếm số lượng trong thư mục
+function countItems(dirPath, filterFn) {
+    const fullPath = path.join(process.cwd(), '.agent', dirPath);
+    if (!fs.existsSync(fullPath)) return 0;
+    return fs.readdirSync(fullPath, { withFileTypes: true })
+        .filter(filterFn).length;
+}
+
+// Logic chính
+function main() {
+    const newVersion = process.argv[2];
+    
+    if (!newVersion) {
+        console.error("❌ Error: Vui lòng cung cấp version mới. Ví dụ: node .agent/scripts/auto-release.js 4.0.4");
+        process.exit(1);
+    }
+
+    console.log(`🚀 Starting Release Process for v${newVersion}...\n`);
+
+    // --- A. Cập nhật Version ---
+    console.log("1️⃣  Updating Version Numbers...");
+    let updatedFiles = 0;
+
+    VERSION_FILES.forEach(config => {
+        const filePath = path.join(process.cwd(), config.path);
+        if (fs.existsSync(filePath)) {
+            let content = fs.readFileSync(filePath, 'utf8');
+            if (config.regex.test(content)) {
+                const newContent = content.replace(config.regex, config.template(newVersion));
+                fs.writeFileSync(filePath, newContent);
+                console.log(`   ✅ Updated ${config.path}`);
+                updatedFiles++;
+            } else {
+                console.log(`   ⚠️  Current version pattern not found in ${config.path} (Skipped)`);
+            }
+        }
+    });
+
+    // --- B. Cập nhật Thống kê Real-time ---
+    console.log("\n2️⃣  Updating Live Statistics...");
+    
+    const stats = {
+        skills: countItems('skills', item => item.isDirectory()), // Folder là skill
+        workflows: countItems('workflows', item => item.isFile() && item.name.endsWith('.md')),
+        rules: countItems('rules', item => item.isFile() && item.name.endsWith('.md')),
+        agents: countItems('agents', item => item.isFile() && item.name.endsWith('.md'))
+    };
+
+    console.log(`   📊 Detected: ${stats.skills} Skills | ${stats.agents} Agents | ${stats.workflows} Workflows | ${stats.rules} Rules`);
+
+    STATS_FILES.forEach(fileName => {
+        const filePath = path.join(process.cwd(), fileName);
+        if (fs.existsSync(filePath)) {
+            let content = fs.readFileSync(filePath, 'utf8');
+            
+            // Regex thay thế số lượng (VD: **26** Skills -> **27** Skills)
+            // Pattern: | **XX** [Text] |
+            
+            // Update Skills
+            content = content.replace(/\|\s*\*\*\d+\*\*\s*(Master Skills|Bộ Kỹ năng|Skills)/g, 
+                `| **${stats.skills}** $1`);
+            
+            // Update Workflows
+            content = content.replace(/\|\s*\*\*\d+\*\*\s*(Workflows|Quy trình|Quy trình \(Workflows\))/g, 
+                `| **${stats.workflows}** $1`);
+            
+            // Update Agents
+            content = content.replace(/\|\s*\*\*\d+\*\*\s*(Specialist Agents|Agent Chuyên gia)/g, 
+                `| **${stats.agents}** $1`);
+
+            // Update GEMINI_GUIDE total skills text
+            content = content.replace(/Total: \d+ Master Skills/g, `Total: ${stats.skills} Master Skills`);
+            content = content.replace(/\*\*All \d+ Master Skills/g, `**All ${stats.skills} Master Skills`);
+
+            fs.writeFileSync(filePath, content);
+            console.log(`   ✅ Synced stats to ${fileName}`);
+        }
+    });
+
+    // --- C. Rà soát tính năng mới (Gợi ý Changelog) ---
+    console.log("\n3️⃣  Scanning for Recent Changes (Git)...");
+    try {
+        // Lấy danh sách file mới thêm trong 24h qua (hoặc chưa commit)
+        const gitStatus = execSync('git status --short').toString();
+        const newFiles = gitStatus.split('\n')
+            .filter(line => line.startsWith('A') || line.startsWith('??'))
+            .map(line => line.substring(3)); // Bỏ prefix trạng thái
+
+        const newFeatures = newFiles.filter(f => f.includes('.agent/skills') || f.includes('.agent/workflows') || f.includes('.agent/rules'));
+
+        if (newFeatures.length > 0) {
+            console.log("   ✨ New features detected (Add these to CHANGELOG.md):");
+            newFeatures.forEach(f => console.log(`      - ${f}`));
+        } else {
+            console.log("   ℹ️  No new feature files detected via Git status.");
+        }
+    } catch (e) {
+        console.log("   ⚠️  Could not run git check (optional step).");
+    }
+
+    console.log("\n✅ Auto-Release Complete! Please verify changes and commit.");
+}
+
+try {
+    main();
+} catch (err) {
+    console.error("❌ Critical Script Error:", err.message);
+    logError(err, "General script failure during main execution loop");
+}

package/scripts/internal/fractalize-skills.js

@@ -0,0 +1,89 @@
+const fs = require('fs');
+const path = require('path');
+
+const SKILLS_DIR = 'd:\\Github\\antigravity-ide\\.agent\\skills';
+
+function fractalizeSkill(skillName) {
+  const skillDir = path.join(SKILLS_DIR, skillName);
+  const skillFile = path.join(skillDir, 'SKILL.md');
+  
+  if (!fs.existsSync(skillFile)) {
+    console.warn(`⚠️ SKILL.md not found for ${skillName}, skipping.`);
+    return;
+  }
+
+  const content = fs.readFileSync(skillFile, 'utf-8');
+
+  // Regex to extract Sections that look like Sub-skills
+  // This is heuristically complex. 
+  // For now, simpler strategy: 
+  // 1. Create `sub-skills` folder.
+  // 2. Identify H3 headers (### Title) as potential sub-skills.
+  // 3. Split content and create files.
+  // 4. Rewrite SKILL.md to link to them.
+  
+  // BUT: Doing this blindly for 500 skills is DANGEROUS and LOW QUALITY.
+  // Better Strategy for now (Safe Fractalization):
+  // 1. Just create the `sub-skills` directory structure if missing.
+  // 2. If `resources` folder exists and has .md files, MOVE them to `sub-skills`.
+  // 3. Update SKILL.md frontmatter to include `version: x.x.x-fractal`.
+  
+  const subSkillsDir = path.join(skillDir, 'sub-skills');
+  if (!fs.existsSync(subSkillsDir)) {
+    fs.mkdirSync(subSkillsDir);
+  }
+
+  // Move Resources to Sub-skills
+  const resourcesDir = path.join(skillDir, 'resources');
+  if (fs.existsSync(resourcesDir)) {
+     const files = fs.readdirSync(resourcesDir);
+     files.forEach(file => {
+       if (file.endsWith('.md')) {
+         const src = path.join(resourcesDir, file);
+         const dest = path.join(subSkillsDir, file);
+         fs.renameSync(src, dest);
+         console.log(`📦 Moved ${file} from resources to sub-skills for ${skillName}`);
+       }
+     });
+     // Clean up if empty
+     if (fs.readdirSync(resourcesDir).length === 0) {
+       fs.rmdirSync(resourcesDir);
+     }
+  }
+
+  // Update Frontmatter
+  let newContent = content;
+  if (!content.includes('version:')) {
+    newContent = content.replace('---', `---\nversion: 4.1.0-fractal`);
+  } else if (!content.includes('-fractal')) {
+    newContent = content.replace(/version: (.*)/, `version: 4.1.0-fractal`);
+  }
+
+  if (fs.existsSync(subSkillsDir) && fs.readdirSync(subSkillsDir).length > 0) {
+     // Append "Knowledge Modules" section if there are sub-skills and it's missing
+     if (!newContent.includes('Knowledge Modules')) {
+       newContent += '\n\n## 🧠 Knowledge Modules (Fractal Skills)\n\n';
+       const subFiles = fs.readdirSync(subSkillsDir);
+       subFiles.forEach((file, index) => {
+         newContent += `### ${index + 1}. [${file.replace('.md', '')}](./sub-skills/${file})\n`;
+       });
+     }
+  }
+
+  fs.writeFileSync(skillFile, newContent);
+  console.log(`✅ Fractalized: ${skillName}`);
+}
+
+function main() {
+  const skills = fs.readdirSync(SKILLS_DIR, { withFileTypes: true })
+    .filter(dirent => dirent.isDirectory())
+    .map(dirent => dirent.name);
+
+  skills.forEach(skill => {
+    // Skip if already correct
+    if (skill === 'security-auditor') return; 
+    fractalizeSkill(skill);
+  });
+}
+
+main();

package/scripts/internal/generate-skill-definitions.js

@@ -0,0 +1,134 @@
+const fs = require('fs');
+const path = require('path');
+
+const skillsDir = path.join(__dirname, '..', '..', '.agent', 'skills');
+const outputFile = path.join(__dirname, '..', '..', 'cli', 'logic', 'skill-definitions.js');
+
+// 1. Get all skill names
+const allSkills = fs.readdirSync(skillsDir).filter(f => fs.statSync(path.join(skillsDir, f)).isDirectory());
+
+// 2. Define Category Keywords (Priority Order matters for overlapping terms)
+const categoryKeywords = {
+    security: ['security', 'pentest', 'hack', 'malware', 'vulnerability', 'auth', 'compliance', 'red-team', 'forensics', 'exploit', 'owasp', 'scanning', 'threat', 'ssh', 'ssl', 'encryption', 'pci', 'gdpr', 'stride'],
+    ai: ['ai-', 'llm', 'agent', 'langgraph', 'langchain', 'prompt', 'rag', 'vector', 'embedding', 'model', 'autogen', 'crewai', 'machine-learning', 'ml-', 'deep-learning', 'vision', 'voice', 'chatbot', 'gpt', 'claude', 'gemini', 'context'],
+    mobile: ['mobile', 'android', 'ios', 'flutter', 'react-native', 'expo', 'swift', 'kotlin', 'app-store'],
+    devops: ['devops', 'docker', 'kubernetes', 'k8s', 'terraform', 'aws', 'azure', 'gcp', 'cloud', 'ci/cd', 'pipeline', 'deploy', 'server', 'linux', 'bash', 'shell', 'monitor', 'observability', 'infra', 'terminal', 'powershell', 'bazel', 'turborepo', 'nx', 'git', 'ansible', 'helm', 'prometheus', 'grafana'],
+    testing: ['test', 'tdd', 'playwright', 'cypress', 'selenium', 'puppeteer', 'jest', 'vitest', 'e2e', 'qa', 'quality', 'debugging', 'debugger'],
+    uiux: ['ui', 'ux', 'design', 'css', 'tailwind', 'animation', 'style', 'theme', 'accessibility', 'wcag', 'canvas', 'svg', 'd3', 'icon', 'color', 'font', 'layout', 'responsive', 'frontend'],
+    growth: ['seo', 'analytics', 'marketing', 'growth', 'copy', 'content', 'social', 'email', 'conversion', 'cro', 'pricing', 'sales', 'business', 'startup', 'product', 'advertising', 'ads'],
+    webdev: ['web', 'react', 'next', 'vue', 'angular', 'svelte', 'html', 'javascript', 'typescript', 'node', 'express', 'nestjs', 'api', 'graphql', 'rest', 'backend', 'full-stack', 'frontend', 'wasm', 'pwa', 'remix', 'shopify', 'wordpress', 'django', 'flask', 'fastapi', 'php', 'ruby', 'rails', 'go-', 'rust', 'java', 'c-', 'cpp'],
+    research: ['research', 'analysis', 'strategy', 'brainstorm', 'plan', 'document', 'architecture', 'diagram', 'uml', 'c4', 'review', 'audit'],
+    // Maker matches everything else useful for building
+    maker: ['tool', 'automation', 'productivity', 'notion', 'obsidian', 'workflow', 'script', 'bot', 'scraper', 'data', 'excel', 'csv', 'pdf', 'video', 'image', 'audio', 'file', 'mcp']
+};
+
+const categorizedSkills = {
+    webdev: [],
+    mobile: [],
+    ai: [],
+    research: [],
+    uiux: [],
+    devops: [],
+    security: [],
+    growth: [],
+    maker: [],
+    testing: []
+};
+
+const assignedSkills = new Set();
+
+// 3. Auto-Categorize
+allSkills.forEach(skill => {
+    let assigned = false;
+    const lowerName = skill.toLowerCase();
+
+    // Check specific categories first
+    for (const [cat, keywords] of Object.entries(categoryKeywords)) {
+        if (keywords.some(k => lowerName.includes(k))) {
+            categorizedSkills[cat].push(skill);
+            assignedSkills.add(skill);
+            assigned = true;
+            break; // Assign to first matching category (priority based on order in object)
+        }
+    }
+
+    // Fallback logic
+    if (!assigned) {
+        // If not assigned, put in 'maker' as general tools
+        categorizedSkills.maker.push(skill);
+    }
+});
+
+// 4. Generate File Content
+const fileContent = `/**
+ * Centralized definition of all Agent Skills and their categories.
+ * Auto-generated by .agent/scripts/generate-skill-definitions.js
+ * Total Skills: ${allSkills.length}
+ */
+
+const skillCategories = {
+  webdev: {
+    name: 'Web High-Performance (Vercel & Antfu Grade)',
+    skills: ${JSON.stringify(categorizedSkills.webdev, null, 2).replace(/"/g, "'")}
+  },
+  mobile: {
+    name: 'Mobile Development (iOS, Android, Cross-Platform)',
+    skills: ${JSON.stringify(categorizedSkills.mobile, null, 2).replace(/"/g, "'")}
+  },
+  ai: {
+    name: 'Advanced AI & Research (AutoGen & LangGraph)',
+    skills: ${JSON.stringify(categorizedSkills.ai, null, 2).replace(/"/g, "'")}
+  },
+  research: {
+    name: 'Strategic Research & Wisdom (Fabric Patterns)',
+    skills: ${JSON.stringify(categorizedSkills.research, null, 2).replace(/"/g, "'")}
+  },
+  uiux: {
+    name: 'UI/UX Pro Max (NextLevel Aesthetics)',
+    skills: ${JSON.stringify(categorizedSkills.uiux, null, 2).replace(/"/g, "'")}
+  },
+  devops: {
+    name: 'DevOps & Cloud (Enterprise Grade)',
+    skills: ${JSON.stringify(categorizedSkills.devops, null, 2).replace(/"/g, "'")}
+  },
+  security: {
+    name: 'Security & Compliance (Fintech Standards)',
+    skills: ${JSON.stringify(categorizedSkills.security, null, 2).replace(/"/g, "'")}
+  },
+  growth: {
+    name: 'Growth & Business Intelligence',
+    skills: ${JSON.stringify(categorizedSkills.growth, null, 2).replace(/"/g, "'")}
+  },
+  maker: {
+    name: 'Maker & Indie Hacking (Sickn33) ',
+    skills: ${JSON.stringify(categorizedSkills.maker, null, 2).replace(/"/g, "'")}
+  },
+  testing: {
+    name: 'Professional QA & Testing',
+    skills: ${JSON.stringify(categorizedSkills.testing, null, 2).replace(/"/g, "'")}
+  }
+};
+
+function getSkillsForCategories(categories) {
+  const skills = [];
+  categories.forEach(category => {
+    if (skillCategories[category]) {
+      skills.push(...skillCategories[category].skills);
+    }
+  });
+  return skills;
+}
+
+module.exports = {
+  skillCategories,
+  getSkillsForCategories
+};
+`;
+
+// 5. Write File
+fs.writeFileSync(outputFile, fileContent);
+console.log(`Successfully generated skill definitions for ${allSkills.length} skills.`);
+console.log('Breakdown:');
+Object.keys(categorizedSkills).forEach(cat => {
+    console.log(`  - ${cat}: ${categorizedSkills[cat].length}`);
+});

package/scripts/internal/internal/update-docs.js

@@ -0,0 +1,115 @@
+/**
+ * @script update-docs.js
+ * @version 4.2.0
+ * @layer internal
+ * @protocol unified-protocol-v1
+ * @description Tự động cập nhật số liệu thống kê trong các file tài liệu hướng dẫn.
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+// Đường dẫn các file cần cập nhật
+const DOCS_FILES = {
+    README_VI: 'README.vi.md',
+    README_EN: 'README.md',
+    SKILLS_GUIDE: 'docs/SKILLS_GUIDE.vi.md',
+    RULES_GUIDE: 'docs/RULES_GUIDE.vi.md',
+    WORKFLOW_GUIDE: 'docs/WORKFLOW_GUIDE.vi.md'
+};
+
+// Đếm số lượng Skills
+function countSkills() {
+    const skillsDir = path.join(process.cwd(), '.agent', 'skills');
+    if (!fs.existsSync(skillsDir)) return 0;
+    
+    try {
+        const items = fs.readdirSync(skillsDir, { withFileTypes: true });
+        return items.filter(item => item.isDirectory()).length;
+    } catch (err) {
+        logError(err, "Failed to read skills directory");
+        return 0;
+    }
+}
+
+// Đếm số lượng Workflows
+function countWorkflows() {
+    const workflowsDir = path.join(process.cwd(), '.agent', 'workflows');
+    if (!fs.existsSync(workflowsDir)) return 0;
+    
+    const items = fs.readdirSync(workflowsDir);
+    return items.filter(item => item.endsWith('.md')).length;
+}
+
+// Đếm số lượng Rules
+function countRules() {
+    const rulesDir = path.join(process.cwd(), '.agent', 'rules');
+    if (!fs.existsSync(rulesDir)) return 0;
+    
+    const items = fs.readdirSync(rulesDir);
+    return items.filter(item => item.endsWith('.md')).length;
+}
+
+// Cập nhật số liệu trong README
+function updateCounts() {
+    const skills = countSkills();
+    const workflows = countWorkflows();
+    const rules = countRules();
+    
+    console.log('📊 Current Statistics:');
+    console.log(`   Skills: ${skills}`);
+    console.log(`   Workflows: ${workflows}`);
+    console.log(`   Rules: ${rules}`);
+    
+    return { skills, workflows, rules };
+}
+
+// Main function
+async function main() {
+    console.log('🚀 Auto-Update Documentation System\n');
+    
+    const stats = updateCounts();
+    
+    console.log('\n✅ Statistics collected successfully!');
+    console.log('💡 Tip: Use this data to update README.md and other docs manually for now.');
+    console.log('   Future versions will support automatic text replacement.');
+}
+
+function logError(error, context) {
+    const errorLogPath = path.join(process.cwd(), 'ERRORS.md');
+    const timestamp = new Date().toISOString().replace('T', ' ').substring(0, 16);
+    const entry = `
+## [${timestamp}] - Update-Docs Script Failure
+
+- **Type**: Runtime
+- **Severity**: Low
+- **File**: \`.agent/scripts/internal/update-docs.js\`
+- **Agent**: Senior Documentation Engine
+- **Root Cause**: ${context}
+- **Error Message**: 
+  \`\`\`
+  ${error.message || error}
+  \`\`\`
+- **Fix Applied**: N/A
+- **Prevention**: Ensure file system permissions are correct
+- **Status**: Investigating
+
+---
+`;
+    fs.appendFileSync(errorLogPath, entry);
+}
+
+// Run if called directly
+if (require.main === module) {
+    try {
+        main().catch(err => {
+            logError(err, "Async main execution failed");
+            console.error(err);
+        });
+    } catch (err) {
+        logError(err, "Sync main execution failed");
+        console.error(err);
+    }
+}
+
+module.exports = { countSkills, countWorkflows, countRules, updateCounts };

package/scripts/internal/refactor-skill-content.js

@@ -0,0 +1,127 @@
+const fs = require('fs');
+const path = require('path');
+
+const SKILL_NAME = process.argv[2] || '3d-web-experience';
+const SKILLS_DIR = 'd:\\Github\\antigravity-ide\\.agent\\skills';
+const SKILL_DIR = path.join(SKILLS_DIR, SKILL_NAME);
+const SKILL_FILE = path.join(SKILL_DIR, 'SKILL.md');
+const SUB_SKILLS_DIR = path.join(SKILL_DIR, 'sub-skills');
+
+function slugify(text) {
+  return text.toString().toLowerCase()
+    .replace(/\s+/g, '-')           // Replace spaces with -
+    .replace(/[^\w\-]+/g, '')       // Remove all non-word chars
+    .replace(/\-\-+/g, '-')         // Replace multiple - with single -
+    .replace(/^-+/, '')             // Trim - from start of text
+    .replace(/-+$/, '');            // Trim - from end of text
+}
+
+// Main Execution for ALL skills
+function main() {
+  const allSkills = fs.readdirSync(SKILLS_DIR, { withFileTypes: true })
+    .filter(dirent => dirent.isDirectory())
+    .map(dirent => dirent.name);
+
+  console.log(`🚀 Starting Batch Refactor for ${allSkills.length} skills...`);
+
+  let count = 0;
+  allSkills.forEach(skillName => {
+    // PROTECTED SKILLS - DO NOT TOUCH
+    if (skillName === 'security-auditor') return;
+    
+    // Check if already fractalized deeply? 
+    // Heuristic: If SKILL.md is small (< 500 bytes) and sub-skills has many files, maybe skip?
+    // But for now, let's force run to ensure safety. 
+    // WAIT: If we run this twice on `3d-web-experience`, it might re-extract the links?
+    // content.split(/^### /gm) -> The links are `### 1. [Title]...`
+    // So it will extract the link line as a new file content!
+    // BAD. We need to detect if it's already a link list.
+    
+    if (isAlreadyLinked(skillName)) {
+      console.log(`⏩ Skipping ${skillName} (Already fractalized)`);
+      return;
+    }
+
+    processSkill(skillName);
+    count++;
+  });
+
+  console.log(`✅ Completed. Refactored ${count} skills.`);
+}
+
+function isAlreadyLinked(skillName) {
+  const skillFile = path.join(SKILLS_DIR, skillName, 'SKILL.md');
+  if (!fs.existsSync(skillFile)) return false;
+  const content = fs.readFileSync(skillFile, 'utf-8');
+  // If it has the Fractal header and mostly just links... 
+  // Simple check: does it have "Knowledge Modules (Fractal Skills)"?
+  return content.includes('Knowledge Modules (Fractal Skills)');
+}
+
+function processSkill(skillName) {
+  const skillDir = path.join(SKILLS_DIR, skillName);
+  const skillFile = path.join(skillDir, 'SKILL.md');
+  const subSkillsDir = path.join(skillDir, 'sub-skills');
+
+  if (!fs.existsSync(skillFile)) return;
+
+  const content = fs.readFileSync(skillFile, 'utf-8');
+  if (!content.includes('### ')) {
+     // No headers to split
+     return;
+  }
+
+  const sections = content.split(/^### /gm);
+  if (sections.length < 2) return;
+
+  if (!fs.existsSync(subSkillsDir)) {
+    fs.mkdirSync(subSkillsDir, { recursive: true });
+  }
+
+  // 1. Master Content (Header)
+  let masterContent = sections[0];
+  let modulesList = [];
+
+  // 2. Extract Sections
+  for (let i = 1; i < sections.length; i++) {
+    const rawSection = sections[i];
+    const firstLineEnd = rawSection.indexOf('\n');
+    let title = rawSection.substring(0, firstLineEnd).trim();
+    let body = rawSection.substring(firstLineEnd).trim();
+    
+    // Clean Title (remote [links] etc)
+    title = title.replace(/\[|\]/g, ''); 
+
+    if (!title) continue;
+
+    const fileName = slugify(title) + '.md';
+    const filePath = path.join(subSkillsDir, fileName);
+
+    // Only write if file doesn't exist (PREVENT OVERWRITE of moved resources)
+    if (!fs.existsSync(filePath)) {
+        const fileContent = `# ${title}\n\n${body}`;
+        fs.writeFileSync(filePath, fileContent);
+    }
+    
+    modulesList.push({ title, fileName });
+  }
+
+  // 3. Update SKILL.md
+  // Header + Links
+  let newMasterContent = masterContent.trim() + '\n\n';
+  newMasterContent += '## 🧠 Knowledge Modules (Fractal Skills)\n\n';
+  
+  modulesList.forEach((mod, idx) => {
+    newMasterContent += `### ${idx + 1}. [${mod.title}](./sub-skills/${mod.fileName})\n`;
+  });
+  
+  // Add Version tag if missing
+  if (!newMasterContent.includes('version:')) {
+      newMasterContent = newMasterContent.replace('---', `---\nversion: 4.1.0-fractal`);
+  }
+
+  fs.writeFileSync(skillFile, newMasterContent);
+  console.log(`fractalized: ${skillName}`);
+}
+
+main();