angular-agents-skills 1.0.0

package/dist/src/cli.js

@@ -0,0 +1,293 @@
+import { readFileSync, writeFileSync, mkdirSync, existsSync, readdirSync, statSync } from 'node:fs';
+import { resolve, join, dirname } from 'node:path';
+import { parse as parseYaml } from 'yaml';
+import { registerAdapter, getAdapter, listAdapters, hasAdapter } from './registry.js';
+import { createOpenCodeAdapter } from '../adapters/opencode/index.js';
+import { createClaudeAdapter } from '../adapters/claude/index.js';
+import { createCodexAdapter } from '../adapters/codex/index.js';
+import { createCursorAdapter } from '../adapters/cursor/index.js';
+import { createCopilotAdapter } from '../adapters/copilot/index.js';
+registerAdapter(createOpenCodeAdapter());
+registerAdapter(createClaudeAdapter());
+registerAdapter(createCodexAdapter());
+registerAdapter(createCursorAdapter());
+registerAdapter(createCopilotAdapter());
+function loadAgent(agentName, agentsDir) {
+    const agentPath = join(agentsDir, agentName);
+    if (!existsSync(agentPath)) {
+        throw new Error(`Agent "${agentName}" not found at ${agentPath}`);
+    }
+    const mdPath = join(agentPath, 'agent.md');
+    if (!existsSync(mdPath)) {
+        throw new Error(`Agent "${agentName}" missing agent.md at ${mdPath}`);
+    }
+    const mdContent = readFileSync(mdPath, 'utf-8');
+    const name = agentName;
+    const description = mdContent.split('\n')[0]?.replace(/^#\s+/, '') || agentName;
+    return {
+        metadata: { name, description },
+        instructions: { content: mdContent },
+        basePath: agentPath,
+    };
+}
+function loadAgentConfig(agentName, ai, agentsDir) {
+    const configPath = join(agentsDir, agentName, 'configs', `${ai}.yaml`);
+    if (!existsSync(configPath)) {
+        return undefined;
+    }
+    const configContent = readFileSync(configPath, 'utf-8');
+    return parseYaml(configContent);
+}
+function loadSkill(skillName, skillsDir) {
+    const skillPath = findSkillPath(skillName, skillsDir);
+    if (!skillPath) {
+        throw new Error(`Skill "${skillName}" not found at ${skillsDir}`);
+    }
+    const mdContent = readFileSync(join(skillPath, 'SKILL.md'), 'utf-8');
+    const parsed = parseYaml(mdContent.split('---')[1] || '');
+    return {
+        content: mdContent,
+        metadata: parsed || {},
+    };
+}
+function findSkillPath(skillName, skillsDir) {
+    if (!existsSync(skillsDir)) {
+        return null;
+    }
+    const categories = readdirSync(skillsDir).filter((entry) => {
+        return statSync(join(skillsDir, entry)).isDirectory();
+    });
+    for (const category of categories) {
+        const categoryPath = join(skillsDir, category);
+        const skills = readdirSync(categoryPath).filter((entry) => {
+            return statSync(join(categoryPath, entry)).isDirectory();
+        });
+        for (const skill of skills) {
+            if (skill === skillName) {
+                return join(categoryPath, skill);
+            }
+        }
+    }
+    return null;
+}
+function listAgents(agentsDir) {
+    if (!existsSync(agentsDir)) {
+        return [];
+    }
+    return readdirSync(agentsDir).filter((entry) => {
+        const entryPath = join(agentsDir, entry);
+        return statSync(entryPath).isDirectory() && existsSync(join(entryPath, 'agent.md'));
+    });
+}
+function listSkills(skillsDir) {
+    if (!existsSync(skillsDir)) {
+        return [];
+    }
+    const skills = [];
+    const categories = readdirSync(skillsDir).filter((entry) => {
+        return statSync(join(skillsDir, entry)).isDirectory();
+    });
+    for (const category of categories) {
+        const categoryPath = join(skillsDir, category);
+        const categorySkills = readdirSync(categoryPath).filter((entry) => {
+            const skillPath = join(categoryPath, entry);
+            return statSync(skillPath).isDirectory() && existsSync(join(skillPath, 'SKILL.md'));
+        });
+        for (const skill of categorySkills) {
+            skills.push(skill);
+        }
+    }
+    return skills;
+}
+function installAgent(agentName, ai, agentsDir, targetDir) {
+    const adapter = getAdapter(ai);
+    if (!adapter) {
+        const available = listAdapters().join(', ');
+        throw new Error(`Unknown AI "${ai}". Available: ${available}`);
+    }
+    const agent = loadAgent(agentName, agentsDir);
+    const config = loadAgentConfig(agentName, ai, agentsDir);
+    const output = adapter.generate(agent, config);
+    const installPath = adapter.getInstallPath(agentName, targetDir);
+    const dir = dirname(installPath);
+    mkdirSync(dir, { recursive: true });
+    writeFileSync(installPath, output.content, 'utf-8');
+    console.log(`Installed agent "${agentName}" for ${adapter.name} → ${installPath}`);
+}
+function installAgentAll(agentName, agentsDir, targetDir) {
+    for (const aiName of listAdapters()) {
+        const adapter = getAdapter(aiName);
+        const base = targetDir || adapter.defaultDir;
+        const aiTarget = join(base, aiName);
+        installAgent(agentName, aiName, agentsDir, aiTarget);
+    }
+}
+function installSkill(skillName, ai, skillsDir, targetDir) {
+    const adapter = getAdapter(ai);
+    if (!adapter) {
+        const available = listAdapters().join(', ');
+        throw new Error(`Unknown AI "${ai}". Available: ${available}`);
+    }
+    const skill = loadSkill(skillName, skillsDir);
+    const filename = `${skillName}.md`;
+    const base = targetDir || join(adapter.defaultDir, 'skills');
+    const installPath = join(base, filename);
+    const dir = dirname(installPath);
+    mkdirSync(dir, { recursive: true });
+    writeFileSync(installPath, skill.content, 'utf-8');
+    console.log(`Installed skill "${skillName}" for ${adapter.name} → ${installPath}`);
+}
+function installSkillAll(skillName, skillsDir, targetDir) {
+    for (const aiName of listAdapters()) {
+        const adapter = getAdapter(aiName);
+        const base = targetDir || join(adapter.defaultDir, 'skills');
+        const aiTarget = join(base, aiName);
+        installSkill(skillName, aiName, skillsDir, aiTarget);
+    }
+}
+function printHelp() {
+    console.log(`
+angular-ai — Install Angular agents and skills for AI coding tools
+
+Usage:
+  npx angular-ai agent <name> --ai <tool> [--target <path>]
+  npx angular-ai agent <name> --all [--target <path>]
+  npx angular-ai skill <name> --ai <tool> [--target <path>]
+  npx angular-ai skill <name> --all [--target <path>]
+  npx angular-ai list agents
+  npx angular-ai list skills
+  npx angular-ai list adapters
+
+Options:
+  --ai <tool>        Target AI tool: ${listAdapters().join(', ')}
+  --all              Install for all available AI tools
+  --target <path>    Custom target directory
+
+Examples:
+  npx angular-ai agent angular-architect --ai opencode
+  npx angular-ai skill standalone-component-library --ai claude
+  npx angular-ai agent angular-architect --ai opencode --target ./my-agents
+  npx angular-ai skill signals-state-management --all
+`);
+}
+function main() {
+    const args = process.argv.slice(2);
+    if (args.length === 0 || args.includes('--help') || args.includes('-h')) {
+        printHelp();
+        return;
+    }
+    const command = args[0];
+    if (command === 'list') {
+        const type = args[1];
+        if (type === 'agents') {
+            const agents = listAgents(resolve('agents'));
+            if (agents.length === 0) {
+                console.log('No agents found.');
+            }
+            else {
+                console.log('Available agents:');
+                for (const agent of agents) {
+                    console.log(`  - ${agent}`);
+                }
+            }
+            return;
+        }
+        if (type === 'skills') {
+            const skills = listSkills(resolve('skills'));
+            if (skills.length === 0) {
+                console.log('No skills found.');
+            }
+            else {
+                console.log('Available skills:');
+                for (const skill of skills) {
+                    console.log(`  - ${skill}`);
+                }
+            }
+            return;
+        }
+        if (type === 'adapters') {
+            console.log('Available adapters:');
+            for (const name of listAdapters()) {
+                const adapter = getAdapter(name);
+                console.log(`  - ${name}: ${adapter.description}`);
+            }
+            return;
+        }
+        console.error(`Unknown list type: ${type}. Use "agents", "skills", or "adapters".`);
+        process.exit(1);
+    }
+    if (command === 'agent') {
+        const agentName = args[1];
+        if (!agentName) {
+            console.error('Error: agent name is required.');
+            process.exit(1);
+        }
+        const aiIndex = args.indexOf('--ai');
+        const allFlag = args.includes('--all');
+        const targetIndex = args.indexOf('--target');
+        const targetDir = targetIndex !== -1 ? args[targetIndex + 1] : undefined;
+        const agentsDir = resolve('agents');
+        if (!allFlag && aiIndex === -1) {
+            console.error('Error: specify --ai <tool> or --all');
+            process.exit(1);
+        }
+        try {
+            if (allFlag) {
+                installAgentAll(agentName, agentsDir, targetDir);
+            }
+            else {
+                const ai = args[aiIndex + 1];
+                if (!ai) {
+                    console.error('Error: --ai requires a value');
+                    process.exit(1);
+                }
+                installAgent(agentName, ai, agentsDir, targetDir);
+            }
+        }
+        catch (err) {
+            console.error(`Error: ${err.message}`);
+            process.exit(1);
+        }
+        return;
+    }
+    if (command === 'skill') {
+        const skillName = args[1];
+        if (!skillName) {
+            console.error('Error: skill name is required.');
+            process.exit(1);
+        }
+        const aiIndex = args.indexOf('--ai');
+        const allFlag = args.includes('--all');
+        const targetIndex = args.indexOf('--target');
+        const targetDir = targetIndex !== -1 ? args[targetIndex + 1] : undefined;
+        const skillsDir = resolve('skills');
+        if (!allFlag && aiIndex === -1) {
+            console.error('Error: specify --ai <tool> or --all');
+            process.exit(1);
+        }
+        try {
+            if (allFlag) {
+                installSkillAll(skillName, skillsDir, targetDir);
+            }
+            else {
+                const ai = args[aiIndex + 1];
+                if (!ai) {
+                    console.error('Error: --ai requires a value');
+                    process.exit(1);
+                }
+                installSkill(skillName, ai, skillsDir, targetDir);
+            }
+        }
+        catch (err) {
+            console.error(`Error: ${err.message}`);
+            process.exit(1);
+        }
+        return;
+    }
+    console.error(`Unknown command: ${command}`);
+    printHelp();
+    process.exit(1);
+}
+main();
+export { loadAgent, loadAgentConfig, loadSkill, listAgents, listSkills, installAgent, installAgentAll, installSkill, installSkillAll };
+export { registerAdapter, getAdapter, listAdapters, hasAdapter };

package/dist/src/index.js

@@ -0,0 +1,6 @@
+export { registerAdapter, getAdapter, listAdapters, hasAdapter } from './registry.js';
+export { createOpenCodeAdapter } from '../adapters/opencode/index.js';
+export { createClaudeAdapter } from '../adapters/claude/index.js';
+export { createCodexAdapter } from '../adapters/codex/index.js';
+export { createCursorAdapter } from '../adapters/cursor/index.js';
+export { createCopilotAdapter } from '../adapters/copilot/index.js';

package/dist/src/registry.js

@@ -0,0 +1,13 @@
+const adapters = new Map();
+export function registerAdapter(adapter) {
+    adapters.set(adapter.name, adapter);
+}
+export function getAdapter(name) {
+    return adapters.get(name);
+}
+export function listAdapters() {
+    return Array.from(adapters.keys());
+}
+export function hasAdapter(name) {
+    return adapters.has(name);
+}

package/dist/src/types.js

@@ -0,0 +1 @@
+export {};

package/package.json

@@ -0,0 +1,45 @@
+{
+  "name": "angular-agents-skills",
+  "version": "1.0.0",
+  "description": "Install Angular agents and skills for AI coding tools",
+  "type": "module",
+  "bin": {
+    "angular-ai": "dist/src/cli.js"
+  },
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc --watch",
+    "test": "node --test dist/tests/**/*.test.js",
+    "test:watch": "node --test --watch dist/tests/**/*.test.js",
+    "lint": "tsc --noEmit",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": [
+    "angular",
+    "ai",
+    "agents",
+    "opencode",
+    "claude",
+    "codex",
+    "skills",
+    "coding"
+  ],
+  "author": "Dayerlin Bustamante",
+  "license": "MIT",
+  "dependencies": {
+    "yaml": "^2.7.0"
+  },
+  "devDependencies": {
+    "typescript": "^5.7.0",
+    "@types/node": "^22.0.0"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "files": [
+    "dist",
+    "agents",
+    "skills",
+    "adapters"
+  ]
+}

package/skills/architecture/injection-tokens/SKILL.md

@@ -0,0 +1,82 @@
+---
+name: injection-tokens
+description: Define and consume typed InjectionTokens for configuration objects and adapter/strategy patterns, including optional injection with inject().
+---
+
+# Injection Tokens Pattern
+
+This skill covers creating and using typed `InjectionToken`s for configuration and pluggable adapter/strategy implementations, combined with the functional `inject()` API.
+
+## When to use
+- A library needs a way for consumers to provide configuration at the app/module level (e.g. default modal settings).
+- A component needs a pluggable "adapter" whose implementation is swapped per-feature (e.g. data source adapters for a dropdown).
+- A component needs to optionally read something that only exists in certain contexts (e.g. a dialog reference that's only present when opened via an overlay service).
+
+## Defining a configuration token
+```typescript
+export interface IModalConfiguration {
+  closeOnBackdropClick: boolean;
+  backdropClass?: string;
+}
+
+export const MODAL_CONFIGURATION: InjectionToken<IModalConfiguration> =
+  new InjectionToken<IModalConfiguration>('MODAL_CONFIGURATION');
+```
+Consumers provide a value at bootstrap or feature level:
+```typescript
+providers: [
+  { provide: MODAL_CONFIGURATION, useValue: { closeOnBackdropClick: true } }
+]
+```
+Service consumes it:
+```typescript
+@Injectable({ providedIn: 'root' })
+export class ModalService {
+  private readonly modalConfig = inject(MODAL_CONFIGURATION);
+}
+```
+
+## Adapter / strategy token pattern
+Used when a component needs an interchangeable implementation without hard-coding which one:
+```typescript
+export interface IDropdownAdapter {
+  fetchItems(query: string): Observable<any[]>;
+}
+
+export const DropdownAdapterToken = new InjectionToken<IDropdownAdapter>('DropdownAdapter');
+```
+```typescript
+export class DropdownComponent {
+  readonly dropdownAdapter = inject(DropdownAdapterToken);
+}
+```
+Consumers plug in a concrete implementation per usage:
+```typescript
+providers: [
+  { provide: DropdownAdapterToken, useClass: RemoteDropdownAdapter }
+]
+```
+
+## Optional injection
+Use `{ optional: true }` when a token is only available in some contexts (e.g. component rendered directly vs. rendered inside an overlay):
+```typescript
+private readonly dialogRef = inject(DIALOG_REF, { optional: true });
+
+close(): void {
+  this.dialogRef?.close();
+}
+```
+Always guard usage with `?.` or an explicit `if` check when injecting optionally.
+
+## Other `inject()` flags
+```typescript
+inject(SomeService, { self: true });     // only look at the current injector
+inject(SomeService, { skipSelf: true }); // skip the current injector, look at ancestors
+inject(SomeService, { host: true });     // stop searching at the host component boundary
+```
+
+## Guidelines
+- Prefer an `InjectionToken` over an abstract class when the "contract" is a plain interface (interfaces don't exist at runtime, so they can't be used as DI tokens directly).
+- Name tokens in SCREAMING_SNAKE_CASE-ish convention matching the library prefix (`MODAL_CONFIGURATION`) for configuration, and `PascalCase + Token` suffix for adapters (`DropdownAdapterToken`) — but stay consistent within one library.
+- Always type the `InjectionToken<T>` generic — untyped tokens defeat the purpose of DI type safety.
+- Provide a sensible default via a factory (`{ providedIn: 'root', factory: () => defaultConfig }`) when the token is optional at the library level but required internally.

package/skills/architecture/overlay-animation-lifecycle/SKILL.md

@@ -0,0 +1,98 @@
+---
+name: overlay-animation-lifecycle
+description: Coordinate enter/leave CSS animations for overlay components (modal, popover, toast, tooltip) using animationend events and Promise.all, without the Angular animations package.
+---
+
+# Overlay Animation Lifecycle
+
+This skill covers driving open/close animations for dynamically created overlay components (see `dynamic-component-creation`) using native CSS animations and the `animationend` DOM event, instead of `@angular/animations`.
+
+## When to use
+- Building/maintaining a modal, popover, toast, tooltip, or slide-in panel service that needs an enter animation on open and a coordinated exit animation on close (including an optional backdrop).
+- Avoiding the runtime cost/complexity of `@angular/animations` for simple CSS keyframe-based transitions.
+
+## Component contract
+Each overlay-capable component implements two methods returning a CSS class name:
+```typescript
+export interface IAnimatable {
+  getEnterAnimationClass(): AnimationTypes;
+  getLeaveAnimationClass(): AnimationTypes;
+}
+
+// Modal container
+getEnterAnimationClass(): AnimationTypes {
+  return 'modal-enter';
+}
+getLeaveAnimationClass(): AnimationTypes {
+  return 'modal-leave';
+}
+```
+```scss
+.modal-enter { animation: modal-fade-in 200ms ease-out; }
+.modal-leave { animation: modal-fade-out 150ms ease-in; }
+```
+
+## Opening: apply the class, wait for it to finish
+```typescript
+open(): void {
+  this.beforeOpened$.next(undefined);
+
+  const componentElement = this.componentRef.location.nativeElement as HTMLElement;
+
+  const onOpenEnd = (event: AnimationEvent) => {
+    if (event.target === componentElement) {
+      this.afterOpened$.next();
+      componentElement.removeEventListener('animationend', onOpenEnd);
+    }
+  };
+  componentElement.addEventListener('animationend', onOpenEnd);
+
+  this.enterAnimationClass = this.componentRef.instance.getEnterAnimationClass();
+  if (this.enterAnimationClass) {
+    componentElement.classList.add(this.enterAnimationClass);
+  }
+}
+```
+Always check `event.target === componentElement` — `animationend` bubbles, so a nested animated child could otherwise fire the handler prematurely.
+
+## Closing: coordinate multiple elements (component + backdrop) with `Promise.all`
+```typescript
+close(data: unknown = null): void {
+  const animationPromises: Promise<void>[] = [];
+
+  const createEndPromise = (element: HTMLElement): Promise<void> =>
+    new Promise(resolve => {
+      const onEnd = (event: AnimationEvent) => {
+        if (event.target === element) {
+          element.removeEventListener('animationend', onEnd);
+          resolve();
+        }
+      };
+      element.addEventListener('animationend', onEnd);
+    });
+
+  const componentElement = this.componentRef.location.nativeElement as HTMLElement;
+  componentElement.classList.add(this.componentRef.instance.getLeaveAnimationClass());
+  animationPromises.push(createEndPromise(componentElement));
+
+  if (this.backdropElement) {
+    this.backdropElement.classList.add('backdrop-leave');
+    animationPromises.push(createEndPromise(this.backdropElement));
+  }
+
+  Promise.all(animationPromises).then(() => {
+    this.afterClosed$.next(data);
+    // safe to destroy/detach the component now — see dynamic-component-creation
+  });
+}
+```
+
+## Why this pattern over `@angular/animations`
+- Zero runtime dependency; keyframes live entirely in SCSS alongside the component's other styles (see design tokens/theming skills).
+- Works uniformly for components created dynamically outside a template (no `[@trigger]` binding needed on a manually inserted element).
+- `Promise.all` naturally expresses "wait for N independent animations (component + backdrop) before finalizing teardown".
+
+## Pitfalls
+- If a component defines an enter/leave class but the corresponding CSS animation doesn't exist (or `animation-duration: 0`), `animationend` never fires and the promise never resolves — always verify the class has an actual `@keyframes` animation attached, not just a `transition`.
+- Remove the event listener after it fires (`removeEventListener`) to avoid leaks if the same element is reused.
+- Always destroy/remove the DOM node only **after** the close animation promise resolves, otherwise the exit animation is skipped.

package/skills/components/content-projection-ng/SKILL.md

@@ -0,0 +1,89 @@
+---
+name: content-projection-ng
+description: Project content into Angular components using ng-content, select, and ngProjectAs, including named/multi-slot projection and optional template directives.
+---
+
+# Content Projection (`ng-content` / `ngProjectAs`)
+
+This skill covers advanced content projection patterns used to build flexible, composable UI components.
+
+## When to use
+- A component (e.g. input, card, modal) needs to accept arbitrary consumer-provided markup in specific "slots" (label, left icon, footer, etc.).
+- A consumer needs to project a component that doesn't natively match a `select` query, using `ngProjectAs` to make it match.
+- A component needs to detect whether optional content was actually provided.
+
+## Basic single slot
+```html
+<ng-content />
+```
+Projects everything not matched by a more specific `select` elsewhere in the template.
+
+## Named slots with `select`
+```html
+<!-- ui-input template -->
+<ng-content select="[slot=left]" />
+<input #input ... />
+<ng-content select="[slot=right]" />
+<ng-content ngProjectAs="ui-label" />
+```
+Consumers target a slot either by a matching element/attribute selector:
+```html
+<ui-input>
+  <span slot="left">$</span>
+  <ui-label>Amount</ui-label>
+</ui-input>
+```
+
+## `ngProjectAs`
+Use when the element you want to project doesn't match the component's `select` selector by itself (e.g. you're projecting a generic `<div>` but the target slot expects `ui-label`):
+```html
+<div ngProjectAs="ui-label">Custom label markup</div>
+```
+`ngProjectAs` only affects *projection matching*; it does not change the rendered tag.
+
+## Detecting whether content was projected
+Combine with `contentChild()`/`viewChild()` (see `viewchild-contentchild-signals` skill) and check element children:
+```typescript
+constructor() {
+  effect(() => {
+    if (this.slotLeft().nativeElement.children.length > 0) {
+      this.slotLeftClassValue.set(true); // toggles host class for spacing/layout
+    }
+  });
+}
+```
+```html
+<div #slotLeft class="ui-slot-left"><ng-content select="[slot=left]" /></div>
+```
+
+## Optional template directives (structural content projection)
+For complex optional templates (custom item renderer, header, footer), define a directive applied to `<ng-template>` and read it with `contentChild()`:
+```typescript
+@Directive({ selector: 'ng-template[uiDropdownItemTmpl]' })
+export class DropdownItemTmplDirective {
+  templateRef = inject(TemplateRef);
+}
+```
+```html
+<!-- consumer -->
+<ui-dropdown>
+  <ng-template uiDropdownItemTmpl let-item>{{ item.label }}</ng-template>
+</ui-dropdown>
+```
+```typescript
+// component
+itemTmpl = contentChild(DropdownItemTmplDirective);
+```
+```html
+<!-- render with NgTemplateOutlet when provided, else a default row -->
+@if (itemTmpl(); as tmpl) {
+  <ng-container [ngTemplateOutlet]="tmpl.templateRef" [ngTemplateOutletContext]="{ $implicit: item }" />
+} @else {
+  <div class="default-item">{{ item[keyText()] }}</div>
+}
+```
+
+## Pitfalls
+- `select` selectors are evaluated once at compile time against the light DOM structure — dynamically changing an element's attribute after render won't re-route projection.
+- Don't forget to import `NgTemplateOutlet` in the component's standalone `imports` array when using `[ngTemplateOutlet]`.
+- Order of `<ng-content>` tags in the template determines render order, not the order elements appear in the consumer's markup.