Project Onboarding Skill Skill

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

Agent Skills: Project Onboarding Skill

Install this agent skill to your local

Skill Files