personal-ai-assistant/plans/phase-3-skills-context.md

Phase 3: Skills & Context — Subplan

Goal

Deliver a skill system (general + personal) with CRUD, a personal context editor per user, and context assembly that layers personal context and skill prompts into AI conversations, with frontend management pages and a skill selector in chat.

Prerequisites

• Phase 2 completed: chat CRUD, SSE streaming, Claude API integration, context assembly, admin context editor
• context_files table already exists (Phase 2 migration)
• chats.skill_id column already exists (nullable, Phase 2)

---

Database Schema (Phase 3)

skills table (new)

Column	Type	Constraints
id	UUID	PK (inherited from Base)
user_id	UUID	FK -> users.id ON DELETE CASCADE, NULL = general skill
name	VARCHAR(100)	NOT NULL
description	TEXT	NULL
system_prompt	TEXT	NOT NULL
icon	VARCHAR(50)	NULL (Lucide icon name)
is_active	BOOLEAN	NOT NULL, default true
sort_order	INTEGER	NOT NULL, default 0
created_at	TIMESTAMPTZ	inherited from Base

Also: add FK constraint chats.skill_id -> skills.id ON DELETE SET NULL.

---

Tasks

A. Backend Model & Migration (Tasks 1–3)

• A1. Create backend/app/models/skill.py. Add skills relationship on User model. Add skill relationship on Chat model.
• A2. Update backend/app/models/__init__.py: import Skill.
• A3. Create migration 003_create_skills_add_chat_skill_fk.py.

B. Backend Schemas (Task 4)

• B4. Create backend/app/schemas/skill.py. Extend CreateChatRequest/UpdateChatRequest with optional skill_id.

C. Backend Services (Tasks 5–7)

• C5. Create backend/app/services/skill_service.py: CRUD for personal + general skills with access checks.
• C6. Extend context_service.py: add get_personal_context, upsert_personal_context.
• C7. Extend ai_service.py assemble_context: add personal context (step 2) + skill prompt (step 3).

D. Backend API Endpoints (Tasks 8–11)

• D8. Create backend/app/api/v1/skills.py: personal skills CRUD.
• D9. Extend backend/app/api/v1/admin.py: admin skills CRUD under /admin/skills/.
• D10. Create backend/app/api/v1/users.py: GET/PUT /users/me/context.
• D11. Update router, chats endpoints (skill_id validation on create/update).

E. Frontend API (Tasks 12–13)

• E12. Create frontend/src/api/skills.ts + extend admin.ts with admin skill functions.
• E13. Create frontend/src/api/user-context.ts.

F. Frontend Skill Selector (Tasks 14–15)

• F14. Create frontend/src/components/chat/skill-selector.tsx.
• F15. Update chat creation + chat window to support skill_id.

G. Frontend Admin Skills (Tasks 16–17)

• G16. Create frontend/src/components/admin/skill-editor.tsx (reusable form).
• G17. Create frontend/src/pages/admin/skills.tsx.

H. Frontend Personal Skills & Context (Tasks 18–19)

• H18. Create frontend/src/pages/skills.tsx.
• H19. Create frontend/src/pages/profile/context.tsx.

I. Routing, Sidebar, i18n (Tasks 20–22)

• I20. Update routes: /skills, /profile/context, /admin/skills.
• I21. Update sidebar: add Skills nav, admin skills link.
• I22. Update en/ru translations.

J. Backend Tests (Task 23)

• J23. Create backend/tests/test_skills.py.

---

Acceptance Criteria

1. Migration creates skills table and adds FK on chats.skill_id
2. Admin can CRUD general skills; users cannot
3. Users can CRUD own personal skills; isolated from other users
4. Users can read/write personal context via /users/me/context
5. Context assembly: primary context + personal context + skill prompt
6. Chat creation/update accepts skill_id, validates accessibility
7. Skill selector dropdown in chat creation and header
8. Admin skills page, personal skills page, personal context editor
9. All UI text in English and Russian
10. Backend tests pass

---

Status

COMPLETED