angular-agents-skills 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Dayerlin Bustamante
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,205 @@
+# Angular AI
+
+> AI-agnostic Angular agents and skills for any coding tool.
+
+Install production-ready Angular knowledge into your AI coding agent. Agents and skills are defined once and installed into OpenCode, Claude Code, Codex, or any future tool.
+
+---
+
+## Architecture
+
+```
+angular-agent-skills/
+├── agents/                    # Universal agent definitions
+│   ├── angular-architect/
+│   │   ├── agent.yaml         # Metadata (name, description, triggers, skills)
+│   │   └── agent.md           # Instructions (pure markdown)
+│   ├── angular-migrator/
+│   │   ├── agent.yaml
+│   │   └── agent.md
+│   └── angular-reviewer/
+│       ├── agent.yaml
+│       └── agent.md
+├── adapters/                  # AI-specific format converters
+│   ├── opencode.ts
+│   ├── claude.ts
+│   └── codex.ts
+├── skills/                    # Reusable Angular knowledge
+│   ├── architecture/
+│   ├── components/
+│   ├── libraries/
+│   ├── performance/
+│   ├── quality/
+│   └── reactivity/
+├── src/                       # CLI and core logic
+│   ├── cli.ts
+│   ├── registry.ts
+│   ├── types.ts
+│   └── index.ts
+└── tests/                     # Test suite
+```
+
+### Universal Agent Format
+
+Each agent is a directory with two files:
+
+- **`agent.yaml`** — Universal metadata (name, description, triggers, skills)
+- **`agent.md`** — Pure markdown instructions (no frontmatter, no tool-specific syntax)
+
+This is the single source of truth. Agents never depend on any specific AI tool.
+
+### Adapters
+
+Adapters transform universal agents into tool-specific formats:
+
+| Adapter | Output Format | Install Path |
+|---|---|---|
+| `opencode` | Markdown + YAML frontmatter | `.opencode/agents/` |
+| `claude` | Markdown + YAML frontmatter | `.claude/agents/` |
+| `codex` | TOML | `.codex/agents/` |
+
+Adding a new AI tool requires only creating a new adapter file — no changes to agents or core logic.
+
+---
+
+## Installation
+
+### As CLI
+
+```bash
+npm install -g angular-ai
+```
+
+### As dependency
+
+```bash
+npm install angular-ai
+```
+
+---
+
+## Usage
+
+### Install an agent
+
+```bash
+# For OpenCode
+npx angular-ai install agent angular-architect --ai opencode
+
+# For Claude Code
+npx angular-ai install agent angular-architect --ai claude
+
+# For Codex
+npx angular-ai install agent angular-architect --ai codex
+```
+
+### Install for all tools
+
+```bash
+npx angular-ai install agent angular-architect --all
+```
+
+### Custom target directory
+
+```bash
+npx angular-ai install agent angular-architect \
+  --ai opencode \
+  --agent ./my-agents
+```
+
+### List available agents
+
+```bash
+npx angular-ai list agents
+```
+
+### List available adapters
+
+```bash
+npx angular-ai list adapters
+```
+
+---
+
+## Agents
+
+| Agent | Purpose | Triggers |
+|---|---|---|
+| `angular-architect` | Generate components, services, libraries | create component, generar, scaffold |
+| `angular-migrator` | Migrate legacy code to modern patterns | migrate, migrar, convert to signals |
+| `angular-reviewer` | Review code for best practices | review, revisar, code review |
+
+---
+
+## Skills
+
+Skills are reusable knowledge modules that agents reference:
+
+| Category | Skills |
+|---|---|
+| **Architecture** | injection-tokens, overlay-animation-lifecycle |
+| **Components** | dynamic-components, modern-host-bindings, content-projection-ng, viewchild-contentchild-signals |
+| **Libraries** | standalone-component-library, monorepo-ng-packagr, library-versioning |
+| **Performance** | defer-blocks, control-flow-syntax |
+| **Quality** | pr-reviewer, vitest-angular-components |
+| **Reactivity** | signals-state-management, signals-inputs-outputs, signals-effects |
+
+---
+
+## Development
+
+```bash
+# Install dependencies
+npm install
+
+# Build
+npm run build
+
+# Run tests
+npm test
+
+# Type check
+npm run lint
+```
+
+---
+
+## Adding a New Adapter
+
+1. Create `adapters/my-tool.ts`:
+```typescript
+import type { Adapter, AdapterOutput, InstallOptions, UniversalAgent } from '../src/types.js';
+
+export const myToolAdapter: Adapter = {
+  name: 'my-tool',
+  description: 'My AI Tool',
+  defaultDir: '.my-tool/agents',
+
+  generate(agent: UniversalAgent): AdapterOutput {
+    // Transform agent to tool-specific format
+    return {
+      filename: `${agent.metadata.name}.ext`,
+      content: `...`,
+    };
+  },
+
+  getInstallPath(options: InstallOptions): string {
+    const base = options.targetDir || this.defaultDir;
+    return `${base}/${options.agentName}.ext`;
+  },
+};
+```
+
+2. Register in `src/cli.ts`:
+```typescript
+import { myToolAdapter } from '../adapters/my-tool.js';
+registerAdapter(myToolAdapter);
+```
+
+3. Done. The CLI now supports `--ai my-tool`.
+
+---
+
+## License
+
+MIT

package/adapters/claude/index.ts

@@ -0,0 +1,53 @@
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { parse as parseYaml } from 'yaml';
+import type { Adapter, AdapterOutput, InstallOptions, UniversalAgent } from '../../src/types.js';
+
+const DEFAULT_CONFIG: Record<string, unknown> = {
+  description: 'Angular agent for Claude',
+  name: 'angular-agent',
+  tools: 'Read, Grep, Glob, Edit, Write, Bash',
+};
+
+function loadConfigFromAgent(agentBasePath: string, ai: string): Record<string, unknown> {
+  const configPath = join(agentBasePath, 'configs', `${ai}.yaml`);
+
+  try {
+    return parseYaml(readFileSync(configPath, 'utf-8'));
+  } catch {
+    return {};
+  }
+}
+
+export function createClaudeAdapter(): Adapter {
+  return {
+    name: 'claude',
+    description: 'Claude Code',
+    defaultDir: '.claude/agents',
+    extension: 'md',
+
+    generate(agent: UniversalAgent, config?: Record<string, unknown>): AdapterOutput {
+      const agentConfig = loadConfigFromAgent(agent.basePath, 'claude');
+      const cfg = { ...DEFAULT_CONFIG, ...agentConfig, ...config };
+
+      const frontmatter = [
+        '---',
+        `name: ${cfg.name || agent.metadata.name}`,
+        `description: ${cfg.description || agent.metadata.description}`,
+        `tools: ${cfg.tools || 'Read, Grep, Glob, Edit, Write, Bash'}`,
+        '---',
+        '',
+      ];
+
+      return {
+        filename: `${agent.metadata.name}.md`,
+        content: frontmatter.join('\n') + agent.instructions.content,
+      };
+    },
+
+    getInstallPath(name: string, targetDir?: string): string {
+      const base = targetDir || this.defaultDir;
+      return `${base}/${name}.${this.extension}`;
+    },
+  };
+}

package/adapters/codex/index.ts

@@ -0,0 +1,55 @@
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { parse as parseYaml } from 'yaml';
+import type { Adapter, AdapterOutput, InstallOptions, UniversalAgent } from '../../src/types.js';
+
+const DEFAULT_CONFIG: Record<string, unknown> = {
+  description: 'Angular agent for Codex',
+  name: 'angular-agent',
+};
+
+function loadConfigFromAgent(agentBasePath: string, ai: string): Record<string, unknown> {
+  const configPath = join(agentBasePath, 'configs', `${ai}.yaml`);
+
+  try {
+    return parseYaml(readFileSync(configPath, 'utf-8'));
+  } catch {
+    return {};
+  }
+}
+
+export function createCodexAdapter(): Adapter {
+  return {
+    name: 'codex',
+    description: 'OpenAI Codex CLI',
+    defaultDir: '.codex/agents',
+    extension: 'toml',
+
+    generate(agent: UniversalAgent, config?: Record<string, unknown>): AdapterOutput {
+      const agentConfig = loadConfigFromAgent(agent.basePath, 'codex');
+      const cfg = { ...DEFAULT_CONFIG, ...agentConfig, ...config };
+
+      const escapedInstructions = agent.instructions.content
+        .replace(/\\/g, '\\\\')
+        .replace(/"/g, '\\"')
+        .replace(/\n/g, '\\n');
+
+      const content = [
+        `name = "${cfg.name || agent.metadata.name}"`,
+        `description = "${cfg.description || agent.metadata.description}"`,
+        `developer_instructions = "${escapedInstructions}"`,
+        '',
+      ].join('\n');
+
+      return {
+        filename: `${agent.metadata.name}.toml`,
+        content,
+      };
+    },
+
+    getInstallPath(name: string, targetDir?: string): string {
+      const base = targetDir || this.defaultDir;
+      return `${base}/${name}.${this.extension}`;
+    },
+  };
+}

package/adapters/copilot/index.ts

@@ -0,0 +1,45 @@
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { parse as parseYaml } from 'yaml';
+import type { Adapter, AdapterOutput, InstallOptions, UniversalAgent } from '../../src/types.js';
+
+const DEFAULT_CONFIG: Record<string, unknown> = {
+  description: 'Angular agent for GitHub Copilot',
+  name: 'angular-agent',
+};
+
+function loadConfigFromAgent(agentBasePath: string, ai: string): Record<string, unknown> {
+  const configPath = join(agentBasePath, 'configs', `${ai}.yaml`);
+
+  try {
+    return parseYaml(readFileSync(configPath, 'utf-8'));
+  } catch {
+    return {};
+  }
+}
+
+export function createCopilotAdapter(): Adapter {
+  return {
+    name: 'copilot',
+    description: 'GitHub Copilot',
+    defaultDir: '.github',
+    extension: 'md',
+
+    generate(agent: UniversalAgent, config?: Record<string, unknown>): AdapterOutput {
+      const agentConfig = loadConfigFromAgent(agent.basePath, 'copilot');
+      const cfg = { ...DEFAULT_CONFIG, ...agentConfig, ...config };
+
+      const header = `# ${cfg.name || agent.metadata.name}\n\n${cfg.description || agent.metadata.description}\n\n`;
+
+      return {
+        filename: `copilot-instructions-${agent.metadata.name}.md`,
+        content: header + agent.instructions.content,
+      };
+    },
+
+    getInstallPath(name: string, targetDir?: string): string {
+      const base = targetDir || this.defaultDir;
+      return `${base}/${name}-instructions.${this.extension}`;
+    },
+  };
+}

package/adapters/cursor/index.ts

@@ -0,0 +1,51 @@
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { parse as parseYaml } from 'yaml';
+import type { Adapter, AdapterOutput, InstallOptions, UniversalAgent } from '../../src/types.js';
+
+const DEFAULT_CONFIG: Record<string, unknown> = {
+  description: 'Angular agent for Cursor',
+  name: 'angular-agent',
+};
+
+function loadConfigFromAgent(agentBasePath: string, ai: string): Record<string, unknown> {
+  const configPath = join(agentBasePath, 'configs', `${ai}.yaml`);
+
+  try {
+    return parseYaml(readFileSync(configPath, 'utf-8'));
+  } catch {
+    return {};
+  }
+}
+
+export function createCursorAdapter(): Adapter {
+  return {
+    name: 'cursor',
+    description: 'Cursor AI IDE',
+    defaultDir: '.cursor/rules',
+    extension: 'mdc',
+
+    generate(agent: UniversalAgent, config?: Record<string, unknown>): AdapterOutput {
+      const agentConfig = loadConfigFromAgent(agent.basePath, 'cursor');
+      const cfg = { ...DEFAULT_CONFIG, ...agentConfig, ...config };
+
+      const frontmatter = [
+        '---',
+        `description: ${cfg.description || agent.metadata.description}`,
+        'alwaysApply: false',
+        '---',
+        '',
+      ];
+
+      return {
+        filename: `${agent.metadata.name}.mdc`,
+        content: frontmatter.join('\n') + agent.instructions.content,
+      };
+    },
+
+    getInstallPath(name: string, targetDir?: string): string {
+      const base = targetDir || this.defaultDir;
+      return `${base}/${name}.${this.extension}`;
+    },
+  };
+}

package/adapters/opencode/index.ts

@@ -0,0 +1,63 @@
+import { readFileSync } from 'node:fs';
+import { join, dirname } from 'node:path';
+import { parse as parseYaml } from 'yaml';
+import type { Adapter, AdapterOutput, InstallOptions, UniversalAgent } from '../../src/types.js';
+
+const DEFAULT_CONFIG: Record<string, unknown> = {
+  description: 'Angular agent for OpenCode',
+  mode: 'subagent',
+  permission: {
+    edit: 'allow',
+    bash: 'ask',
+  },
+};
+
+function loadConfigFromAgent(agentBasePath: string, ai: string): Record<string, unknown> {
+  const configPath = join(agentBasePath, 'configs', `${ai}.yaml`);
+
+  try {
+    return parseYaml(readFileSync(configPath, 'utf-8'));
+  } catch {
+    return {};
+  }
+}
+
+export function createOpenCodeAdapter(): Adapter {
+  return {
+    name: 'opencode',
+    description: 'OpenCode AI coding agent',
+    defaultDir: '.opencode/agents',
+    extension: 'md',
+
+    generate(agent: UniversalAgent, config?: Record<string, unknown>): AdapterOutput {
+      const agentConfig = loadConfigFromAgent(agent.basePath, 'opencode');
+      const cfg = { ...DEFAULT_CONFIG, ...agentConfig, ...config };
+
+      const frontmatter = [
+        '---',
+        `description: ${cfg.description || agent.metadata.description}`,
+        `mode: ${cfg.mode || 'subagent'}`,
+      ];
+
+      if (cfg.permission) {
+        frontmatter.push('permission:');
+        const perm = cfg.permission as Record<string, string>;
+        for (const [key, value] of Object.entries(perm)) {
+          frontmatter.push(`  ${key}: ${value}`);
+        }
+      }
+
+      frontmatter.push('---', '');
+
+      return {
+        filename: `${agent.metadata.name}.md`,
+        content: frontmatter.join('\n') + agent.instructions.content,
+      };
+    },
+
+    getInstallPath(name: string, targetDir?: string): string {
+      const base = targetDir || this.defaultDir;
+      return `${base}/${name}.${this.extension}`;
+    },
+  };
+}

package/agents/angular-architect/agent.md

@@ -0,0 +1,143 @@
+# Angular Architect
+
+You are an Angular architect who generates new components, services, and libraries following best practices and project conventions.
+
+## Core Skills
+
+Load and follow the relevant skills from the project's `skills/` directory. The agent.yaml file lists which skills are relevant for this agent.
+
+## Generation Templates
+
+### Component Generation
+
+When creating a new component, use this structure:
+
+```typescript
+// component-name.component.ts
+import { Component, input, output, computed, signal } from '@angular/core';
+
+@Component({
+  selector: 'app-component-name',
+  standalone: true,
+  template: ``,
+  styles: []
+})
+export class ComponentNameComponent {
+  // Inputs (signal-based)
+  readonly data = input.required<Type>();
+  readonly disabled = input(false);
+
+  // Outputs
+  readonly itemClick = output<Item>();
+
+  // State
+  private readonly _internalState = signal<Type>();
+
+  // Computed
+  readonly derivedValue = computed(() => this.data().property);
+
+  // Methods
+  handleClick(item: Item): void {
+    this.itemClick.emit(item);
+  }
+}
+```
+
+### Service Generation
+
+```typescript
+// service-name.service.ts
+import { Injectable, inject, signal } from '@angular/core';
+import { SOME_CONFIG, SomeConfig } from './tokens';
+
+@Injectable({ providedIn: 'root' })
+export class ServiceNameService {
+  private readonly config = inject(SOME_CONFIG);
+  private readonly _state = signal<StateType>(initialState);
+
+  readonly state = this._state.asReadonly();
+
+  updateState(value: StateType): void {
+    this._state.set(value);
+  }
+}
+```
+
+### InjectionToken Generation
+
+```typescript
+// tokens.ts
+import { InjectionToken } from '@angular/core';
+
+export interface ComponentConfig {
+  // Configuration options
+}
+
+export const COMPONENT_CONFIG = new InjectionToken<ComponentConfig>('COMPONENT_CONFIG');
+
+// Default factory
+export function provideComponentConfig(config: Partial<ComponentConfig>): Provider {
+  return {
+    provide: COMPONENT_CONFIG,
+    useValue: { ...defaultConfig, ...config }
+  };
+}
+```
+
+### Library Generation
+
+For a new library, create:
+
+```
+libs/
+  feature-name/
+    src/
+      lib/
+        components/
+        services/
+        tokens/
+        models/
+      index.ts
+      public-api.ts
+    ng-package.json
+    package.json
+    tsconfig.lib.json
+```
+
+## Decision Tree
+
+When user requests generation:
+
+1. **What type?**
+   - Component → Use component template
+   - Service → Use service template
+   - Library → Use library structure
+   - Module (legacy) → Warn and suggest standalone
+
+2. **What features?**
+   - Needs configuration? → Create InjectionToken
+   - Needs state? → Use signals
+   - Needs lazy loading? → Add @defer in template
+   - Has children? → Add content projection
+
+3. **Where to place?**
+   - Check existing project structure
+   - Follow naming conventions
+   - Place in appropriate module/feature
+
+## Output
+
+Always generate:
+1. Complete TypeScript file(s)
+2. Test file (if requested)
+3. Usage example
+4. Any required tokens or providers
+
+## Rules
+
+- Always use standalone components
+- Always use signal-based inputs/outputs
+- Always use functional `inject()` instead of constructor
+- Always include proper TypeScript types
+- Follow existing project conventions (check `skills/` for reference)
+- Write in Spanish when the user communicates in Spanish

package/agents/angular-architect/configs/claude.yaml

@@ -0,0 +1,3 @@
+name: angular-architect
+description: Generate Angular architecture, components, and libraries following project conventions.
+tools: Read, Grep, Glob, Edit, Write, Bash

package/agents/angular-architect/configs/codex.yaml

@@ -0,0 +1,2 @@
+name: angular-architect
+description: Generate Angular architecture, components, and libraries following project conventions.

package/agents/angular-architect/configs/opencode.yaml

@@ -0,0 +1,5 @@
+description: Generate Angular architecture, components, and libraries following project conventions.
+mode: subagent
+permission:
+  edit: allow
+  bash: ask