Custom Ontology

Extend the capability graph with your organization's unique skills and domains.

While provides a comprehensive default skill ontology, every organization has specialized capabilities. This pattern shows you how to define custom skills, domains, and taxonomies that reflect your unique business needs.

When to Use This

• ✅ You have organization-specific skills not in the default ontology
• ✅ You need custom domains (e.g., "quantum_computing", "maritime_law")
• ✅ You want to define skill hierarchies and relationships
• ✅ You need to map previous HR systems to

Architecture

┌─────────────────────────────────────────────────────┐
│         Your Organization's Skill Model             │
│   - Custom domains                                   │
│   - Specialized skills                               │
│   - Proficiency definitions                          │
└────────────────────┬────────────────────────────────┘
                     │
                     ▼
          ┌──────────────────────┐
          │   Ontology Registry  │
          │   (create custom     │
          │    skills & domains) │
          └──────────┬───────────┘
                     │
                     ▼
      ┌──────────────────────────────┐
      │   Capability Graph Engine    │
      │   - Merges with base ontology│
      │   - Validates relationships  │
      │   - Indexes custom skills    │
      └──────────┬───────────────────┘
                 │
                 ▼
    ┌────────────────────────────────┐
    │   Unified Skill Taxonomy       │
    │   - Base + Custom Skills       │
    │   - Organization namespaced    │
    │   - Searchable & queryable     │
    └────────────────────────────────┘

Prerequisites

• API key
• Organization Passport ID
• Admin role (ontology management permission)
• Understanding of your organization's skill model

Implementation

Define a Custom Skill

Create a new skill specific to your organization:

Define a Custom Domain

Create a new domain (category) for grouping skills:

Define Skill Relationships

Create hierarchies and relationships between skills:

Use Cases

Best Practices

Naming Conventions

• Use snake_case for skill IDs (e.g., widget_assembly_advanced)
• Include organization context for truly unique skills
• Avoid abbreviations unless industry-standard
• Be specific rather than generic (e.g., "react_frontend" not "programming")

Skill Definitions

• Define clear levels with actionable descriptions
• Document prerequisites for complex skills
• Include metadata for certifications, safety requirements, etc.
• Review regularly - skills evolve, ontologies should too

Maintenance

• Version your ontology - track changes over time
• Deprecate carefully - provide migration paths for old skills
• Test queries after ontology changes
• Document custom skills for future team members

Security Considerations

Common Patterns

Pattern: Import from HR System

async function importSkillsFromHR(csvFile: string) {
  const skills = parseCSV(csvFile); // { name, description, level }
  
  for (const skill of skills) {
    // Create in HUMΛN ontology
    const humanSkill = await client.ontology.createSkill({
      organizationId: 'org_acme',
      skill: toSnakeCase(skill.name),
      displayName: skill.name,
      description: skill.description,
      domain: inferDomain(skill),
      levels: standardizeLevels(skill.level),
    });

    // Create equivalence mapping
    await client.ontology.createEquivalence({
      organizationId: 'org_acme',
      humanSkill: humanSkill.skill,
      externalSystem: 'hr_system',
      externalSkillId: skill.id,
      bidirectional: true,
    });
  }
}

Pattern: Skill Evolution

async function evolveSkill(oldSkill: string, newSkill: string) {
  // Create new skill
  const updated = await client.ontology.createSkill({
    organizationId: 'org_acme',
    skill: newSkill,
    displayName: `${oldSkill} (Updated)`,
    // ... updated definition
  });

  // Mark relationship
  await client.ontology.createRelationship({
    organizationId: 'org_acme',
    fromSkill: oldSkill,
    toSkill: newSkill,
    relationship: 'supersedes',
    strength: 1.0,
  });

  // Deprecate old skill (don't delete - preserves history)
  await client.ontology.updateSkill({
    organizationId: 'org_acme',
    skill: oldSkill,
    deprecated: true,
    deprecationMessage: `Superseded by ${newSkill}`,
  });
}

Related Patterns

• Grant Capability - Use custom skills when granting capabilities
• Query Skills - Search across custom and base skills
• Verify Capability - Verify custom skill proficiency

See Also

• Capability Graph Core Concept
• Ontology API Reference