refactor(skills): reorganize skills under .agents

.agents/context/project.md

@@ -0,0 +1,54 @@
+# Project Context
+
+Concise context for ACS-aware tools. The full rules live in the
+[Coding Guidelines](../../.github/CODING_GUIDELINES.md) and their summary in
+[`.github/copilot-instructions.md`](../../.github/copilot-instructions.md).
+Read them before making changes; if they disagree with this file, they win.
+
+## Stack
+
+- Language: TypeScript (strict), ESM with `.js` import extensions
+- Framework: Lit 3 custom elements with Shadow DOM, `@lit/context` for shared state
+- Positioning: `@floating-ui/dom`; localization: `igniteui-i18n-core`
+- Styles: SCSS compiled to generated `.css.ts` files, themes from `igniteui-theming`
+- Tests: Web Test Runner + Playwright, `@open-wc/testing`, mandatory a11y audits
+- Docs and demos: Storybook, Custom Elements Manifest, TypeDoc
+- Tooling: oxlint, oxfmt, stylelint, lit-analyzer, dependency-cruiser
+
+## Architecture
+
+- `src/components/[name]/`: one directory per component, with `[name].ts`, `[name].spec.ts`,
+  a `spec.md` behavioral contract and, when themed, its SCSS under `themes/`
+- `src/internals/`, `src/theming/`, `src/animations/`: shared code, imported only through the
+  `#internals/*`, `#theming/*` and `#animations/*` aliases
+- `src/extras/`: opt-in add-ons, published as `igniteui-webcomponents/extras`
+- `src/styles/`: global SCSS utilities, mixins and themes
+- `src/index.ts`: the public entry point of the package
+- `stories/`: Storybook stories, one per component tag
+- `scripts/`: build, styles, stories, typedoc and changelog scripts; `scripts/_package.json`
+  is the published manifest
+- `skills/`: public, user-facing skills that ship with the package
+- `.agents/`: contributor-facing skills and this context
+
+## Workflow
+
+Read the component's `spec.md` first and update it in the same change. Use the contributor
+skills instead of guessing (see [`.agents/skills/`](../skills/README.md)):
+
+- New component: [create-new-component](../skills/create-new-component/SKILL.md)
+- New property: [add-component-property](../skills/add-component-property/SKILL.md)
+- SCSS and themes: [update-component-styles](../skills/update-component-styles/SKILL.md)
+- Reviews: [review-component-pr](../skills/review-component-pr/SKILL.md)
+- Skills: [skill-authoring](../skills/skill-authoring/SKILL.md)
+
+Before finishing, run `npm run check`, `npm run lint` and `npm run test`. For a new
+component or a bug fix, update `CHANGELOG.md`.
+
+## Do not change without explicit instruction
+
+- `tsconfig*.json` compiler options (strict mode is required)
+- `package-lock.json` or new runtime dependencies; prefer native platform features
+- Public API names, tag names, events or CSS parts without a deprecation plan
+- Generated output: `src/**/*.css.ts`, the `// region default` block of stories,
+  `custom-elements.json`, `dist/`
+- A new import alias goes into both `package.json` and `scripts/_package.json`, never one only

.agents/main.yaml

@@ -0,0 +1,30 @@
+# Agentic Collaboration Standard (ACS) manifest.
+# Spec: https://github.com/jackby03/agentic-collaboration-standard/tree/main/spec/v1
+# Schema: https://raw.githubusercontent.com/jackby03/agentic-collaboration-standard/main/schemas/v1/manifest.schema.json
+#
+# .github/CODING_GUIDELINES.md holds the full coding rules and
+# .github/copilot-instructions.md their summary. Both win over this folder.
+# The skills in .agents/skills/ are for contributors to this repository. The
+# end-user skills that ship with the package live in skills/ at the root.
+
+version: '1.0'
+
+project:
+  name: 'igniteui-webcomponents'
+  description: 'Ignite UI for Web Components: a library of accessible, themable UI components (inputs, date pickers, navigation, layout, chat and more) built with Lit and TypeScript and usable in any web framework.'
+  language: typescript
+  framework: lit
+
+layers:
+  context: true # context/project.md
+  skills: true # .agents/skills/ (contributor workflows)
+  commands: false # no reusable single-shot commands defined yet
+  agents: false # no custom agents defined yet
+  permissions: true # permissions/policy.yaml
+
+compatible_with:
+  - github-copilot
+  - claude-code
+  - cursor
+  - codex
+  - any

.agents/permissions/policy.yaml

@@ -0,0 +1,43 @@
+# ACS Permission Policy v1.0
+# Spec: https://github.com/jackby03/agentic-collaboration-standard/blob/main/spec/v1/08-permissions.md
+#
+# Evaluation order: deny rules first, then allow rules, then default deny.
+# Mirrors the rules in .github/CODING_GUIDELINES.md. package.json stays writable
+# because a new import alias must be added to it (and to scripts/_package.json);
+# lock files and build output are denied.
+
+deny:
+  read:
+    - '.env'
+    - '.env.*'
+    - '.envrc'
+    - '**/.envrc'
+    - '**/.env'
+    - '**/.env.*'
+    - '*.pem'
+    - '**/*.pem'
+    - '*.key'
+    - '**/*.key'
+    - '*.pfx'
+    - '**/*.pfx'
+    - '.npmrc'
+    - '**/.npmrc'
+  write:
+    - '.git/**'
+    - 'node_modules/**'
+    - 'dist/**'
+    - 'coverage/**'
+    - 'storybook-static/**'
+    - 'src/**/*.css.ts'
+    - 'custom-elements.json'
+    - 'vscode-html-custom-data.json'
+    - 'package-lock.json'
+    - '**/package-lock.json'
+    - '**/yarn.lock'
+    - '**/pnpm-lock.yaml'
+
+allow:
+  read:
+    - '**'
+  write:
+    - '**'

.github/skills/README.md → .agents/skills/README.md

@@ -2,7 +2,7 @@
 
 Workflows for contributors to this repository. End-user skills live in [`skills/`](../../skills/).
 
-- The rules live in the [Coding Guidelines](../CODING_GUIDELINES.md). A skill says in what
+- The rules live in the [Coding Guidelines](../../.github/CODING_GUIDELINES.md). A skill says in what
   order to apply them. When a skill and the guidelines disagree, the guidelines win and the
   skill needs a fix.
 - The behavior of a component lives in its `src/components/[name]/spec.md`. Read it before
@@ -16,6 +16,7 @@ Workflows for contributors to this repository. End-user skills live in [`skills/
 | [add-component-property](./add-component-property/)   | Adding a reactive property to a component  |
 | [update-component-styles](./update-component-styles/) | Changing the SCSS or themes of a component |
 | [review-component-pr](./review-component-pr/)         | Reviewing a component pull request         |
+| [skill-authoring](./skill-authoring/)                 | Writing or updating a skill                |
 
 Reference a skill by name: "Follow the create-new-component skill to add a progress-bar
 component."
@@ -25,9 +26,14 @@ component."
 Skills use the
 [VS Code agent skills format](https://code.visualstudio.com/docs/copilot/customization/agent-skills):
 
-1. Create `.github/skills/[skill-name]/SKILL.md`. The directory name is kebab-case.
-2. Add frontmatter with `name` (same as the directory) and `description`. Optional keys:
-   `user-invokable`, `argument-hint`, `compatibility`, `disable-model-invocation`, `license`,
-   `metadata`.
+Follow the [skill-authoring](./skill-authoring/SKILL.md) skill for the frontmatter rules, the
+description format and the size budget. In short:
+
+1. Create `.agents/skills/[skill-name]/SKILL.md`. The directory name is kebab-case and
+   matches `name`.
+2. Add frontmatter with `license`, `name` and `description`. The description has
+   `WHEN TO USE:` and `WHEN NOT TO USE:` markers. Optional keys: `user-invocable`,
+   `argument-hint`, `compatibility`, `disable-model-invocation`, `metadata`.
 3. Link to the guidelines for rules. Do not copy them.
-4. Add the skill to the table above.
+4. Add the skill to the table above and to the Workflow section of
+   [`.agents/context/project.md`](../context/project.md).

.github/skills/add-component-property/SKILL.md → .agents/skills/add-component-property/SKILL.md

@@ -6,8 +6,8 @@ description: Add a reactive property to an existing Lit web component with prope
 # Add Component Property
 
 Adds a reactive property together with its JSDoc, tests, spec update and generated metadata.
-The rules are in [Properties and Attributes](../../CODING_GUIDELINES.md#properties-and-attributes)
-and [API Documentation](../../CODING_GUIDELINES.md#api-documentation).
+The rules are in [Properties and Attributes](../../../.github/CODING_GUIDELINES.md#properties-and-attributes)
+and [API Documentation](../../../.github/CODING_GUIDELINES.md#api-documentation).
 
 Related: [create-new-component](../create-new-component/),
 [update-component-styles](../update-component-styles/).
@@ -118,7 +118,7 @@ separate one.
 ### 5. Update the specification
 
 A new property changes the public API, so it also changes `src/components/[name]/spec.md`.
-Use [Keeping it current](../../CODING_GUIDELINES.md#keeping-it-current):
+Use [Keeping it current](../../../.github/CODING_GUIDELINES.md#keeping-it-current):
 
 - Add a row to `### Properties and attributes` with the name, attribute, reflects, type, default,
   and the same description as the JSDoc.

.github/skills/create-new-component/SKILL.md → .agents/skills/create-new-component/SKILL.md

@@ -6,7 +6,7 @@ description: Create a new Lit web component following project conventions, inclu
 # Create New Component
 
 Scaffolds a component. The rules behind each step are in the
-[Coding Guidelines](../../CODING_GUIDELINES.md).
+[Coding Guidelines](../../../.github/CODING_GUIDELINES.md).
 
 Related: [add-component-property](../add-component-property/),
 [update-component-styles](../update-component-styles/).
@@ -26,7 +26,7 @@ Confirm with the user before you start:
 
 Write `src/components/[name]/spec.md` first. It decides the public API, the keyboard model and
 the ARIA semantics. Copy the structure of `src/components/splitter/spec.md` and follow
-[Specifications](../../CODING_GUIDELINES.md#specifications): one spec per directory, a
+[Specifications](../../../.github/CODING_GUIDELINES.md#specifications): one spec per directory, a
 hand-maintained table of contents, a revision history that starts at version 1, and no
 ownership sections. Fill in `## Test scenarios` in step 6.
 
@@ -95,18 +95,18 @@ declare global {
 ```
 
 - Pass every component that the template renders to `registerComponent(Self, ...deps)`.
-- Follow the [region layout](../../CODING_GUIDELINES.md#components) and the
-  [import rules](../../CODING_GUIDELINES.md#imports).
+- Follow the [region layout](../../../.github/CODING_GUIDELINES.md#components) and the
+  [import rules](../../../.github/CODING_GUIDELINES.md#imports).
 - Before you write lifecycle code, look for a controller in the
-  [controllers table](../../CODING_GUIDELINES.md#controllers) or in `src/internals`. Examples:
+  [controllers table](../../../.github/CODING_GUIDELINES.md#controllers) or in `src/internals`. Examples:
   `addRovingFocusController`, `addToggleController`, `addHostListeners`, and the `resizable()` /
   `draggable()` directives.
 - Write JSDoc as product documentation. See
-  [API Documentation](../../CODING_GUIDELINES.md#api-documentation).
+  [API Documentation](../../../.github/CODING_GUIDELINES.md#api-documentation).
 
 ### 3. Create the SCSS files
 
-The layout is in [Styles and Theming](../../CODING_GUIDELINES.md#styles-and-theming).
+The layout is in [Styles and Theming](../../../.github/CODING_GUIDELINES.md#styles-and-theming).
 `src/components/badge/themes/` is a complete example. Use 4-space indentation and load-path
 specifiers.
 
@@ -262,7 +262,7 @@ describe('[Name]', () => {
 ```
 
 Use the shared helpers in `#internals/testing/` for interaction and forms (see
-[Testing](../../CODING_GUIDELINES.md#testing)). Do not import one component spec from another,
+[Testing](../../../.github/CODING_GUIDELINES.md#testing)). Do not import one component spec from another,
 because that runs the imported suite again.
 
 Then fill in the `## Test scenarios` section of the spec: one subsection per `describe` block,
@@ -272,7 +272,7 @@ that the suite does not test under `### Not covered by the suite`.
 ### 7. Create the Storybook story
 
 Create `stories/[name].stories.ts`. The filename must match the tag name. See
-[Storybook](../../CODING_GUIDELINES.md#storybook) for the full template.
+[Storybook](../../../.github/CODING_GUIDELINES.md#storybook) for the full template.
 
 ```ts
 import type { Meta, StoryObj } from '@storybook/web-components-vite';

.github/skills/review-component-pr/SKILL.md → .agents/skills/review-component-pr/SKILL.md

@@ -5,7 +5,7 @@ description: Code review checklist for component pull requests covering structur
 
 # Review Component PR
 
-A checklist to use on a diff. The rules are in the [Coding Guidelines](../../CODING_GUIDELINES.md).
+A checklist to use on a diff. The rules are in the [Coding Guidelines](../../../.github/CODING_GUIDELINES.md).
 Read the `spec.md` of the component before the diff. A change that contradicts the spec is a
 bug, or the author must also update the spec.
 
@@ -19,7 +19,7 @@ Review in this order. The public API is hard to change after release, so review
 - [ ] Complete theme scaffold, with every file in `themes.ts`
 - [ ] Exported from `src/index.ts` in alphabetical order. No new exports from
       `src/internals` beyond the approved list in
-      [Project Structure](../../CODING_GUIDELINES.md#project-structure).
+      [Project Structure](../../../.github/CODING_GUIDELINES.md#project-structure).
 - [ ] `#internals` / `#theming` / `#animations` aliases for cross-cutting imports. Relative
       imports between components. `.js` specifiers.
 - [ ] A new alias is in `package.json` **and** in `scripts/_package.json`
@@ -47,7 +47,7 @@ grep -rn "igc-" --include="*.ts" src/ \
 ## 3. Specification
 
 Map each change to a spec section with
-[Keeping it current](../../CODING_GUIDELINES.md#keeping-it-current).
+[Keeping it current](../../../.github/CODING_GUIDELINES.md#keeping-it-current).
 
 - [ ] A new component has a `spec.md` in the splitter structure
 - [ ] API tables match the JSDoc for each added, renamed, deprecated or removed member

.agents/skills/skill-authoring/SKILL.md

@@ -0,0 +1,51 @@
+---
+license: MIT
+name: skill-authoring
+description: "Provides rules for writing or updating a SKILL.md in this repository: frontmatter validation for license, name and description, the WHEN TO USE and WHEN NOT TO USE description format, and the 500-line body budget with progressive disclosure into reference files. WHEN TO USE: creating a new skill under .agents/skills/ or skills/, or editing an existing skill's frontmatter, scope, or length. WHEN NOT TO USE: writing component code, styles, or tests (use create-new-component, add-component-property, or update-component-styles), reviewing a component pull request (use review-component-pr), or changing the coding rules themselves (edit .github/CODING_GUIDELINES.md)."
+user-invocable: true
+---
+
+# Ignite UI for Web Components — Skill Authoring
+
+Quick-reference for writing a `SKILL.md` that agents can discover and load reliably.
+
+## Location
+
+- Internal, contributor-facing skills: `.agents/skills/<name>/SKILL.md`
+- Public skills that ship with the package: `skills/<name>/SKILL.md`
+- The folder name must match the `name` field.
+
+## Frontmatter
+
+| Field | Rules |
+|---|---|
+| `license` | Required. Must specify the license under which the skill is released. Default is MIT. |
+| `name` | Required. Max 64 characters. Lowercase letters, numbers, and hyphens only. No XML tags. No reserved words (`anthropic`, `claude`). Public skills use the `igniteui-wc-` prefix; internal skills use a plain kebab-case name. |
+| `description` | Required. Non-empty. Max 1,024 characters. No XML tags. |
+
+Write the description in the third person: say what the skill covers, then add both markers:
+
+- `WHEN TO USE:` the tasks or triggers that should load the skill.
+- `WHEN NOT TO USE:` nearby tasks it does not cover, naming the skill to use instead.
+
+Agents see only `name` and `description` until they load the skill, so the description decides whether it is ever used.
+
+## Token Budget
+
+- Keep the `SKILL.md` body under 500 lines.
+- If it grows past that, use progressive disclosure: keep the overview and core rules in `SKILL.md` and move detail into `references/<topic>.md` files.
+- Link each reference file directly from `SKILL.md` (one level deep) and say when to read it, so agents load it only when needed.
+
+## Checklist
+
+1. Frontmatter passes the rules above.
+2. The description includes `WHEN TO USE:` and `WHEN NOT TO USE:`.
+3. The body is under 500 lines, and every reference file is linked from `SKILL.md`.
+4. The skill is listed in the Skills table of its README: [.agents/skills/README.md](../README.md) for internal skills, [skills/README.md](../../../skills/README.md) for public skills. Internal skills are also listed in the Workflow section of [.agents/context/project.md](../../context/project.md).
+
+## Related Skills
+
+- [`create-new-component`](../create-new-component/SKILL.md) — Scaffolding a new component
+- [`add-component-property`](../add-component-property/SKILL.md) — Adding a reactive property
+- [`update-component-styles`](../update-component-styles/SKILL.md) — Changing SCSS or themes
+- [`review-component-pr`](../review-component-pr/SKILL.md) — Reviewing a component pull request

.github/skills/update-component-styles/SKILL.md → .agents/skills/update-component-styles/SKILL.md

@@ -7,7 +7,7 @@ description: Update component styling following the SCSS to Lit CSS workflow wit
 
 Changes component styles through the SCSS → Lit CSS build and the `igniteui-theming` schemas.
 The directory layout and rules are in
-[Styles and Theming](../../CODING_GUIDELINES.md#styles-and-theming).
+[Styles and Theming](../../../.github/CODING_GUIDELINES.md#styles-and-theming).
 
 Related: [create-new-component](../create-new-component/) for a new theme scaffold.
 
@@ -60,7 +60,7 @@ $theme: $bootstrap;
 - Keep specificity low. Document the custom properties that consumers can set, and prefix
   internal ones with `--_`.
 - Key composite-anchor selectors off `data-role` / `data-haspopup`, not `role` / `aria-*`
-  (see [ARIA across shadow boundaries](../../CODING_GUIDELINES.md#aria-across-shadow-boundaries)).
+  (see [ARIA across shadow boundaries](../../../.github/CODING_GUIDELINES.md#aria-across-shadow-boundaries)).
 - `var-get()` resolves only keys that are in the schema. For a new key, add it to
   `igniteui-theming`, or declare a local variable in `shared/[component].common.scss`.
 

.github/CODING_GUIDELINES.md

@@ -1079,7 +1079,7 @@ For a new component or a bug fix, update the
 - [README.md](https://github.com/IgniteUI/igniteui-webcomponents/blob/master/README.md)
 - Component specifications: `src/components/[component]/spec.md`, with the
   [splitter](../src/components/splitter/spec.md) as the reference
-- [LLM Skills](./skills/README.md) for guided workflows
+- [LLM Skills](../.agents/skills/README.md) for guided workflows
 - [Lit](https://lit.dev/docs/), [MDN Web Components](https://developer.mozilla.org/en-US/docs/Web/Web_Components),
   [WCAG](https://www.w3.org/WAI/WCAG21/quickref/),
   [TypeScript Handbook](https://www.typescriptlang.org/docs/handbook/intro.html)

.github/copilot-instructions.md

@@ -72,7 +72,7 @@ structural reference.
 ## Resources
 
 - [Coding Guidelines](CODING_GUIDELINES.md): the full rules
-- [Skills](skills/): workflows to create components, add properties, update styles and review
-  PRs
+- [Skills](../.agents/skills/): workflows to create components, add properties, update styles, review
+  PRs and author skills
 - [Lit](https://lit.dev/docs/), [Lit context](https://lit.dev/docs/data/context/),
   [MDN Web Components](https://developer.mozilla.org/en-US/docs/Web/Web_Components)

skills/README.md

@@ -57,9 +57,6 @@ If you identify gaps in the skills or have suggestions for improvements:
 
 1. [Open an issue](https://github.com/IgniteUI/igniteui-webcomponents/issues) describing the improvement
 2. Submit a pull request with the proposed changes
-3. Follow the skill format and structure of existing skills
-
-For skills related to **contributing to the library itself** (creating components, reviewing PRs, etc.), see [`.github/skills/`](../.github/skills/).
 
 ## Additional Resources