How gerivdb/skills works
Purpose and Entry Points
This is the ecosystem-1 canonical Skills registry: a declarative catalog plus local tooling for discovering, validating, loading, indexing, and governing skill definitions. Primary entry points are REGISTRY.yaml, MANIFEST.json, and registry.json; each skill is principally expressed as a SKILL.md. Operational Python entry points include skill_loader.py, skill_manager.py, and skill_registry.py.
Skill Catalog and Content Boundary
The registry separates maintained native skills, repository-local operational skills, and assimilated/external content. Native capability families reside under native/foundational/, native/domain/, and native/engines/; each leaf exposes a portable instruction contract such as native/engines/dag-rag/SKILL.md. Repository-local skills are held in skills/, while Perplexity-oriented source and packaged variants are separated in perplexity/skills/ and perplexity/skills_pack/. External material is isolated behind the submodule boundary at ext/marketingskills/.
Registry, Manifest, and Taxonomy Model
REGISTRY.yaml is the canonical registered-skill index, with MANIFEST.json providing agentskills.io compatibility and registry.json likely serving generated/consumable registry output. Classification and graph metadata are distinct from skill prose: TAXONOMY.md, TAXONOMY/coords.yaml, and TAXONOMY/graph.yaml define placement and relationships. Ecosystem identity and scope are governed by ECOS_ROOT.json, citizens.yaml, and SCOPE.yaml.
Loading and Runtime Control
The local Python runtime supplies lazy skill resolution and lifecycle control rather than a web service. skill_loader.py loads requested skills; skill_registry.py provides registry access; and skill_lock_file.py supports lock-state handling. ctulu_resolver.py and verse_context.py add context/resolution layers around skill selection. The lazy-loading architecture is explicitly documented in ADR/ADR-001-lazy-skill-menu.md and planned through PRD/PRD-005-skill-loader-ctulu-wiring.md.
Search, IR, and Graph Pipeline
Skills can be transformed into intermediate/searchable representations through skill_ir/skill_ir.py, indexed by scripts/index_skills.py, and queried by scripts/search_skills.py. Vector-search infrastructure is represented by tools/core/zvec_manager.py and persisted metadata in data/zvec/zvec_index.json. Graph-oriented capabilities are defined as composable skills, including skills/ctulu-graph-builder/SKILL.md, skills/ctulu-louvain-clusterer/SKILL.md, and skills/ctulu-pagerank-runner/SKILL.md; the canonical relationship layer remains under TAXONOMY/.
Validation and Publication Flow
Contribution flow is: add or change SKILL.md content, update registry/manifest metadata, run validators, then publish through Git-based review and CI. Core enforcement tools are tools/validate-skills.py, tools/validate-agentic.py, and tools/registry-gen.py. Git hooks under .githooks/ enforce local quality gates, while GitHub Actions in .github/workflows/validate-skills.yml and .github/workflows/registry-sync.yml validate and synchronize registry state. The registry is designed for consumption by the external ECOYSTEM federator as a Git submodule, not as an independently deployed application.
Components 20
Skill Catalog
Portable skill content and source boundaries.
- Canonical Registry · Authoritative registered-skill index.
REGISTRY.yaml - AgentSkills Manifest
MANIFEST.json - Consumable Registry
registry.json - Native Skill Families · Foundational, domain, and engine capabilities.
native/engines/dag-rag/SKILL.md - Repository-local Skills · Includes composable graph capabilities.
skills/ctulu-graph-builder/SKILL.md - Perplexity Content · Source and packaged variants are separated.
- External Skills Submodule · Assimilated material remains isolated.
Local Runtime
Lazy resolution and lifecycle control.
- Skill Loader · Lazily loads requested skills.
skill_loader.py - Registry Access
skill_registry.py - Context Resolver · Adds contextual resolution around skill selection.
ctulu_resolver.py - Lock State
skill_lock_file.py
Search & Graph
IR, vector search, and relationship metadata.
- Taxonomy & Relations · Coordinates and canonical skill relationships.
TAXONOMY/graph.yaml - Skill IR · Transforms skills into searchable representations.
skill_ir/skill_ir.py - Skill Indexer
scripts/index_skills.py - Skill Search
scripts/search_skills.py - Vector Index · Persisted vector-search index.
data/zvec/zvec_index.json
Governance & Publication
Validation, synchronization, and federation.
- Validation Tools · Validate skill and agentic contracts.
tools/validate-skills.py - Registry Generator
tools/registry-gen.py - Hooks & CI Sync · Local hooks and GitHub Actions enforce and synchronize state.
.github/workflows/registry-sync.yml - ECOYSTEM Federator · Consumes this registry as a Git submodule.
Connections 24
- Native Skill Families → Canonical Registry: registered in
- Repository-local Skills → Canonical Registry: registered in
- Perplexity Content → Canonical Registry: cataloged by
- External Skills Submodule → Canonical Registry: isolated from
- Canonical Registry → AgentSkills Manifest: aligned with
- Canonical Registry → Consumable Registry: generated to
- Taxonomy & Relations → Canonical Registry: classifies
- Registry Access → Canonical Registry: reads
- Context Resolver → Skill Loader: guides selection
- Skill Loader → Registry Access: resolves through
- Skill Loader → Lock State: uses
- Skill Loader → Repository-local Skills: lazy-loads
- Native Skill Families → Skill IR: transformed into
- Repository-local Skills → Skill IR: transformed into
- Skill IR → Skill Indexer: indexed by
- Skill Indexer → Vector Index: writes
- Skill Search → Vector Index: queries
- Native Skill Families → Validation Tools: validated by
- Repository-local Skills → Validation Tools: validated by
- Canonical Registry → Registry Generator: generates
- Registry Generator → Consumable Registry: publishes
- Validation Tools → Hooks & CI Sync: gates
- Hooks & CI Sync → Consumable Registry: synchronizes
- Consumable Registry → ECOYSTEM Federator: consumed as submodule