Query Skills

Search and filter capabilities to find the right person or agent for a task.

This pattern shows you how to query the Capability Graph to discover who has specific skills, experience levels, or training certifications.

When to Use This

✅ You need to find who can perform a specific task
✅ You're building a skill-based routing system
✅ You need to match capabilities to requirements
✅ You want to discover available talent or agents

Architecture

┌─────────────────────────────────────────────────────┐
│         Your Application (Task Assignment)          │
└────────────────────┬────────────────────────────────┘
                     │
                     ▼
          ┌──────────────────────┐
          │   Capability Query   │
          │   (filter by skill,  │
          │   level, certification) │
          └──────────┬───────────┘
                     │
                     ▼
      ┌──────────────────────────────┐
      │   Capability Graph Engine    │
      │   - Indexes capabilities      │
      │   - Supports filters          │
      │   - Returns matches           │
      └──────────┬───────────────────┘
                 │
                 ▼
    ┌────────────────────────────────┐
    │   Matching Capabilities        │
    │   - Passport IDs               │
    │   - Skill levels               │
    │   - Certifications             │
    └────────────────────────────────┘

Prerequisites

API key
Passport ID for querying entity
Understanding of capability structure (skill, level, domain)

Implementation

Basic Skill Query

Find all entities with a specific skill:

TypeScript:
```typescript
import { HumanClient } from '@human/sdk';

const client = new HumanClient({
  apiKey: process.env.HUMAN_API_KEY,
});

// Query for specific skill
const matches = await client.capability.query({
  skill: 'invoice_processing',
  minLevel: 3, // Proficiency level 3 or higher
  limit: 10,
});

console.log(`Found ${matches.length} matches`);
matches.forEach(match => {
  console.log(`- ${match.passportId}: Level ${match.level}`);
});
```

Python:
```python
from human_sdk import HumanClient

client = HumanClient(api_key=os.environ["HUMAN_API_KEY"])

# Query for specific skill
matches = client.capability.query(
    skill="invoice_processing",
    min_level=3,  # Proficiency level 3 or higher
    limit=10
)

print(f"Found {len(matches)} matches")
for match in matches:
    print(f"- {match.passport_id}: Level {match.level}")
```

Go:
```go
import "github.com/human/sdk-go"

client := human.NewClient(os.Getenv("HUMAN_API_KEY"))

// Query for specific skill
matches, err := client.Capability.Query(&human.CapabilityQueryParams{
    Skill:    "invoice_processing",
    MinLevel: 3, // Proficiency level 3 or higher
    Limit:    10,
})

if err != nil {
    log.Fatal(err)
}

fmt.Printf("Found %d matches\n", len(matches))
for _, match := range matches {
    fmt.Printf("- %s: Level %d\n", match.PassportID, match.Level)
}
```

REST API:
```bash
curl -X POST https://api.human.ai/v1/capabilities/query \\
  -H "Authorization: Bearer $HUMAN_API_KEY" \\
  -H "Content-Type: application/json" \\
  -d '{
    "skill": "invoice_processing",
    "minLevel": 3,
    "limit": 10
  }'
```

Query by Multiple Criteria

Find entities matching multiple requirements:

TypeScript:
```typescript
// Query with multiple filters
const matches = await client.capability.query({
  skills: [
    { skill: 'contract_review', minLevel: 4 },
    { skill: 'legal_compliance', minLevel: 3 },
  ],
  domain: 'legal',
  certified: true, // Must have certification
  availability: 'available',
  limit: 5,
});

console.log('Top legal experts:');
matches.forEach(match => {
  console.log(`- ${match.name} (${match.passportId})`);
  console.log(`  Skills: ${match.capabilities.map(c => c.skill).join(', ')}`);
  console.log(`  Certified: ${match.certified}`);
});
```

Python:
```python
# Query with multiple filters
matches = client.capability.query(
    skills=[
        {"skill": "contract_review", "min_level": 4},
        {"skill": "legal_compliance", "min_level": 3},
    ],
    domain="legal",
    certified=True,  # Must have certification
    availability="available",
    limit=5
)

print("Top legal experts:")
for match in matches:
    print(f"- {match.name} ({match.passport_id})")
    print(f"  Skills: {', '.join(c.skill for c in match.capabilities)}")
    print(f"  Certified: {match.certified}")
```

Go:
```go
// Query with multiple filters
matches, err := client.Capability.Query(&human.CapabilityQueryParams{
    Skills: []human.SkillFilter{
        {Skill: "contract_review", MinLevel: 4},
        {Skill: "legal_compliance", MinLevel: 3},
    },
    Domain:       "legal",
    Certified:    true,  // Must have certification
    Availability: "available",
    Limit:        5,
})

if err != nil {
    log.Fatal(err)
}

fmt.Println("Top legal experts:")
for _, match := range matches {
    fmt.Printf("- %s (%s)\n", match.Name, match.PassportID)
    fmt.Print("  Skills: ")
    for i, cap := range match.Capabilities {
        if i > 0 {
            fmt.Print(", ")
        }
        fmt.Print(cap.Skill)
    }
    fmt.Printf("\n  Certified: %v\n", match.Certified)
}
```

REST API:
```bash
curl -X POST https://api.human.ai/v1/capabilities/query \\
  -H "Authorization: Bearer $HUMAN_API_KEY" \\
  -H "Content-Type: application/json" \\
  -d '{
    "skills": [
      { "skill": "contract_review", "minLevel": 4 },
      { "skill": "legal_compliance", "minLevel": 3 }
    ],
    "domain": "legal",
    "certified": true,
    "availability": "available",
    "limit": 5
  }'
```

Query by Organization

Find all capabilities within an organization:

TypeScript:
```typescript
// Query capabilities within an organization
const orgCapabilities = await client.capability.query({
  organizationId: 'org_acme',
  sortBy: 'skill_level',
  order: 'desc',
  includeAgents: true, // Include AI agents
  limit: 50,
});

// Group by skill
const bySkill = orgCapabilities.reduce((acc, cap) => {
  if (!acc[cap.skill]) acc[cap.skill] = [];
  acc[cap.skill].push(cap);
  return acc;
}, {} as Record<string, typeof orgCapabilities>);

console.log('Organization capabilities:');
Object.entries(bySkill).forEach(([skill, capabilities]) => {
  console.log(`\n${skill}:`);
  capabilities.forEach(cap => {
    const type = cap.passportType === 'agent' ? '[Agent]' : '[Human]';
    console.log(`  - ${type} ${cap.name}: Level ${cap.level}`);
  });
});
```

Python:
```python
from collections import defaultdict

# Query capabilities within an organization
org_capabilities = client.capability.query(
    organization_id="org_acme",
    sort_by="skill_level",
    order="desc",
    include_agents=True,  # Include AI agents
    limit=50
)

# Group by skill
by_skill = defaultdict(list)
for cap in org_capabilities:
    by_skill[cap.skill].append(cap)

print("Organization capabilities:")
for skill, capabilities in by_skill.items():
    print(f"\n{skill}:")
    for cap in capabilities:
        cap_type = "[Agent]" if cap.passport_type == "agent" else "[Human]"
        print(f"  - {cap_type} {cap.name}: Level {cap.level}")
```

Go:
```go
// Query capabilities within an organization
orgCapabilities, err := client.Capability.Query(&human.CapabilityQueryParams{
    OrganizationID: "org_acme",
    SortBy:         "skill_level",
    Order:          "desc",
    IncludeAgents:  true, // Include AI agents
    Limit:          50,
})

if err != nil {
    log.Fatal(err)
}

// Group by skill
bySkill := make(map[string][]human.Capability)
for _, cap := range orgCapabilities {
    bySkill[cap.Skill] = append(bySkill[cap.Skill], cap)
}

fmt.Println("Organization capabilities:")
for skill, capabilities := range bySkill {
    fmt.Printf("\n%s:\n", skill)
    for _, cap := range capabilities {
        capType := "[Human]"
        if cap.PassportType == "agent" {
            capType = "[Agent]"
        }
        fmt.Printf("  - %s %s: Level %d\n", capType, cap.Name, cap.Level)
    }
}
```

REST API:
```bash
curl -X POST https://api.human.ai/v1/capabilities/query \\
  -H "Authorization: Bearer $HUMAN_API_KEY" \\
  -H "Content-Type: application/json" \\
  -d '{
    "organizationId": "org_acme",
    "sortBy": "skill_level",
    "order": "desc",
    "includeAgents": true,
    "limit": 50
  }'
```

Use Cases

briefcase:Task Assignment|Query to find the best person or agent for a specific task based on required skills and availability
search:Talent Discovery|Discover internal talent with specific skill combinations for projects or initiatives
graduation-cap:Training Gaps|Identify skill gaps across the organization to inform training programs
users:Team Building|Find complementary skills to build balanced project teams

Best Practices

Performance

Use specific filters to reduce result sets
Set appropriate limits to avoid overwhelming responses
Cache frequently used queries for common skill searches
Index custom skills for faster lookups

Accuracy

Verify skill levels before assignment (capabilities may be outdated)
Check last updated timestamps for capability freshness
Consider certifications for critical tasks
Review provenance to understand how capability was earned

Privacy

Respect access controls - only query capabilities you're authorized to see
Don't expose sensitive skills without consent
Log all queries for audit trails
Use delegation tokens when querying on behalf of others

Security Considerations

do:Verify the querying entity has permission to view results
do:Log all capability queries for audit trails
do:Filter results based on the requester's access level
do:Validate skill names against the canonical ontology
dont:Return capabilities marked as private without explicit consent
dont:Allow unauthenticated queries
dont:Expose personally identifiable information in query results
dont:Cache capability data without considering staleness

Common Patterns

Pattern: Skill-Based Routing

async function routeTask(task: Task): Promise<string> {
  // Query for qualified candidates
  const matches = await client.capability.query({
    skills: task.requiredSkills,
    availability: 'available',
    minLevel: task.minSkillLevel,
    limit: 10,
  });

  if (matches.length === 0) {
    throw new Error('No qualified candidates found');
  }

  // Sort by skill level and assign to top match
  const best = matches.sort((a, b) => b.avgLevel - a.avgLevel)[0];
  
  return best.passportId;
}

Pattern: Skill Gap Analysis

async function analyzeSkillGaps(orgId: string, targetSkills: string[]) {
  const currentSkills = await client.capability.query({
    organizationId: orgId,
    limit: 1000,
  });

  // Find skills that exist
  const existingSkills = new Set(currentSkills.map(c => c.skill));

  // Identify gaps
  const gaps = targetSkills.filter(skill => !existingSkills.has(skill));
  const weak = targetSkills.filter(skill => {
    const levels = currentSkills
      .filter(c => c.skill === skill)
      .map(c => c.level);
    const avgLevel = levels.reduce((a, b) => a + b, 0) / levels.length;
    return avgLevel < 3;  // Below proficiency
  });

  return { gaps, weak };
}

Grant Capability - Add new capabilities after identifying gaps
Verify Capability - Validate capabilities before task assignment
Route Task - Use query results to route work

Query Skills

Query Skills

When to Use This

Architecture

Prerequisites

Implementation

Basic Skill Query

Query by Multiple Criteria

Query by Organization

Use Cases

Best Practices

Performance

Accuracy

Privacy

Security Considerations

Common Patterns

Pattern: Skill-Based Routing

Pattern: Skill Gap Analysis

Related Patterns

See Also