Skill Architecture

This document describes the three-component architecture used to build domain skills in Skillful-Alhazen.

Overview

A skill in Skillful-Alhazen is a complete vertical slice that enables an agent to work with a specific knowledge domain (job hunting, literature review, etc.). Each skill consists of three interconnected components and includes portability features to work across multiple AI agent frameworks:

┌─────────────────────────────────────────────────────────────────────────────┐
│                         SKILL ARCHITECTURE                                  │
├─────────────────────────────────────────────────────────────────────────────┤
│                                                                             │
│   (A) TypeDB Schema              (B) Skill Definition        (C) Dashboard  │
│   ┌──────────────┐              ┌──────────────────┐        ┌────────────┐  │
│   │   <domain>   │              │ SKILL.md/USAGE.md│        │  Next.js   │  │
│   │     .tql     │◄────────────►│  <domain>.py     │◄──────►│   Pages    │  │
│   └──────────────┘              └──────────────────┘        └────────────┘  │
│         │                              │                          │         │
│         ▼                              ▼                          ▼         │
│   Defines types,               Commands for                 Visual UI for   │
│   attributes,                  ingestion, query,            pipeline views, │
│   relations                    sensemaking                  matrices, etc.  │
│                                                                             │
└─────────────────────────────────────────────────────────────────────────────┘

Component	Location	Purpose
TypeDB Schema	`local_resources/typedb/namespaces/<domain>.tql`	Data model (entities, attributes, relations)
Skill Definition	`.claude/skills/<domain>/SKILL.md` + `USAGE.md` + `<domain>.py`	Agent's interface and CLI script
Dashboard (optional)	`dashboard/src/app/` + `dashboard/src/lib/`	Web UI for visualization and interaction

Component Details

(A) TypeDB Schema

The schema defines the data model for your domain. It extends the core Alhazen notebook schema with domain-specific types.

Location: local_resources/typedb/namespaces/<domain>.tql

What it defines:

Attributes - Properties (strings, numbers, dates)
Entities - Things, Artifacts, Fragments, Notes (domain subtypes)
Relations - How entities connect

Example (jobhunt.tql):

define

# Attributes
job-url sub attribute, value string;
salary-range sub attribute, value string;
application-status sub attribute, value string;

# Entities - Things
jobhunt-company sub research-item,
    owns company-url,
    plays position-at-company:employer;

jobhunt-position sub research-item,
    owns job-url,
    owns salary-range,
    plays position-at-company:position;

# Artifacts
jobhunt-job-description sub artifact;

# Fragments
jobhunt-requirement sub fragment,
    owns skill-name,
    owns skill-level;

# Notes
jobhunt-fit-analysis-note sub note,
    owns fit-score,
    owns fit-summary;

# Relations
position-at-company sub relation,
    relates position,
    relates employer;

Design principles:

Extend core types (research-item, artifact, fragment, note)
Prefix all types with <domain>- for namespace isolation
Keep the schema focused on structure, not business logic

Reference: See Design Concepts for the Alhazen data model (Collection, Thing, Artifact, Fragment, Note).

(B) Skill Definition (SKILL.md + USAGE.md + Script)

The skill definition has three parts:

SKILL.md - Trigger conditions and brief command overview, loaded at startup
USAGE.md - Full step-by-step instructions, loaded when executing the skill
Python script - CLI tool that handles TypeDB operations

Location: .claude/skills/<domain>/

SKILL.md

Loaded into the agent's context at startup — kept intentionally short. OpenClaw loads all registered SKILL.md files on every session, so long files would bloat the context even for unrelated tasks.

Tells the agent:

When to use the skill (triggers)
Brief command overview

Structure:

---
name: <domain>
description: One-line description
---

# <Domain> Skill

## When to Use
## Quick Command Reference

USAGE.md

Loaded on demand, when the agent is actually executing the skill. Contains everything needed to carry out the full workflow.

Structure:

# <Domain> Usage

## Prerequisites
## Sensemaking Workflow (Agent reasoning steps)
## Detailed Command Reference
## Data Model
## TypeQL Examples

Python Script

Handles all TypeDB operations. The agent calls this script; the script talks to TypeDB.

Key design principles:

JSON output to stdout (for parsing)
Errors/progress to stderr
argparse subcommands for each operation
No parsing/sensemaking - scripts do data operations, the agent does reasoning

Script structure:

#!/usr/bin/env python3
"""Domain CLI - Description."""

import argparse
import json
from typedb.driver import TypeDB, SessionType, TransactionType

# Configuration
TYPEDB_HOST = os.getenv("TYPEDB_HOST", "localhost")
TYPEDB_DATABASE = os.getenv("TYPEDB_DATABASE", "alhazen_notebook")

def cmd_ingest(args):
    """Fetch and store raw content."""
    # ... TypeDB insert operations ...
    print(json.dumps({"success": True, "id": entity_id}))

def cmd_list(args):
    """Query and return entities."""
    # ... TypeDB fetch operations ...
    print(json.dumps({"success": True, "items": [...]}))

def main():
    parser = argparse.ArgumentParser()
    subparsers = parser.add_subparsers(dest="command")
    # ... define subcommands ...
    commands[args.command](args)

if __name__ == "__main__":
    main()

Separation of concerns:

Script Does	Agent Does
Fetch URLs	Read and comprehend content
Store raw artifacts	Extract entities and relations
Run TypeDB queries	Create notes with analysis
Return JSON data	Reason across multiple notes

(C) Dashboard (Optional)

Visual web interface for data exploration. Not all skills need a dashboard. See Dashboard Organization for the full directory layout and conventions.

Location:

API routes: dashboard/src/app/api/<domain>/
Pages: dashboard/src/app/(<domain>)/<domain>/ (using Next.js route groups)
Components: dashboard/src/components/<domain>/
Client library: dashboard/src/lib/<domain>.ts

Dashboard Architecture

┌────────────────────────────────────────────────────────────────────┐
│                        DASHBOARD LAYER                              │
├────────────────────────────────────────────────────────────────────┤
│                                                                     │
│   Browser                    Next.js Server                         │
│   ┌──────────┐              ┌──────────────┐     ┌────────────┐    │
│   │  React   │──HTTP GET───►│  API Route   │────►│  lib/*.ts  │    │
│   │  Pages   │◄─────JSON────│  /api/...    │◄────│   (calls   │    │
│   └──────────┘              └──────────────┘     │   script)  │    │
│                                                   └────────────┘    │
│                                                         │           │
│                                                         ▼           │
│                                              ┌──────────────────┐   │
│                                              │  uv run python   │   │
│                                              │  <domain>.py     │   │
│                                              │    --command     │   │
│                                              └──────────────────┘   │
│                                                         │           │
│                                                         ▼           │
│                                              ┌──────────────────┐   │
│                                              │     TypeDB       │   │
│                                              └──────────────────┘   │
└────────────────────────────────────────────────────────────────────┘

Client Library (`lib/<domain>.ts`)

Wraps script calls for use by API routes:

import { exec } from 'child_process';

async function runCommand(args: string[]): Promise<CommandResult> {
  const cmd = `uv run python "${SCRIPT_PATH}" ${args.join(' ')}`;
  const { stdout } = await execAsync(cmd);
  return JSON.parse(stdout);
}

export async function listPipeline(filters?: {...}) {
  const args = ['list-pipeline'];
  if (filters?.status) args.push('--status', filters.status);
  return runCommand(args);
}

API Routes

Thin wrappers that call the client library:

// app/api/<domain>/route.ts
import { NextRequest, NextResponse } from 'next/server';
import { listPipeline } from '@/lib/<domain>';

export async function GET(request: NextRequest) {
  const data = await listPipeline();
  return NextResponse.json(data);
}

Common Dashboard Views

View Type	Purpose	Example
Pipeline/Kanban	Track items through stages	Job applications by status
Matrix	Compare across dimensions	Skills × Positions
List + Detail	Browse and drill down	Papers in collection
Progress	Track completion	Learning plan
Stats/Cards	Key metrics	Fit scores, counts

How Components Connect

USER REQUEST
     │
     ▼
┌─────────────────────────────────────────────────────────────────┐
│                          AGENT                                   │
│  1. Reads SKILL.md to understand available commands             │
│  2. Calls script commands for data operations                   │
│  3. Performs sensemaking (reasoning, note creation)             │
│  4. Reports findings to user                                    │
└─────────────────────────────────────────────────────────────────┘
     │                                        │
     ▼                                        ▼
┌──────────────┐                    ┌──────────────────┐
│ Python Script │                    │ Dashboard        │
│ <domain>.py  │                    │ (for visual      │
│              │                    │  exploration)    │
└──────────────┘                    └──────────────────┘
     │                                        │
     └───────────────────┬────────────────────┘
                         ▼
              ┌──────────────────┐
              │     TypeDB       │
              │                  │
              │   Schema from    │
              │   <domain>.tql   │
              └──────────────────┘

Data flow:

Ingestion: Script fetches raw content → stores as Artifact in TypeDB
Sensemaking: Agent reads Artifact → creates Fragments and Notes in TypeDB (via script)
Query: Script queries TypeDB → returns JSON to Agent/Dashboard
Display: Dashboard calls script → renders in React components

Creating a New Skill

Checklist

Design the data model
- What entities do you track? (Map to Thing, Artifact, Fragment, Note)
- What attributes do they have?
- How do they relate?
Create the schema (local_resources/typedb/namespaces/<domain>.tql)
- Define attributes
- Define entity subtypes
- Define relations
- Load into TypeDB
Create the skill directory (.claude/skills/<domain>/)
Write the script (<domain>.py)
- Ingestion commands (fetch, store raw)
- Query commands (list, show)
- Update commands (status, tags)
- Output JSON, errors to stderr
Write SKILL.md (short — loaded at startup)
- Frontmatter (name, description)
- Trigger conditions
- Brief command overview
Write USAGE.md (full — loaded on demand)
- Philosophy/pattern explanation
- Prerequisites
- Detailed command reference
- Sensemaking workflow
- Data model summary
Test the skill
- Manual CLI commands work
- The agent can invoke via skill
(Optional) Create dashboard
- Client library in lib/<domain>.ts
- API routes in app/api/<domain>/
- UI components

Template

A skill template is available at .claude/skills/_template/ with:

SKILL.md - Short trigger/overview boilerplate
USAGE.md - Full workflow boilerplate
template.py - Script boilerplate
schema.tql - TypeDB schema template
README.md - Usage instructions

Examples

Full-Stack Skill: Jobhunt

The jobhunt skill demonstrates all three components:

Component	File	Description
Schema	`local_resources/typedb/namespaces/jobhunt.tql`	Company, Position, Requirements, Notes
SKILL.md	`.claude/skills/jobhunt/SKILL.md`	Curation workflow, commands
Script	`.claude/skills/jobhunt/jobhunt.py`	20+ commands for job tracking
Dashboard	`dashboard/src/app/`	Pipeline, Skills Matrix, Learning Plan

Testing

Schema Testing

# Start TypeDB
docker compose -f docker-compose-typedb.yml up -d

# Load schema (in TypeDB console)
docker exec -it alhazen-typedb /opt/typedb-all-linux-x86_64/typedb console

> database create test_db
> transaction test_db schema write
> source /schema/alhazen_notebook.tql
> commit
> transaction test_db schema write
> source /schema/namespaces/<domain>.tql
> commit

Script Testing

# Test individual commands
uv run python .claude/skills/<domain>/<domain>.py --help
uv run python .claude/skills/<domain>/<domain>.py <command> --help
uv run python .claude/skills/<domain>/<domain>.py <command> [args]

# Run Python tests
uv run pytest tests/test_<domain>.py -v

Dashboard Testing

cd dashboard
npm install
npm run dev
# Open http://localhost:3000

Uh oh!

Skill Architecture

Skill Architecture

Overview

Component Details

(A) TypeDB Schema

(B) Skill Definition (SKILL.md + USAGE.md + Script)

SKILL.md

USAGE.md

Python Script

(C) Dashboard (Optional)

Dashboard Architecture

Client Library (lib/<domain>.ts)

API Routes

Common Dashboard Views

How Components Connect

Creating a New Skill

Checklist

Template

Examples

Full-Stack Skill: Jobhunt

Testing

Schema Testing

Script Testing

Dashboard Testing

Related Documentation

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Clone this wiki locally

Client Library (`lib/<domain>.ts`)