Comprehensive development rules for Agent Portal - an enterprise AI platform. Covers service management, testing protocols, code patterns, and best practices for FastAPI backend, SvelteKit frontend, Docker orchestration, and GenAI monitoring.
This skill has safety concerns that you should review before use. Some patterns were detected that may pose a risk.Safety score: 60/100.
KillerSkills scans all public content for safety. Use caution before installing or executing flagged content.
You are an AI coding assistant working on Agent Portal, an enterprise agentic AI platform for building, deploying, monitoring, and governing AI agents.
**Plan → Code → Test → Complete**
Code alone is NOT complete. You MUST test before marking any TODO as done.
**Testing Procedure:**
1. **Backend API**: Test with `curl http://localhost:8000/api/...`
2. **Frontend/UI**: Use browser MCP tools to test in actual browser
3. **Integration**: Test full user flow end-to-end
**Browser Testing (REQUIRED for UI Changes):**
**Completion Flow:**
```
1. Write/modify code
2. Restart service if needed
3. Execute actual test (curl for backend, browser tools for frontend)
4. Verify result
5. ✅ No errors → Mark complete
6. ❌ Errors → Fix and retry from step 2
```
**NEVER:**
**Safe Practices:**
**Pre-Code Checklist (MANDATORY):**
Before writing ANY new function/component:
1. Search codebase for similar functionality (`grep` for keywords)
2. Check if existing code can be used, extended, or wrapped
3. If creating new, document why existing code can't be reused
**Reuse Criteria:**
**Prohibited:**
```
❌ Creating fetchData2() when fetchData() exists
❌ Duplicate modal components
❌ Copy-paste with minor modifications
```
**Correct:**
```
✅ Import and use existing utilities
✅ Extend functions with optional parameters
✅ Create shared components, import everywhere
```
**Priority 1 — Domain Rules (`.cursor/rules/*.mdc`):**
**Priority 2 — Project Docs:**
**Priority 3 — Skills (On-Demand):**
**Always restart services in this order:**
```
Layer 1: Infrastructure (mariadb, redis)
↓ wait 10s
Layer 2: Core Services (litellm, kong, kong-db)
↓ wait 10s
Layer 3: Observability (otel-collector, clickhouse, prometheus, langfuse)
↓ wait 10s
Layer 4: Application (backend, chromadb, minio)
↓ wait 5s
Layer 5: Frontend (webui)
```
**Before restart:**
```bash
./scripts/health-check.sh
cat .cursor/state/services.json | jq '.services'
```
**Single service restart:**
```bash
./scripts/pre-build.sh backend
docker compose restart backend
./scripts/health-check.sh
```
**Service rebuild:**
```bash
./scripts/pre-build.sh backend
docker compose build --no-cache backend
docker compose up -d backend
./scripts/health-check.sh
```
**On failure:**
```bash
./scripts/rollback.sh latest
```
| Service | Port | Role | Health Check |
|---------|------|------|--------------|
| backend | 8000 | FastAPI BFF | http://localhost:8000/docs |
| webui | 3001 | Portal UI | http://localhost:3001 |
| litellm | 4000 | LLM Proxy | http://localhost:4000/health |
| clickhouse | 8124 | Monitoring | http://localhost:8124/ping |
| kong | 8002 | API Gateway | http://localhost:8002/status |
| mariadb | 3306 | App Database | - |
| redis | 6379 | Cache | - |
**Before starting:**
**During development:**
**After completion:**
**Before starting:**
**During development:**
**After completion:**
**MariaDB:**
```bash
docker compose exec mariadb mariadb -uroot -prootpass agent_portal \
-e "DESCRIBE table_name;"
docker compose exec mariadb mariadb -uroot -prootpass agent_portal \
-e "ALTER TABLE table_name ADD column_name VARCHAR(255);"
```
**ClickHouse (Monitoring):**
```bash
docker compose exec monitoring-clickhouse clickhouse-client \
--query "DESCRIBE otel_2.otel_traces"
WHERE ResourceAttributes['project_id'] = 'value'
WHERE project_id = 'value'
```
```bash
lsof -i :8000
lsof -i :3001
kill -9 <PID>
```
```bash
docker compose ps
docker compose logs <service> --tail=100
docker compose up -d --force-recreate <service>
docker compose build --no-cache <service>
docker compose up -d <service>
```
```javascript
// ❌ WRONG: Direct call
fetch('http://localhost:8000/api/...')
// ✅ CORRECT: Use Vite proxy
fetch('/api/...')
```
Check `webui/vite.config.ts` for proxy configuration.
```python
app.include_router(example_router, prefix="/example")
docker compose exec backend cat /app/app/main.py | grep include_router
docker compose build --no-cache backend
docker compose up -d backend
```
```python
from fastapi import APIRouter, HTTPException, Depends
from typing import Optional
import asyncio
router = APIRouter()
@router.get("/endpoint")
async def get_data(
param: str,
timeout: int = 30
) -> dict:
try:
result = await asyncio.wait_for(
fetch_data(param),
timeout=timeout
)
return result
except asyncio.TimeoutError:
raise HTTPException(status_code=504, detail="Request timeout")
except Exception as e:
raise HTTPException(status_code=500, detail=str(e))
```
```svelte
<script lang="ts">
import { onMount } from 'svelte';
let data: DataType | null = null;
let loading = false;
let error: string | null = null;
onMount(async () => {
try {
loading = true;
// ✅ Use proxy path
const response = await fetch('/api/endpoint');
if (!response.ok) throw new Error('Failed to fetch');
data = await response.json();
} catch (e) {
error = e.message;
} finally {
loading = false;
}
});
</script>
<!-- Support dark/light mode with Tailwind classes -->
<div class="bg-white dark:bg-gray-800">
{#if loading}
<p>Loading...</p>
{:else if error}
<p class="text-red-500">{error}</p>
{:else if data}
<!-- Render data -->
{/if}
</div>
```
**Ask user when:**
**Proceed autonomously when:**
**Patch (default for bug fixes):**
**Refactor (only when requested):**
After completing significant tasks:
1. **Test before complete** — Use curl for backend, browser MCP tools for frontend
2. **Protect sensitive data** — Never expose credentials
3. **Reuse before creating** — Search codebase thoroughly first
4. **Follow service order** — Respect dependency chain when restarting
5. **Reference domain rules** — Check `.cursor/rules/*.mdc` before implementing
6. **Use browser tools** — Mandatory testing for all UI changes
7. **Handle errors properly** — Timeouts, HTTPException, try-catch
8. **Ask when uncertain** — Better to clarify than break functionality
Remember: **Plan → Code → Test → Complete**. Never skip the testing step.
Leave a review
No reviews yet. Be the first to review this skill!
# Download SKILL.md from killerskills.ai/api/skills/agent-portal-development-guidelines/raw