# 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 skills/registry.query/registry_query.py skills --tag api --format table

================================================================================
REGISTRY QUERY: SKILLS
================================================================================

Total entries: 21
Matching entries: 5

+-------------------+---------+--------+---------------------------+-------------------------+
| Name              | Version | Status | Tags                      | Commands                |
+-------------------+---------+--------+---------------------------+-------------------------+
| api.define        | 0.1.0   | active | api, openapi, asyncapi    | /api/define             |
| api.validate      | 0.1.0   | active | api, validation, openapi  | /api/validate           |
| api.compatibility | 0.1.0   | draft  | api, compatibility        | /api/compatibility      |
| api.generate      | 0.1.0   | active | api, codegen              | /api/generate           |
| api.test          | 0.1.0   | draft  | api, testing              | /api/test               |
+-------------------+---------+--------+---------------------------+-------------------------+

================================================================================
```

### Example 2: Find all API-related skills in compact format

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

================================================================================
REGISTRY QUERY: SKILLS
================================================================================

Total entries: 21
Matching entries: 5

--------------------------------------------------------------------------------
RESULTS:
--------------------------------------------------------------------------------

1. api.define (v0.1.0)
   Status: active
   Description: Generates OpenAPI 3.1 or AsyncAPI 2.6 specifications from natural language...
   Tags: api, openapi, asyncapi, scaffolding
   Commands: /api/define

2. api.validate (v0.1.0)
   Status: active
   Description: Validates OpenAPI or AsyncAPI specifications against their respective schemas...
   Tags: api, validation, openapi, asyncapi
   Commands: /api/validate

...
```

### Example 3: Query hooks registry

```bash
$ python3 skills/registry.query/registry_query.py hooks --format table

================================================================================
REGISTRY QUERY: HOOKS
================================================================================

Total entries: 3
Matching entries: 3

+------------------+---------+--------+------------------+----------------------------------------+---------+
| Name             | Version | Status | Event            | Command                                | Enabled |
+------------------+---------+--------+------------------+----------------------------------------+---------+
| pre-commit-lint  | 0.1.0   | active | on_commit        | python3 hooks/lint.py                  | True    |
| auto-test        | 0.1.0   | active | on_file_save     | pytest tests/                          | True    |
| telemetry-log    | 0.1.0   | active | on_workflow_end  | python3 hooks/telemetry.py --capture   | True    |
+------------------+---------+--------+------------------+----------------------------------------+---------+

================================================================================
```

### Example 4: Find agents that can design APIs

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

================================================================================
REGISTRY QUERY: AGENTS
================================================================================

Total entries: 2
Matching entries: 1

--------------------------------------------------------------------------------
RESULTS:
--------------------------------------------------------------------------------

1. api.designer (v0.1.0)
   Status: draft
   Description: Design RESTful APIs following best practices and guidelines...
   Tags: api, design, openapi
   Capabilities: 7 capabilities
   Reasoning: iterative
```

### Example 5: Fuzzy search with limit

```bash
$ python3 skills/registry.query/registry_query.py skills --name vld --fuzzy --limit 3

# Finds: api.validate, context.validate, etc.
```

## Error Handling

The skill handles various error conditions:

- **Invalid registry type**: Returns error with valid options
- **Missing registry file**: Returns empty results with warning
- **Invalid JSON**: Returns error with details
- **Invalid filter combinations**: Logs warnings and proceeds with valid filters

## Performance Considerations

- Registry files are loaded once per query
- Filtering is performed in memory (O(n) complexity)
- For large registries, use `--limit` to control result size
- Consider caching registry data for repeated queries in production

## Dependencies

- **None**: This skill has no dependencies on other Betty skills
- **Python Standard Library**: Uses `json`, `re`, `pathlib`
- **Betty Framework**: Requires `betty.config`, `betty.logging_utils`, `betty.errors`

## Permissions

- **`filesystem:read`**: Required to read registry JSON files

## Contributing

To extend this skill:

1. Add new filter types in `filter_entries()`
2. Enhance fuzzy matching in `matches_pattern()`
3. Add new metadata extractors in `extract_key_metadata()`
4. Update tests and documentation

## See Also

- **skill.define**: Define new skills
- **agent.define**: Define new agents
- **plugin.sync**: Sync registry files
- **marketplace**: Betty marketplace catalog