Merge pull request #31 from BjornMelin/feat/add-agent-skills

feat: add agent skills + UI for management

Author: BjornMelin

.env.example

@@ -37,6 +37,11 @@ NEXT_PUBLIC_AUTH_SOCIAL_PROVIDERS=vercel
 #   (auto-managed by .github/workflows/vercel-preview-env-sync.yml).
 APP_BASE_URL=
 
+# Agent Skills (optional)
+# Comma-separated list of skill root directories scanned for repo-bundled skills.
+# Defaults to ".agents/skills,.codex/skills". Supported values: ".agents/skills", ".codex/skills" (subset allowed).
+AGENT_SKILLS_DIRS=.agents/skills,.codex/skills
+
 # Database (Neon Postgres)
 # Prefer connection strings with `sslmode=verify-full`.
 DATABASE_URL=

.gitignore

@@ -47,6 +47,9 @@ yarn-error.log*
 # Vercel
 .vercel/
 
+# Neon
+.neon
+
 # OS
 .DS_Store
 .AppleDouble

.neon

@@ -41,6 +41,7 @@ bun run fetch:models           # Update AI model catalog (requires AI_GATEWAY_AP
 - Do **not** switch to package barrel imports by default.
 - Barrel imports are allowed only for packages listed in `next.config.ts` `experimental.optimizePackageImports` (currently `radix-ui` and `lucide-react`).
 - For all other packages, use explicit/non-barrel imports.
+- **Workflow layering guardrail**: Workflow-only shared helpers must live in `src/workflows/_shared/` (not `src/lib/`). Avoid `index.ts` re-export facades; import concrete modules directly.
 
 ## Drizzle + database
 

AGENTS.md

@@ -135,6 +135,20 @@ Primary spec/ADR references:
 - [`docs/architecture/spec/SPEC-0004-chat-retrieval-augmentation.md`](./docs/architecture/spec/SPEC-0004-chat-retrieval-augmentation.md)
 - [`docs/architecture/adr/ADR-0006-agent-runtime-ai-sdk-v6-toolloopagent-streaming-ui-responses.md`](./docs/architecture/adr/ADR-0006-agent-runtime-ai-sdk-v6-toolloopagent-streaming-ui-responses.md)
 
+### Epic 4b: Agent Skills (progressive disclosure)
+
+- Support runtime-loadable Agent Skills (name/description index + on-demand load). (FR-035)
+- Support project-scoped skill overrides stored in the DB. (FR-036)
+- Support installing skills from the public skills.sh registry from the UI. (FR-037)
+- Keep skill loading read-only; any execution of skill scripts must be sandboxed and approval-gated. (NFR-013, NFR-014, NFR-016)
+
+Primary spec/ADR references:
+
+- [`docs/architecture/spec/SPEC-0027-agent-skills-runtime-integration.md`](./docs/architecture/spec/SPEC-0027-agent-skills-runtime-integration.md)
+- [`docs/architecture/spec/SPEC-0028-skills-registry-ui-and-bundled-installs.md`](./docs/architecture/spec/SPEC-0028-skills-registry-ui-and-bundled-installs.md)
+- [`docs/architecture/adr/ADR-0028-agent-skills-progressive-disclosure-hybrid-fs-db.md`](./docs/architecture/adr/ADR-0028-agent-skills-progressive-disclosure-hybrid-fs-db.md)
+- [`docs/architecture/adr/ADR-0029-skills-registry-integration-ui-installs-and-bundled-db-files.md`](./docs/architecture/adr/ADR-0029-skills-registry-integration-ui-installs-and-bundled-db-files.md)
+
 ### Epic 5: Durable runs (research → artifacts)
 
 - Start and persist durable runs with step status and tool call logs. (FR-010, FR-011)

PRD.md

@@ -20,6 +20,7 @@ trail).
 - Enforces per-user project ownership for all project-scoped reads/writes.
 - Applies server-side search guardrails (strict query validation + rate limiting).
 - Maintains a formal architecture pack (PRD, ADRs, specs, security) in-repo with deterministic export.
+- Supports runtime-loadable Agent Skills (SKILL.md progressive disclosure) with per-project overrides and skills.sh registry installs.
 - Supports an implementation/deployment phase (approval-gated side effects) to:
   - connect a target GitHub repo
   - plan changes traceable to artifacts
@@ -65,6 +66,8 @@ flowchart LR
 - Provisioning + deploy automation: [`docs/architecture/spec/SPEC-0018-infrastructure-provisioning-and-secrets-for-target-apps.md`](./docs/architecture/spec/SPEC-0018-infrastructure-provisioning-and-secrets-for-target-apps.md)
 - Sandbox verification jobs: [`docs/architecture/spec/SPEC-0019-sandbox-build-test-and-ci-execution.md`](./docs/architecture/spec/SPEC-0019-sandbox-build-test-and-ci-execution.md)
 - Workspace + search UX: [`docs/architecture/spec/SPEC-0020-project-workspace-and-search.md`](./docs/architecture/spec/SPEC-0020-project-workspace-and-search.md)
+- Agent Skills (progressive disclosure): [`docs/architecture/spec/SPEC-0027-agent-skills-runtime-integration.md`](./docs/architecture/spec/SPEC-0027-agent-skills-runtime-integration.md)
+- Skills registry installs: [`docs/architecture/spec/SPEC-0028-skills-registry-ui-and-bundled-installs.md`](./docs/architecture/spec/SPEC-0028-skills-registry-ui-and-bundled-installs.md)
 - GitOps + deploy ADRs:
   - [`docs/architecture/adr/ADR-0024-gitops-repository-automation-pr-based-workflows.md`](./docs/architecture/adr/ADR-0024-gitops-repository-automation-pr-based-workflows.md)
   - [`docs/architecture/adr/ADR-0025-infrastructure-provisioning-and-vercel-deployment-automation.md`](./docs/architecture/adr/ADR-0025-infrastructure-provisioning-and-vercel-deployment-automation.md)

README.md

@@ -0,0 +1,158 @@
+---
+ADR: 0028
+Title: Agent Skills progressive disclosure (hybrid filesystem + DB)
+Status: Implemented
+Version: 0.1
+Date: 2026-02-09
+Supersedes: []
+Superseded-by: []
+Related: [ADR-0006, ADR-0010, ADR-0013, ADR-0021, ADR-0026, ADR-0029]
+Tags: [ai-sdk, agents, nextjs, workflow, security, caching]
+Related-Requirements: [FR-035, FR-036, NFR-006, NFR-013, NFR-014, NFR-016]
+References:
+  - [AI SDK cookbook: Add Skills to Your Agent](https://ai-sdk.dev/cookbook/guides/agent-skills)
+  - [1Password: From Magic to Malware (Agent Skills attack surface)](https://1password.com/blog/from-magic-to-malware-how-openclaws-agent-skills-become-an-attack-surface)
+  - [Vercel KB: Using files in Serverless Functions](https://vercel.com/kb/guide/how-can-i-use-files-in-serverless-functions)
+---
+
+## Status
+
+Implemented — 2026-02-09.
+
+## Context
+
+This app relies on multiple agents and workflows (chat, research, code mode,
+implementation runs). Agents need **specialized, high-signal workflows** (e.g.
+Workflow DevKit patterns, Sandbox safety, AI SDK usage) but the system prompt
+must remain small to preserve:
+
+- cost controls (token budgets)
+- relevance (avoid noisy instructions)
+- reliability (reduce prompt drift)
+
+We also need **project-scoped customization** so a project can override or
+extend the default skills without requiring a redeploy.
+
+## Decision Drivers
+
+- Progressive disclosure (small prompt index, load full instructions on demand)
+- Per-project overrides with deterministic precedence
+- Safe-by-default: no code execution from skill content in app runtime
+- Vercel/Next.js serverless compatibility (skill files must be traced/bundled)
+- Maintainability: strict TS, simple resolution rules, minimal new surface area
+
+## Alternatives Considered
+
+### A. Filesystem-only skills (repo-bundled)
+
+Pros:
+
+- Very low maintenance and operational complexity.
+- Skills are versioned and reviewed via PRs.
+- Deterministic deploys.
+
+Cons:
+
+- No per-project customization without redeploy.
+- Cannot support non-developer editing via UI.
+
+### B. Database-only skills (project-defined)
+
+Pros:
+
+- Maximum flexibility and per-project customization.
+- No reliance on filesystem tracing for skills.
+
+Cons:
+
+- Higher maintenance burden (validation, governance, drift management).
+- Loses the “vetted standard library” properties of repo-bundled skills.
+
+### C. Hybrid filesystem + DB (DB overrides by normalized name) (**Chosen**)
+
+Pros:
+
+- Repo ships a vetted “standard library” of skills.
+- Projects can override/extend skills without redeploy.
+- Clear precedence rule: DB wins on normalized name collisions.
+
+Cons:
+
+- Added complexity: merging/indexing semantics and cache invalidation.
+- Requires careful path confinement for any file reads.
+
+### D. Filesystem-only with project-local overrides in-repo
+
+Pros:
+
+- Override semantics without DB schema/migrations.
+- Git-tracked overrides.
+
+Cons:
+
+- Requires writing to the repo (not compatible with this app’s product UX).
+- Still effectively requires redeploy/branch management for updates.
+
+## Decision Framework
+
+Weights:
+
+- Solution leverage: 35%
+- Application value: 30%
+- Maintenance and cognitive load: 25%
+- Architectural adaptability: 10%
+
+| Option | Leverage | Value | Maintenance | Adaptability | Weighted total |
+| --- | ---: | ---: | ---: | ---: | ---: |
+| A. Filesystem-only | 6.8 | 5.8 | 9.2 | 4.6 | 7.06 |
+| B. Database-only | 8.6 | 9.1 | 7.2 | 9.0 | 8.42 |
+| C. Hybrid FS + DB overrides | 9.4 | 9.3 | 8.6 | 9.0 | **9.13** |
+| D. FS-only + project-local overrides | 7.4 | 6.4 | 8.4 | 6.0 | 7.25 |
+
+Consensus process artifacts used in evaluation:
+
+- Exa deep research task: `01kh25d2yzphpxetpdat8ym2mf`
+- Zen consensus continuation: `c845be0a-d38e-47d2-8445-65eeccd705c4`
+
+## Decision
+
+Adopt **Hybrid FS + DB Agent Skills** with **progressive disclosure**:
+
+1. Repo-bundled skills live in the filesystem and are discovered from
+   `AGENT_SKILLS_DIRS`.
+2. Projects can define DB skills that override filesystem skills by normalized
+   name (`trim().toLowerCase()`).
+3. Agents only see `{name, description}` in the prompt. Full instructions are
+   loaded on-demand via:
+   - `skills.load` (load skill body)
+   - `skills.readFile` (read repo-bundled skill files and bundled DB skill
+     files when present; strict path safety)
+4. Skill-bundled scripts are **not executed** by the app runtime. Any future
+   execution must be implemented as separate sandbox tools and gated by explicit
+   approvals (see ADR-0010).
+
+Implementation details are defined in:
+
+- [SPEC-0027](../spec/SPEC-0027-agent-skills-runtime-integration.md)
+- [SPEC-0028](../spec/SPEC-0028-skills-registry-ui-and-bundled-installs.md)
+
+## Consequences
+
+### Positive outcomes
+
+- Skill workflows scale without prompt bloat (progressive disclosure).
+- Teams can adapt skills per project without redeploy.
+- Read-only file access and sandbox-only execution preserve security posture.
+
+### Negative outcomes / risks
+
+- Added complexity in resolution/debugging (two sources).
+  - Mitigation: deterministic precedence, normalized-name resolution, and UI
+    showing “effective skills”.
+- Untrusted DB skill content can cause prompt injection.
+  - Mitigation: skills remain text-only; side-effectful tools remain
+    least-privilege + approval-gated.
+
+## Changelog
+
+- **0.1 (2026-02-09)**: Initial version. Implemented as part of SPEC-0027.

docs/architecture/adr/ADR-0028-agent-skills-progressive-disclosure-hybrid-fs-db.md

@@ -0,0 +1,156 @@
+---
+ADR: 0029
+Title: Skills registry integration (skills.sh) with UI installs + bundled DB skill files
+Status: Implemented
+Version: 0.1
+Date: 2026-02-09
+Supersedes: []
+Superseded-by: []
+Related: [ADR-0028, ADR-0010, ADR-0013, ADR-0026, ADR-0021]
+Tags: [agents, skills, nextjs, workflow, blob, security]
+Related-Requirements: [FR-035, FR-036, FR-037, NFR-001, NFR-006, NFR-013, NFR-014, NFR-016, IR-006, IR-011]
+References:
+  - [skills.sh docs](https://skills.sh/docs)
+  - [skills.sh CLI docs](https://skills.sh/docs/cli)
+  - [skills.sh search API](https://skills.sh/api/search)
+  - [vercel-labs/skills (GitHub)](https://github.com/vercel-labs/skills)
+---
+
+## Status
+
+Implemented — 2026-02-09.
+
+## Context
+
+The app uses Agent Skills (progressive disclosure) to keep system prompts small
+while providing deep, task-specific workflows (Sandbox, Workflow DevKit, AI SDK,
+etc.). The base implementation supports:
+
+- repo-bundled filesystem skills
+- project-scoped DB skills that override filesystem skills by normalized name
+
+Teams need a **UI-managed** way to discover and install skills from the public
+ecosystem (skills.sh) without requiring developers to:
+
+- edit the repo to add skill folders
+- copy/paste `SKILL.md` into the DB manually
+
+We must preserve the security posture:
+
+- Do not execute skill-bundled code in the app runtime.
+- Any execution must remain sandboxed and approval-gated (ADR-0010).
+- Do not leak Blob URLs/pathnames to clients (public-only storage).
+
+## Decision Drivers
+
+- High leverage: reuse skills.sh registry and GitHub-hosted skills.
+- Strong security: no runtime `npx` or repo writes; strict size/SSRF guardrails.
+- Maintainability: simple contracts, minimal new surface area, strict TS.
+- UX: install/update/uninstall from the project Skills tab.
+
+## Alternatives Considered
+
+### A. Run `npx skills add/remove` in app runtime
+
+Pros:
+
+- Matches the official CLI behavior.
+
+Cons:
+
+- Unacceptable supply-chain risk (runtime package execution).
+- Operational complexity (filesystem writes, caching, cleanup).
+- Conflicts with serverless tracing + immutable deployments.
+
+### B. Run `npx skills` inside Vercel Sandbox
+
+Pros:
+
+- Isolation from app runtime.
+
+Cons:
+
+- Still requires package execution (supply chain + allowlist complexity).
+- Introduces a new control plane (tokens, policy, caching, output validation).
+- Harder UX (async installs, logs, retries) for a first iteration.
+
+### C. Use skills.sh search + GitHub archive ingestion + DB/Blob bundles (**Chosen**)
+
+Pros:
+
+- No runtime package execution.
+- Deterministic parsing: resolve `SKILL.md` by frontmatter `name`.
+- Files for `skills.readFile` are supported via a bundle ZIP stored in Blob.
+- Fits existing precedence model (DB overrides FS).
+
+Cons:
+
+- Requires careful bounds (archive size, bundle limits).
+- Update semantics are “reinstall” (no pinning/version UI yet).
+
+### D. Write skills into repo directories from the UI
+
+Pros:
+
+- Skills become part of the repo skill library.
+
+Cons:
+
+- Not compatible with serverless/immutable deploys.
+- Requires RepoOps + PR flows (large scope, high risk for this feature).
+
+## Decision Framework (must be ≥ 9.0)
+
+Weights:
+
+- Solution leverage: 35%
+- Application value: 30%
+- Maintenance and cognitive load: 25%
+- Architectural adaptability: 10%
+
+| Option | Leverage | Value | Maintenance | Adaptability | Weighted total |
+| --- | ---: | ---: | ---: | ---: | ---: |
+| A. Runtime `npx skills` | 6.5 | 7.5 | 3.0 | 5.5 | 5.74 |
+| B. Sandbox `npx skills` | 7.8 | 8.6 | 7.0 | 8.2 | 7.85 |
+| C. Search API + GitHub zip + DB/Blob bundles | 9.4 | 9.3 | 8.8 | 9.0 | **9.16** |
+| D. Repo write/PR-based installs | 6.8 | 7.2 | 5.6 | 8.6 | 6.70 |
+
+## Decision
+
+Implement registry management as:
+
+1. Search via `skills.sh/api/search`.
+2. Install/update via a **Workflow DevKit** workflow:
+   - Download GitHub archive ZIP (`main` → `master` fallback).
+   - Resolve the chosen skill by matching `SKILL.md` frontmatter `name` to the
+     requested `skillId`.
+   - Bundle the skill directory into a ZIP and upload to Vercel Blob.
+   - Upsert the skill into `project_skills` with server-only metadata
+     referencing the registry id and bundle blob pathname.
+3. Uninstall deletes the DB record and best-effort deletes the bundle blob.
+4. `skills.readFile` supports DB skills **only when** they have a valid bundle
+   reference.
+
+Details and file-level contracts are defined in:
+
+- [SPEC-0028](../spec/SPEC-0028-skills-registry-ui-and-bundled-installs.md)
+- [SPEC-0027](../spec/SPEC-0027-agent-skills-runtime-integration.md)
+
+## Consequences
+
+### Positive outcomes
+
+- Users can install skills from the UI without redeploying or editing the repo.
+- Read-only file access works for installed skills (bundled ZIP).
+- Avoids runtime `npx` execution and keeps the app runtime minimal.
+
+### Negative outcomes / risks
+
+- GitHub archive downloads can fail/rate-limit.
+  - Mitigation: optional `GITHUB_TOKEN`, strict timeouts, durable retries.
+- Public-only Blob means bundles must be treated as sensitive.
+  - Mitigation: never send blob URLs/pathnames to clients; redact metadata.
+
+## Changelog
+
+- **0.1 (2026-02-09)**: Initial version. Implemented as part of SPEC-0028.

docs/architecture/adr/ADR-0029-skills-registry-integration-ui-installs-and-bundled-db-files.md

@@ -25,6 +25,8 @@
 - [ADR-0023](./ADR-0023-public-signup-deferred-until-byok.md) — Public sign-up deferred until BYOK (deferred)
 - [ADR-0026](./ADR-0026-orchestration-vercel-workflow-devkit-for-interactive-runs.md) — Orchestration: Vercel Workflow DevKit for interactive runs (QStash for background jobs)
 - [ADR-0027](./ADR-0027-preview-resource-governance-for-bot-branches-vercel-neon.md) — Preview resource governance for bot branches (Vercel + Neon) (Implemented)
+- [ADR-0028](./ADR-0028-agent-skills-progressive-disclosure-hybrid-fs-db.md) — Agent Skills progressive disclosure (hybrid filesystem + DB) (Implemented)
+- [ADR-0029](./ADR-0029-skills-registry-integration-ui-installs-and-bundled-db-files.md) — Skills registry integration (skills.sh) with UI installs + bundled DB skill files (Implemented)
 
 ## Implementation & deployment automation