skill-registry

Files (1)

• SKILL.md

SKILL.md (first lines)

# Skill Registry — Dynamic Skill Discovery

This skill enables **Pi** to use `js-doc-store-server` as a dynamic skill registry. Instead of keeping dozens of `SKILL.md` files scattered in `~/.agents/skills/`, only **one** meta-skill lives on the filesystem. All functional skills are stored in the `skills` table and discovered on-demand via tag-based queries.

## Problem with Static Filesystem Skills

| Issue | Consequence |
|-------|-------------|
| Pi loads **all** `SKILL.md` files at startup | Massive context overload |
| No search by topic | Must know exact filename |
| No versioning | Skills evolve but files don't track it |
| Multi-session portability | Files are local to one machine |
| No semantic discovery | Can't find "CRM" skill via "customer" query |

## The Registry Pattern

```
Filesystem (~/.agents/skills/)
└── skill-discovery/SKILL.md    ← SINGLE skill on disk

js-doc-store-server (localhost:3000)
└── table: skills
    ├── data-architect     → content: full SKILL.md
    ├── tree-operator      → content: full SKILL.md
    ├── vps-management     → content: full SKILL.md
    ├── github-management  → content: full SKILL.md
    └── ... (any skill)
```

## Schema

Register this table in your `js-doc-store-server`:

```json
{
  "tableName": "skills",
  "columns": [
    { "name": "name",        "type": "text", "required": true },
    { "name": "version",     "type": "text" },
    { "name": "tags",        "type": "text" },
    { "name": "description", "type": "text" },
    { "name": "content",     "type": "text", "required": true }
  ]
}
```

## Workflow

### 1. One-Time Setup (per Pi installation)

Create the `skills` table:

```bash
TOKEN=$(pi auth login --output-token)

pi tools call arch_create_table --params '{
  "tableName": "skills",
  "columns": [
    {"name":"name","type":"text","required":true},
    {"name":"version","type":"text"},
    {"name":"tags","type":"text"},
    {"name":"description","type":"text"},
    {"name":"content","type":"text","required":true}
  ]
}'
```

Keep **only** `skill-discovery/SKILL.md` in `~/.agents/skills/`. Delete all other filesystem skills.

### 2. Register Existing Skills

For every `SKILL.md` you have:

```bash
# Read file content
CONTENT=$(cat ~/.agents/skills/my-skill/SKILL.md)

# Insert into registry
pi tools call arch_insert --params '{
  "tableName": "skills",
  "data": {
    "name": "my-skill",
    "version": "1.0.0",
    "tags": "tag1,tag2,topic",
    "description": "Brief description for listings",
    "content": "'"$CONTENT"'"
  }
}'
```

Or use the `skill-registry.js` helper script (see `examples/` in this extension).

### 3. Discovery by User Intent

When the user says:
- *"I need a CRM"* → query tags with `$regex: "crm"`
- *"How do I deploy to my VPS?"* → query tags with `$regex: "vps|deploy"`
- *"Set up RAG"* → query tags with `$regex: "rag"`

```typescript
const results = await arch_query({
  tableName: "skills",
  filter: { tags: { $regex: "vps" } }
});
// Inject results[0].content into prompt context
```

### 4. Retrieve Full Skill Content

```typescript
const skill = await arch_query({
  tableName: "skills",
  filter: { name: "vps-management" }
});
// skill.data[0].content === complete markdown text
```

### 5. Register New Skill from Conversation

From MauricioPerera/pi-extension-data-architect, MIT.

More from MauricioPerera/pi-extension-data-architect