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:

Query by Multiple Criteria

Find entities matching multiple skills (comma-separated or array — same skills field):

import { HumanClient } from '@human/sdk';

const client = new HumanClient({
  delegationToken: process.env.HUMAN_DELEGATION_TOKEN!,
});

const { data, error } = await client.raw.POST('/v1/capabilities/query', {
  body: {
    skills: ['contract_review', 'legal_compliance'],
    domains__in: ['legal'],
    min_weight: 0.7,
    limit: 5,
  },
});
if (error) throw error;

const matches = Array.isArray(data?.data) ? data.data : [];
console.log(`Top matches: ${matches.length}`);
for (const row of matches) {
  console.log(`- ${row.passport_did}: ${row.capability?.canonical_name ?? row.capability_id}`);
}

curl -s -X POST https://api.haio.run/v1/capabilities/query \
  -H "Authorization: Bearer $HUMAN_DELEGATION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"skills":["contract_review","legal_compliance"],"domains__in":["legal"],"min_weight":0.7,"limit":5}'

Query with Sort and Pagination

const { data, error } = await client.raw.POST('/v1/capabilities/query', {
  body: {
    skills: ['invoice_processing'],
    sort: '-weight,granted_at',
    limit: 50,
    cursor: process.env.NEXT_CURSOR, // opaque cursor from prior next_cursor
  },
});
if (error) throw error;

console.log(`page size=${data?.data?.length ?? 0} has_more=${data?.has_more}`);

curl -s -X POST https://api.haio.run/v1/capabilities/query \
  -H "Authorization: Bearer $HUMAN_DELEGATION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"skills":["invoice_processing"],"sort":"-weight,granted_at","limit":50}'

Use Cases

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

Common Patterns

Pattern: Skill-Based Routing

async function routeTask(
  client: HumanClient,
  requiredSkills: string[],
  minWeight = 0.7,
): Promise<string> {
  const { data, error } = await client.raw.POST('/v1/capabilities/query', {
    body: { skills: requiredSkills, min_weight: minWeight, limit: 10 },
  });
  if (error) throw error;

  const matches = Array.isArray(data?.data) ? data.data : [];
  if (matches.length === 0) {
    throw new Error('No qualified candidates found');
  }

  const best = matches[0];
  return best.passport_did as string;
}

Pattern: Skill Coverage Check

async function analyzeSkillCoverage(
  client: HumanClient,
  targetSkills: string[],
) {
  const { data, error } = await client.raw.POST('/v1/capabilities/query', {
    body: { skills: targetSkills, limit: 100 },
  });
  if (error) throw error;

  const rows = Array.isArray(data?.data) ? data.data : [];
  const found = new Set(
    rows.map((r) => r.capability?.canonical_name ?? r.capability_id).filter(Boolean),
  );
  const gaps = targetSkills.filter((skill) => !found.has(skill));
  return { found: [...found], gaps };
}

Query by domain (alias)

/docs/patterns/capability-graph/query-capabilities-by-domain is an alias. Filter with domain (or ontology path) on the same query surface:

const { data, error } = await client.raw.POST('/v1/capabilities/query', {
  body: {
    domain: 'finance',
    skills: ['invoice_processing'],
    limit: 20,
  },
});
if (error) throw error;

Related Patterns

• Grant Capability - Add new capabilities after identifying gaps
• Verify Capability - Validate capabilities before task assignment
• Capability routing - Use query results to select executors
• Route Task - Workforce work-item routing

See Also

• Concept Doc: Capability Graph
• Grant Capability pattern
• CLI evidence commands