Project Onboarding Skill

Quickly onboard a new project into the agentic workspace with RAG collections, routing rules, and baseline knowledge.

Overview

When starting work on a new project, this skill provides a systematic approach to:

Create project-specific RAG collections
Register semantic routing rules
Ingest existing documentation as baseline knowledge
Set up credentials and configuration
Validate the setup

Prerequisites

Workspace with RAG server running
Router server running
Access to the project's source code or documentation

Onboarding Steps

Step 1: Gather Project Information

Before onboarding, collect:

project: name: "project-slug" # Lowercase, hyphenated display_name: "Project Name" # Human-readable code_path: "/path/to/code" # Absolute path to source description: "Brief description of the project"

Optional

tech_stack: - python - fastapi - postgresql

docs_paths: - README.md - docs/ - ARCHITECTURE.md

Step 2: Create RAG Collections

Create isolated collections for different content types:

Collection naming convention: {project}_{content_type}

collections = [ f"{project_name}_docs", # Documentation, READMEs f"{project_name}_code", # Code snippets, patterns f"{project_name}_decisions", # ADRs, architectural decisions f"{project_name}_research", # Research findings, notes ]

Create via RAG server

for collection in collections: await rag.create_collection(collection)

Recommended collection structure:

Collection Content Metadata

{project}_docs

README, guides, API docs type: doc, source: file

{project}_code

Reusable patterns, examples type: code, language: python

{project}_decisions

ADRs, design docs type: decision, status: accepted

{project}_research

Research notes, findings type: research, topic: x

Step 3: Ingest Baseline Documentation

#!/bin/bash

scripts/onboard-docs.sh

PROJECT=$1 CODE_PATH=$2

Ingest README

if [ -f "$CODE_PATH/README.md" ]; then /ingest --collection "${PROJECT}_docs"
--source "readme"
--file "$CODE_PATH/README.md" fi

Ingest docs directory

if [ -d "$CODE_PATH/docs" ]; then find "$CODE_PATH/docs" -name "*.md" -exec
/ingest --collection "${PROJECT}_docs"
--source "docs"
--file {} ; fi

Ingest architecture docs

for doc in ARCHITECTURE.md DESIGN.md CONTRIBUTING.md; do if [ -f "$CODE_PATH/$doc" ]; then /ingest --collection "${PROJECT}_decisions"
--source "architecture"
--file "$CODE_PATH/$doc" fi done

Step 4: Register Routing Rules

Add project-specific routing so queries get directed appropriately:

routing/routes/project-{name}.yaml

routes:

name: "{project}_code_search" utterances:
- "find code in {project}"
- "search {project} for"
- "how does {project} implement"
- "{project} code pattern" action: type: rag_search collection: "{project}_code"
name: "{project}_docs_search" utterances:
- "{project} documentation"
- "how to use {project}"
- "{project} setup"
- "{project} guide" action: type: rag_search collection: "{project}_docs"
name: "{project}_decisions" utterances:
- "why did {project}"
- "{project} architecture"
- "{project} design decision" action: type: rag_search collection: "{project}_decisions"

Step 5: Create Project Configuration

config/projects/{project}.yaml

project: name: "{project}" display_name: "{Project Display Name}" code_path: "/path/to/code"

collections: docs: "{project}_docs" code: "{project}_code" decisions: "{project}_decisions" research: "{project}_research"

credentials:

Reference to .env variables

api_key: "{PROJECT}_API_KEY" database_url: "{PROJECT}_DATABASE_URL"

defaults: search_collection: "{project}_docs" search_results: 5

Step 6: Create Code Symlink

Link project code into workspace

ln -sf /path/to/actual/code ./code/{project}

Step 7: Validate Setup

#!/usr/bin/env python3 """Validate project onboarding."""

import asyncio from pathlib import Path

async def validate_onboarding(project: str): errors = []

# Check collections exist
collections = await rag.list_collections()
expected = [f"{project}_docs", f"{project}_code",
            f"{project}_decisions", f"{project}_research"]

for coll in expected:
    if coll not in [c["name"] for c in collections]:
        errors.append(f"Missing collection: {coll}")

# Check config exists
config_path = Path(f"config/projects/{project}.yaml")
if not config_path.exists():
    errors.append(f"Missing config: {config_path}")

# Check code symlink
code_path = Path(f"code/{project}")
if not code_path.exists():
    errors.append(f"Missing code symlink: {code_path}")

# Check routing rules
route_path = Path(f"routing/routes/project-{project}.yaml")
if not route_path.exists():
    errors.append(f"Missing routes: {route_path}")

# Test search works
try:
    results = await rag.search(
        query="project overview",
        collection=f"{project}_docs",
        n_results=1
    )
    if not results["results"]:
        errors.append("No documents in docs collection")
except Exception as e:
    errors.append(f"Search failed: {e}")

return errors

if name == "main": import sys project = sys.argv[1] errors = asyncio.run(validate_onboarding(project))

if errors:
    print("❌ Onboarding validation failed:")
    for e in errors:
        print(f"  - {e}")
    sys.exit(1)
else:
    print(f"✅ Project '{project}' onboarded successfully!")

Quick Onboarding Script

#!/bin/bash

scripts/onboard-project.sh

set -e

PROJECT=$1 CODE_PATH=$2 DISPLAY_NAME=${3:-$PROJECT}

if [ -z "$PROJECT" ] || [ -z "$CODE_PATH" ]; then echo "Usage: onboard-project.sh <project-slug> <code-path> [display-name]" exit 1 fi

echo "🚀 Onboarding project: $PROJECT"

Step 1: Create collections

echo "📦 Creating RAG collections..." for type in docs code decisions research; do curl -X POST "http://localhost:8100/create_collection"
-d "{"name": "${PROJECT}_${type}"}" done

Step 2: Create config

echo "⚙️ Creating project config..." cat > "config/projects/${PROJECT}.yaml" << EOF project: name: "${PROJECT}" display_name: "${DISPLAY_NAME}" code_path: "${CODE_PATH}"

collections: docs: "${PROJECT}_docs" code: "${PROJECT}_code" decisions: "${PROJECT}_decisions" research: "${PROJECT}_research" EOF

Step 3: Create code symlink

echo "🔗 Creating code symlink..." mkdir -p code ln -sf "$CODE_PATH" "code/${PROJECT}"

Step 4: Ingest docs

echo "📚 Ingesting documentation..." ./scripts/onboard-docs.sh "$PROJECT" "$CODE_PATH"

Step 5: Create routing rules

echo "🔀 Creating routing rules..." cat > "routing/routes/project-${PROJECT}.yaml" << EOF routes:

name: "${PROJECT}_search" utterances:
- "${PROJECT}"
- "search ${PROJECT}"
- "${PROJECT} code"
- "${PROJECT} docs" action: type: rag_search collection: "${PROJECT}_docs" EOF

Step 6: Validate

echo "✅ Validating..." python scripts/validate-onboarding.py "$PROJECT"

echo "🎉 Project '$PROJECT' onboarded successfully!"

Usage Examples

Onboard a Python project

./scripts/onboard-project.sh my-api ~/projects/my-api "My API Service"

Onboard with just slug and path

./scripts/onboard-project.sh client-portal ~/work/client-portal

Validate existing project

python scripts/validate-onboarding.py my-api

Post-Onboarding

After onboarding:

Ingest more content as you work:

/ingest --collection my-api_research --content "Found that..."

Refine routing rules based on actual usage patterns

Add project-specific workflows in workflows/definitions/

Troubleshooting

Issue Solution

Collections not created Check RAG server is running

Search returns nothing Verify documents were ingested

Routing not working Reload router embeddings

Code symlink broken Check absolute path is correct

Refinement Notes

Add notes here as you onboard projects and discover improvements.

Initial implementation
Tested with real project
Automated script working
Routing integration verified

project-onboarding

Safety Notice

Copy this and send it to your AI assistant to learn