Skip to main content

Implementation Plan: Unified Skills API, Gateway, and Template Import

Branch: fix/skills-ai-generate-use-dynamic-agents (legacy branch; spec folder 2026-04-29-skills-api-unification)
Date: 2026-04-29
Spec: spec.md
Related engineer notes: implementation-plan.md (route map, verification checklist)

Note: Generated by /speckit.plan. Use SPECKIT_FEATURE_DIR + SPECKIT_SKIP_BRANCH_CHECK=1 when the git branch is not date-prefixed.

Summary​

Unify all CAIPE UI and documented HTTP entry points for skills under /api/skills/*, retire /api/agent-skills/*, keep catalog (GET /api/skills) separate from persisted config CRUD (/api/skills/configs). Add explicit system-only template import with deterministic IDs (skill-{slug}-{6hex}) and narrow auto-seed to at most one example. Update Skills Gateway copy and bootstrap flow so live catalog + on-demand fetch is primary; bulk install is advanced. MongoDB collection remains agent_skills. Distribution includes a real default packaged skill (incident post-mortem).

Technical Context​

Language/Version: TypeScript 5.x, Node 20+, Next.js App Router (16), React 19
Primary Dependencies: Next.js route handlers, Motor-backed patterns via existing Mongo helpers in UI (getCollection), JWT/session auth via existing API middleware
Storage: MongoDB collection agent_skills only (no new collection); chart-mounted SKILL.md + metadata.json for packaged templates
Testing: Jest + Testing Library in ui/ (npm test, npm run lint)
Target Platform: CAIPE web UI (browser + serverless/Node API routes)
Project Type: web application (Next.js frontend + API routes; supervisor Python unchanged except refresh calls)
Performance Goals: API routes remain responsive for typical CRUD; supervisor refresh stays fire-and-forget (existing 30s timeout pattern)
Constraints: Breaking URL change must be documented (FR-010); template import must not duplicate rows (FR-006); ancillary files soft limit 5 MB (existing)
Scale/Scope: All ui/src fetch sites for agent-skills; gateway components (TrySkillsGateway, bootstrap, install script); optional gallery import modal

Constitution Check​

GATE: Must pass before Phase 0 research. Re-check after Phase 1 design.

PrincipleStatus
V. Specs as source of truthPass — work traced to spec.md
VI. CI gatesPass — changes must pass npm run lint and npm test in ui/ before merge
VII. Security by defaultPass — auth middleware on mutating routes; validate bodies; no secrets in source; treat LLM/scan inputs as untrusted (existing patterns)
I–IV, coding practicesPass — extend existing types (AgentSkill); avoid speculative abstractions; reuse withAuth / withErrorHandler

Post-design re-check: Contracts in contracts/rest-api.md keep catalog vs config separation (FR-002). No new collection (FR-003). Breaking migration is explicit in release notes (FR-010). MongoDB collection rename is not part of this release — see mongodb-migration.md.

Project Structure​

Documentation (this feature)​

docs/docs/specs/2026-04-29-skills-api-unification/
├── spec.md
├── plan.md                 # This file
├── implementation-plan.md  # Detailed route map & phases
├── research.md             # Phase 0
├── data-model.md           # Phase 1
├── quickstart.md           # Phase 1
├── mongodb-migration.md    # DB: no rename for this feature; optional indexes & future rename reference
├── contracts/
│   └── rest-api.md
├── checklists/
│   └── requirements.md
└── tasks.md                # /speckit.tasks

Source Code (repository root)​

ui/src/app/api/skills/
├── route.ts                    # GET — merged catalog only (existing)
├── configs/route.ts            # CRUD — moved from agent-skills
├── seed/route.ts
├── generate/route.ts
├── import-github/route.ts
├── templates/import/route.ts   # POST — new
├── bootstrap/route.ts          # gateway artifact
└── install.sh (or route)       # as today

ui/src/store/agent-skills-store.ts
ui/src/components/skills/
charts/ai-platform-engineering/data/skills/<template>/

Structure Decision: Single Next.js ui/ app owns all new/moved routes; Python supervisor URL unchanged for refresh/scan; Helm chart data directory holds packaged templates.

Database migrations​

Storage: MongoDB agent_skills (see Technical Context). Deliverable: mongodb-migration.md (project-specific name per Speckit template; equivalent to db-migration.md).

  • Required for this release: No collection rename, no mandatory ops script; optional additive metadata.* fields on new/updated documents; optional compound index if dedupe queries need it.
  • Rollback / backup: Covered in migration doc for any future rename initiative (out of scope for this feature).
  • Link: Schema and entities in data-model.md.

Complexity Tracking​

No constitution violations requiring justification. Breaking HTTP paths are an explicit product decision (FR-001, FR-010), not speculative scope creep.

Phase 0 & 1 outputs​

  • research.md — consolidates decisions (no open NEEDS CLARIFICATION; choices align with spec + stakeholder locks).
  • data-model.md — persisted skill shape, template import metadata, catalog entry distinction.
  • contracts/rest-api.md — public HTTP contract for the UI and integrators.
  • quickstart.md — how to validate locally after implementation.
  • mongodb-migration.md — MongoDB: no agent_skills rename required; additive metadata; optional indexes; future rename appendix.
  • tasks.md — Dependency-ordered checklist for /speckit.implement.