chore: bundle agent skills & add migration to copy into project (#16961)

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

Author: damyanpetev

.github/workflows/npm-publish.yml

@@ -41,10 +41,11 @@ jobs:
             if [[ ${VERSION} == *"alpha"* || ${VERSION} == *"beta"* || ${VERSION} == *"rc"* ]]; then echo "NPM_TAG=next"; else echo "NPM_TAG=latest"; fi >> $GITHUB_ENV
             echo ${NPM_TAG}
 
-      - name: Copy readme and license for igniteui-angular
+      - name: Copy readme, license & skills for igniteui-angular
         run: |
             cp ../../README.md README.md
             cp ../../LICENSE LICENSE
+            cp -r ../../skills/. skills
         working-directory: dist/igniteui-angular
 
       - name: Copy i18n files

CHANGELOG.md

@@ -53,11 +53,11 @@ All notable changes for each version of this project will be documented in this
     - Improved positioning accuracy for container-based overlays with fixed container bounds.
 
 - **AI-Assisted Development - Copilot Skills**
-    - Three consolidated Copilot Skills are now included in the repository to teach AI coding assistants (GitHub Copilot, Cursor, Windsurf, Claude, JetBrains AI, etc.) how to work with Ignite UI for Angular:
+    - Three consolidated Copilot Skills are now included in the repository to teach AI coding assistants/agents (e.g., GitHub Copilot, Cursor, Windsurf, Claude, JetBrains AI, etc.) how to work with Ignite UI for Angular:
         - **Components** - UI Components (form controls, layout, data display, feedback/overlays, directives — Input Group, Combo, Select, Date/Time Pickers, Calendar, Tabs, Stepper, Accordion, List, Card, Dialog, Snackbar, Button, Ripple, Tooltip, Drag and Drop, Layout Manager, Dock Manager and Charts (Area Chart, Bar Chart, Column Chart, Stock/Financial Chart, Pie Chart))
         - **Data Grids** - Data Grids (grid type selection, column config, sorting, filtering, selection, editing, grouping, paging, remote data, state persistence, Tree Grid, Hierarchical Grid, Grid Lite, Pivot Grid)
         - **Theming & Styling** - Theming & Styling (includes MCP server setup for live theming tools)
-    - These skills are automatically discovered by GitHub Copilot via `.github/copilot-instructions.md` and can be manually configured in other IDEs. For more information, see the [README](README.md#ai-assisted-development).
+    - These skills are automatically discovered when placed in the agent's skills path ( e.g. `.claude/skills`) and this release ships with an optional migration to add those to your project. For more information, see the [README](README.md#ai-assisted-development).
 
 ### General
 

projects/igniteui-angular/migrations/migration-collection.json

@@ -272,6 +272,13 @@
             "factory": "./update-21_1_0_css-migration",
             "recommended": true,
             "optional": true
+        },
+        "migration-54": {
+            "version": "21.1.0",
+            "description": "Add AI Agent skills for Ignite UI for Angular components and theming to the project.",
+            "factory": "./update-21_1_0_add-agent-skills",
+            "recommended": true,
+            "optional": true
         }
     }
 }

projects/igniteui-angular/migrations/update-21_1_0_add-agent-skills/index.spec.ts

@@ -0,0 +1,105 @@
+import * as path from 'path';
+
+import { SchematicTestRunner, UnitTestTree } from '@angular-devkit/schematics/testing';
+import { setupTestTree } from '../common/setup.spec';
+import { IG_LICENSED_PACKAGE_NAME, IG_PACKAGE_NAME } from '../common/tsUtils';
+
+describe(`Add Agent skills`, () => {
+    let appTree: UnitTestTree;
+    const schematicRunner = new SchematicTestRunner('ig-migrate', path.join(__dirname, '../migration-collection.json'));
+
+    beforeEach(() => {
+        appTree = setupTestTree();
+    });
+
+    const migrationName = 'migration-54';
+
+    const packagePath = `/node_modules/${IG_PACKAGE_NAME}`;
+    const licensedPackagePath = `/node_modules/${IG_LICENSED_PACKAGE_NAME}`;
+
+    const addPackageSkills = (tree: UnitTestTree, basePath: string, packageName = IG_PACKAGE_NAME) => {
+        tree.create(`${basePath}/package.json`, JSON.stringify({ name: packageName, version: '21.1.0' }));
+        tree.create(`${basePath}/skills/igniteui-angular-components/SKILL.md`, '# Components Skill');
+        tree.create(`${basePath}/skills/igniteui-angular-grids/SKILL.md`, '# Grids Skill');
+    };
+
+    it('should copy skill files to .claude/skills by default when no existing agent directories have content', async () => {
+        addPackageSkills(appTree, packagePath);
+
+        const tree = await schematicRunner.runSchematic(migrationName, {}, appTree);
+
+        expect(tree.exists('/.claude/skills/igniteui-angular-components/SKILL.md')).toBeTrue();
+        expect(tree.exists('/.claude/skills/igniteui-angular-grids/SKILL.md')).toBeTrue();
+    });
+
+    it('should copy skill files to .agents/skills when that directory already has content', async () => {
+        addPackageSkills(appTree, packagePath);
+        appTree.create('/.agents/skills/existing-skill/SKILL.md', '# Existing Skill');
+
+        const tree = await schematicRunner.runSchematic(migrationName, {}, appTree);
+
+        expect(tree.exists('/.agents/skills/igniteui-angular-components/SKILL.md')).toBeTrue();
+        expect(tree.exists('/.agents/skills/igniteui-angular-grids/SKILL.md')).toBeTrue();
+        expect(tree.exists('/.claude/skills/igniteui-angular-components/SKILL.md')).toBeFalse();
+    });
+
+    it('should copy skill files to .cursor/skills when that directory already has content', async () => {
+        addPackageSkills(appTree, packagePath);
+        appTree.create('/.cursor/skills/existing-skill/SKILL.md', '# Existing Skill');
+
+        const tree = await schematicRunner.runSchematic(migrationName, {}, appTree);
+
+        expect(tree.exists('/.cursor/skills/igniteui-angular-components/SKILL.md')).toBeTrue();
+        expect(tree.exists('/.cursor/skills/igniteui-angular-grids/SKILL.md')).toBeTrue();
+        expect(tree.exists('/.claude/skills/igniteui-angular-components/SKILL.md')).toBeFalse();
+    });
+
+    it('should copy skill files to .github/skills when that directory already has content', async () => {
+        addPackageSkills(appTree, packagePath);
+        appTree.create('/.github/skills/existing-skill/SKILL.md', '# Existing Skill');
+
+        const tree = await schematicRunner.runSchematic(migrationName, {}, appTree);
+
+        expect(tree.exists('/.github/skills/igniteui-angular-components/SKILL.md')).toBeTrue();
+        expect(tree.exists('/.github/skills/igniteui-angular-grids/SKILL.md')).toBeTrue();
+        expect(tree.exists('/.claude/skills/igniteui-angular-components/SKILL.md')).toBeFalse();
+    });
+
+    it('should use the licensed package skills when only the licensed package is installed', async () => {
+        addPackageSkills(appTree, licensedPackagePath, IG_LICENSED_PACKAGE_NAME);
+
+        const tree = await schematicRunner.runSchematic(migrationName, {}, appTree);
+
+        expect(tree.exists('/.claude/skills/igniteui-angular-components/SKILL.md')).toBeTrue();
+    });
+
+    it('should not create any skill files when neither package is installed', async () => {
+        const tree = await schematicRunner.runSchematic(migrationName, {}, appTree);
+
+        expect(tree.exists('/.claude/skills/igniteui-angular-components/SKILL.md')).toBeFalse();
+        expect(tree.exists('/.agents/skills/igniteui-angular-components/SKILL.md')).toBeFalse();
+        expect(tree.exists('/.cursor/skills/igniteui-angular-components/SKILL.md')).toBeFalse();
+    });
+
+    it('should overwrite existing skill files when re-running the migration', async () => {
+        addPackageSkills(appTree, packagePath);
+        appTree.create('/.claude/skills/igniteui-angular-components/SKILL.md', '# Old Content');
+
+        const tree = await schematicRunner.runSchematic(migrationName, {}, appTree);
+
+        expect(tree.readContent('/.claude/skills/igniteui-angular-components/SKILL.md')).toBe('# Components Skill');
+    });
+
+    it('should preserve content of all skill files during copy', async () => {
+        const componentsContent = '# Components Skill\nSome detailed content here.';
+        const gridsContent = '# Grids Skill\nGrid-specific instructions.';
+        appTree.create(`${packagePath}/package.json`, JSON.stringify({ name: IG_PACKAGE_NAME, version: '21.1.0' }));
+        appTree.create(`${packagePath}/skills/igniteui-angular-components/SKILL.md`, componentsContent);
+        appTree.create(`${packagePath}/skills/igniteui-angular-grids/SKILL.md`, gridsContent);
+
+        const tree = await schematicRunner.runSchematic(migrationName, {}, appTree);
+
+        expect(tree.readContent('/.claude/skills/igniteui-angular-components/SKILL.md')).toBe(componentsContent);
+        expect(tree.readContent('/.claude/skills/igniteui-angular-grids/SKILL.md')).toBe(gridsContent);
+    });
+});

projects/igniteui-angular/migrations/update-21_1_0_add-agent-skills/index.ts

@@ -0,0 +1,52 @@
+import { normalize, type Path, relative } from '@angular-devkit/core';
+import {
+    apply,
+    MergeStrategy,
+    mergeWith,
+    move,
+    type Rule,
+    type SchematicContext,
+    type Source,
+    Tree
+} from '@angular-devkit/schematics';
+import { IG_LICENSED_PACKAGE_NAME, IG_PACKAGE_NAME } from '../common/tsUtils';
+
+export default (): Rule => async (host: Tree, context: SchematicContext) => {
+    let skillsPath = normalize(`.claude/skills`);
+    const agentsPath = normalize(`.agents/skills`);
+    const cursorSkills = normalize(`.cursor/skills`);
+    const githubSkills = normalize(`.github/skills`);
+
+    if (host.getDir(agentsPath).subdirs.length)
+        skillsPath = agentsPath;
+    if (host.getDir(cursorSkills).subdirs.length)
+        skillsPath = cursorSkills;
+    if (host.getDir(githubSkills).subdirs.length)
+        skillsPath = githubSkills;
+
+    let from: Path | undefined;
+    const packagePath = `/node_modules/${IG_PACKAGE_NAME}`;
+    const licensedPackagePath = `/node_modules/${IG_LICENSED_PACKAGE_NAME}`;
+
+    // exists works on files only, so check package.json
+    if (host.exists(`${packagePath}/package.json`))
+        from = normalize(`${packagePath}/skills`);
+
+    if (host.exists(`${licensedPackagePath}/package.json`))
+        from = normalize(`${licensedPackagePath}/skills`);
+
+    if (from) {
+        const skillsSource: Source = () => {
+            const tree = Tree.empty();
+            host.getDir(from).visit((filePath) => {
+                tree.create(relative(from, filePath), host.read(filePath));
+            });
+            return tree;
+        };
+
+        context.logger.info(`Added Ignite UI for Angular agent skill files to ${skillsPath}.`);
+        context.logger.info(`If your agent doesn't load from that path by default, please refer to its documentation and move the skill files as needed.`);
+
+        return mergeWith(apply(skillsSource, [move(skillsPath)]), MergeStrategy.Overwrite);
+    }
+};