registry.query

What this skill does

# registry.query

**Version:** 0.1.0
**Status:** Active
**Tags:** registry, search, query, discovery, metadata, cli

## Overview

The `registry.query` skill enables programmatic searching of Betty registries (skills, agents, and commands) with flexible filtering capabilities. It's designed for dynamic discovery, workflow automation, and CLI autocompletion.

## Features

- **Multi-Registry Support**: Query skills, agents, commands, or hooks registries
- **Flexible Filtering**: Filter by name, version, status, tags, domain, and capability
- **Fuzzy Matching**: Optional fuzzy search for name and capability fields
- **Result Limiting**: Control the number of results returned
- **Rich Metadata**: Returns key metadata for each matching entry
- **Multiple Output Formats**: JSON, table, or compact format for different use cases
- **Table Formatting**: Aligned column display for easy CLI viewing

## Usage

### Command Line

```bash
# List all skills (compact format, default)
python3 skills/registry.query/registry_query.py skills

# Find skills with 'api' tag in table format
python3 skills/registry.query/registry_query.py skills --tag api --format table

# Find agents with 'design' capability
python3 skills/registry.query/registry_query.py agents --capability design

# Query hooks registry
python3 skills/registry.query/registry_query.py hooks --status active --format table

# Find active skills with name containing 'validate'
python3 skills/registry.query/registry_query.py skills --name validate --status active

# Fuzzy search for commands
python3 skills/registry.query/registry_query.py commands --name test --fuzzy

# Limit results to top 5
python3 skills/registry.query/registry_query.py skills --tag api --limit 5

# Get full JSON output
python3 skills/registry.query/registry_query.py skills --tag validation --format json
```

### Programmatic Use

```python
from skills.registry.query.registry_query import query_registry

# Query skills with API tag
result = query_registry(
    registry="skills",
    tag="api",
    status="active"
)

if result["ok"]:
    matching_entries = result["details"]["results"]
    for entry in matching_entries:
        print(f"{entry['name']}: {entry['description']}")
```

### Betty CLI

```bash
# Via Betty CLI (when registered)
betty registry query skills --tag api
betty registry query agents --capability "API design"
```

## Parameters

### Required

- **`registry`** (string): Registry to query
  - Valid values: `skills`, `agents`, `commands`, `hooks`

### Optional Filters

- **`name`** (string): Filter by name (substring match, case-insensitive)
- **`version`** (string): Filter by exact version match
- **`status`** (string): Filter by status (e.g., `active`, `draft`, `deprecated`, `archived`)
- **`tag`** (string): Filter by single tag
- **`tags`** (array): Filter by multiple tags (matches any)
- **`capability`** (string): Filter by capability (agents only, substring match)
- **`domain`** (string): Filter by domain (alias for tag filter)
- **`fuzzy`** (boolean): Enable fuzzy matching for name and capability
- **`limit`** (integer): Maximum number of results to return
- **`format`** (string): Output format (`json`, `table`, `compact`)
  - `json`: Full JSON response with all metadata
  - `table`: Aligned column table for easy reading
  - `compact`: Detailed list format (default)

## Output Format

### Success Response

```json
{
  "ok": true,
  "status": "success",
  "errors": [],
  "timestamp": "2025-10-23T10:30:00.000000Z",
  "details": {
    "registry": "skills",
    "query": {
      "name": "api",
      "version": null,
      "status": "active",
      "tags": ["validation"],
      "capability": null,
      "domain": null,
      "fuzzy": false,
      "limit": null
    },
    "total_entries": 21,
    "matching_entries": 3,
    "results": [
      {
        "name": "api.validate",
        "version": "0.1.0",
        "description": "Validates OpenAPI or AsyncAPI specifications...",
        "status": "active",
        "tags": ["api", "validation", "openapi", "asyncapi"],
        "dependencies": ["context.schema"],
        "entrypoints": [
          {
            "command": "/api/validate",
            "runtime": "python",
            "description": "Validate API specification files"
          }
        ],
        "inputs": [...],
        "outputs": [...]
      }
    ]
  }
}
```

### Error Response

```json
{
  "ok": false,
  "status": "failed",
  "errors": ["Invalid registry: invalid_type"],
  "timestamp": "2025-10-23T10:30:00.000000Z"
}
```

## Metadata Fields by Registry Type

### Skills

- `name`, `version`, `description`, `status`, `tags`
- `dependencies`: List of required skills
- `entrypoints`: Available commands and handlers
- `inputs`: Expected input parameters
- `outputs`: Generated outputs

### Agents

- `name`, `version`, `description`, `status`, `tags`
- `capabilities`: List of agent capabilities
- `skills_available`: Skills the agent can invoke
- `reasoning_mode`: `oneshot` or `iterative`
- `context_requirements`: Required context fields

### Commands

- `name`, `version`, `description`, `status`, `tags`
- `execution`: Execution configuration (type, target)
- `parameters`: Command parameters

### Hooks

- `name`, `version`, `description`, `status`, `tags`
- `event`: Hook event trigger (e.g., on_file_edit, on_commit)
- `command`: Command to execute
- `enabled`: Whether the hook is enabled

## Use Cases

### 1. Dynamic Discovery

Find skills related to a specific domain:

```bash
python3 skills/registry.query/registry_query.py skills --domain api
```

### 2. Workflow Automation

Programmatically find and invoke skills:

```python
# Find validation skills
result = query_registry(registry="skills", tag="validation", status="active")

for skill in result["details"]["results"]:
    print(f"Found validation skill: {skill['name']}")
    # Invoke skill programmatically
```

### 3. CLI Autocompletion

Generate autocompletion data:

```python
# Get all active skill names for tab completion
result = query_registry(registry="skills", status="active")
skill_names = [s["name"] for s in result["details"]["results"]]
```

### 4. Dependency Resolution

Find skills with specific dependencies:

```python
result = query_registry(registry="skills", status="active")
for skill in result["details"]["results"]:
    if "context.schema" in skill.get("dependencies", []):
        print(f"{skill['name']} depends on context.schema")
```

### 5. Capability Search

Find agents by capability:

```bash
python3 skills/registry.query/registry_query.py agents --capability "API design"
```

### 6. Hooks Management

Query and monitor hooks:

```bash
# List all hooks in table format
python3 skills/registry.query/registry_query.py hooks --format table

# Find hooks by event type
python3 skills/registry.query/registry_query.py hooks --tag commit

# Find enabled hooks
python3 skills/registry.query/registry_query.py hooks --status active
```

### 7. Status Monitoring

Find deprecated or draft entries:

```bash
python3 skills/registry.query/registry_query.py skills --status deprecated
python3 skills/registry.query/registry_query.py skills --status draft
```

## Future Extensions

The skill is designed with these future enhancements in mind:

1. **Advanced Fuzzy Matching**: Implement more sophisticated fuzzy matching algorithms (e.g., Levenshtein distance)
2. **Full-Text Search**: Search within descriptions and documentation
3. **Dependency Graph**: Query dependency relationships between skills
4. **Version Ranges**: Support semantic version range queries (e.g., `>=1.0.0,<2.0.0`)
5. **Sorting Options**: Sort results by name, version, or relevance
6. **Regular Expression Support**: Use regex patterns for advanced filtering
7. **Marketplace Integration**: Query marketplace catalogs with certification status
8. **Performance Caching**: Cache registry data for faster repeated queries

## Examples

### Example 1: Find all API-related skills in table format

```bash
$ python3