feat: add L2 constructs (Agent, Skill, Prompt, BuiltInTool, Shell)

.gitignore

@@ -4,3 +4,6 @@ coverage/
 .kiro-constructs.out/
 .kiro-constructs.cache/
 *.tsbuildinfo
+docs/
+
+.idea/

AGENTS.md

@@ -0,0 +1,11 @@
+# Agent Notes
+
+## Pre-push checklist
+
+Before pushing changes, run the full CI pipeline locally to avoid PR failures:
+
+```bash
+npm run build && npm run lint && npm run format:check && npm test
+```
+
+If `format:check` fails, fix with `npm run format` then re-run the check.

README.md

@@ -11,18 +11,31 @@ npm install @kiro/constructs constructs
 ## Quick Start
 
 ```typescript
-import { App, CfgAgent, CfgPrompt } from '@kiro/constructs';
+import { App, Agent, Skill, Prompt, BuiltInTool, Shell } from '@kiro/constructs';
 
 const app = new App();
 
-new CfgAgent(app, 'dev', {
-  description: 'Development assistant',
-  prompt: 'You are a helpful development assistant.',
-  tools: ['@builtin'],
+const skill = new Skill(app, 'typescript', {
+  description: 'TypeScript development expertise',
+  instructions: '# TypeScript\n\nUse strict TypeScript with no `any`.',
 });
 
-new CfgPrompt(app, 'review', {
-  content: '# Code Review\n\nReview the code for correctness and readability.',
+const prompt = new Prompt(app, 'review', {
+  content: '# Code Review\n\nReview for correctness and readability.',
+});
+
+new Agent(app, 'dev', {
+  description: 'Development assistant',
+  prompt: 'You are a helpful development assistant.',
+  skills: [skill],
+  prompts: [prompt],
+  tools: [
+    BuiltInTool.all({ allowed: true }),
+    BuiltInTool.shell({
+      allow: [Shell.git.readonly(), Shell.npm.scripts()],
+      deny: [Shell.git.destructive()],
+    }),
+  ],
 });
 
 await app.synth();
@@ -33,18 +46,97 @@ This synthesizes to:
 ```
 .kiro-constructs.out/
 ├── agents/dev.json
+├── skills/typescript/SKILL.md
 └── prompts/review.md
 ```
 
-## Core Concepts
+## Constructs
+
+### Agent
+
+Higher-level construct for Kiro CLI agents. Accepts typed tool configs, skills, and prompts, and decomposes them into the correct JSON fields.
+
+```typescript
+const agent = new Agent(app, 'dev', {
+  description: 'Development assistant',
+  prompt: 'You are helpful.',
+  tools: [BuiltInTool.all({ allowed: true })],
+  skills: [skill],
+  prompts: [prompt],
+});
+
+// Builder methods for post-construction composition
+agent.addTool(BuiltInTool.write({ deniedPaths: ['.env'] }));
+agent.addMcpServer('github', { command: 'gh-mcp' });
+agent.addHook('agentSpawn', { command: 'git status' });
+agent.addSkill(anotherSkill);
+agent.addPrompt(anotherPrompt);
+```
+
+### Skill
+
+Synthesizes a skill directory with a `SKILL.md` file (YAML frontmatter + markdown body) and optional assets.
+
+```typescript
+new Skill(app, 'typescript', {
+  description: 'TypeScript expertise',
+  instructions: '# TypeScript\n\nFollow strict conventions...',
+  assets: { 'tsconfig.example.json': '{ "strict": true }' },
+});
+
+// Load from an existing skill directory
+const existing = Skill.fromDirectory(app, 'review', './skills/review');
+```
+
+### Prompt
+
+Synthesizes a prompt markdown file with optional YAML frontmatter.
+
+```typescript
+const prompt = new Prompt(app, 'review', {
+  content: '# Code Review\n\nReview for correctness.',
+  metadata: { version: '2.0' },
+});
+
+prompt.appendContent('## Additional Guidelines\n\nCheck for security issues.');
+
+// Load from an existing file
+const fromDisk = Prompt.fromFile(app, 'security', './prompts/security.md');
+```
+
+### BuiltInTool & Shell
+
+Typed factories for Kiro's built-in tools with shell permission helpers.
+
+```typescript
+// Individual tools with settings
+BuiltInTool.shell({ allowed: true, denyByDefault: true });
+BuiltInTool.write({ deniedPaths: ['.env', '*.pem'] });
+BuiltInTool.glob({ allowReadOnly: true });
+
+// All 9 built-in tools at once
+BuiltInTool.all({ allowed: true });
+
+// Shell permissions
+BuiltInTool.shell({
+  allow: [Shell.git.readonly(), Shell.npm.scripts(), Shell.files.inspect()],
+  deny: [Shell.git.destructive()],
+});
+```
+
+### L1 Constructs
+
+Low-level constructs that map 1:1 to output files, for when you need full control:
+
+- `CfgAgent` — synthesizes to `agents/{name}.json`
+- `CfgPrompt` — synthesizes to `prompts/{name}.md`
+
+### Core
 
-- **App** — Root construct that drives synthesis to an output directory
-- **CfgAgent** — L1 construct for Kiro CLI agent configuration (`.kiro/agents/*.json`)
-- **CfgPrompt** — L1 construct for Kiro prompts (`.kiro/prompts/*.md`)
-- **Source** — Content factories for text, JSON, and file copy
+- **App** — Root construct that drives synthesis
+- **Source** — Content factories (text, JSON, file copy)
 - **Assembly** — File system output abstraction
 - **Lazy** — Deferred value resolution
-- **Content** — File loading helper for construct content
 - **Cache** — SHA-based caching for LLM-generated content
 
 ## Model Providers

examples/agent-with-skills.ts

@@ -0,0 +1,52 @@
+/**
+ * L2 constructs example: Agent with Skills and Prompts.
+ *
+ * Run: npx tsx examples/l2.ts
+ * Output: .kiro-constructs.out/agents/dev.json
+ *         .kiro-constructs.out/skills/typescript/SKILL.md
+ *         .kiro-constructs.out/prompts/review.md
+ */
+
+import { App, Agent, Skill, Prompt, BuiltInTool, Shell } from '@kiro/constructs';
+
+const app = new App();
+
+const skill = new Skill(app, 'typescript', {
+  description: 'TypeScript development expertise',
+  instructions: [
+    '# TypeScript',
+    '',
+    'Follow these conventions:',
+    '- Use strict TypeScript with no `any`',
+    '- Prefer `interface` over `type` for object shapes',
+    '- Use `readonly` for immutable properties',
+  ].join('\n'),
+});
+
+const prompt = new Prompt(app, 'review', {
+  content: [
+    '# Code Review',
+    '',
+    'Review the code for:',
+    '- Correctness and edge cases',
+    '- Performance implications',
+    '- Readability and naming',
+  ].join('\n'),
+});
+
+new Agent(app, 'dev', {
+  description: 'Full-stack development assistant',
+  prompt: 'You are a senior full-stack developer.',
+  skills: [skill],
+  prompts: [prompt],
+  tools: [
+    BuiltInTool.all({ allowed: true }),
+    BuiltInTool.shell({
+      allow: [Shell.git.readonly(), Shell.git.write(), Shell.npm.scripts()],
+      deny: [Shell.git.destructive()],
+    }),
+    BuiltInTool.write({ deniedPaths: ['.env', '*.pem'] }),
+  ],
+});
+
+app.synth().then(() => console.log('Synthesized to', app.outdir));

examples/basic.ts

@@ -1,6 +1,3 @@
-// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
-// SPDX-License-Identifier: Apache-2.0
-
 /**
  * Basic example: synthesize a Kiro agent and prompt using core constructs.
  *