The graph lens

Explore how skills relate to each other. See the neighbors of a skill, paths between two, what depends on one, dependency cycles, orphans and clusters of skills that compete for the same task.

By The SKaaS team. Last updated . Markdown version

Skills point at each other. One requires another, defers to it, replaces it or covers a part of it. The graph lens shows those links, so you can see what breaks when you change a skill and which skills compete.

Edition and plan: the graph_lens feature, which is in Cloud Team and above and in the Community edition. It also needs the optional graph database. On a self-hosted deployment, start the graph profile of Compose and set SKAAS_NEO4J_URI to its address, with the user name and password in NEO4J_PASSWORD, so that the server connects to it. A deployment with no graph answers NOT_IMPLEMENTED with the message that it has no graph.

From the skills themselves and from use. An author declares a relation in the frontmatter of a skill, with one of nine types.

Where do the links come from?
Type Means
requires This skill needs the other one.
defers_to For another task, use the other skill.
part_of, broader The skill sits inside, or under, a wider one.
covers The skill covers the same ground as another.
uses_evidence_from The skill relies on a reference.
derived_from The skill says that another skill is its origin.
supersedes The skill replaces another.
related_to A looser link.

The service adds two more. collides_with links two skills whose descriptions compete for the same task, with a score from 0 to 1. co_loaded_with counts how often two skills are loaded together. The links belong to a release, so the graph follows the head of each skill.

The graph database is a projection. It is rebuilt from the relations that the releases hold, so you can lose it without losing anything. A change reaches it through the outbox, a little after the publish.

What can I ask it?

Every answer lists only skills that the caller may read.

What can I ask it?
View What it shows
Neighborhood The skills around one skill, at most two hops away, eight links per skill and twenty skills in all. Filter by relation type and direction.
Paths The shortest paths between two skills, up to 16 hops and 20 paths.
Dependents The skills that depend on one skill, to see what a change reaches. Up to 32 hops and 1,000 skills.
Cycles Groups of skills that require each other in a loop. A loop is a mistake to fix.
Orphans Skills that no link joins to another, by kind. They are easy to miss for a person and for a search.
Collisions Clusters of skills that compete, with the pairs and their scores. Use it before you merge or reword.

The answer says when a cap or a row limit left something out. Each view has a route under /v1/orgs/{org}/insights/graph/, and the dashboard shows them.

Where do I see it in the dashboard?

Open Relations in the dashboard of the organization. The page has a skill chooser and a path finder. With a skill chosen, it shows the relations around it, with the type, the direction and the other skill in each row, and the list of what depends on it. Without one, it still shows the cycles, the skills that nothing relates, and the collision clusters with their members and scores. The page is built from tables and lists, because every fact fits in a row and a list reads the same with a screen reader, so it draws no diagram. Each card loads on its own. A card that fails shows its own error with a retry, and the others stay in place. A list that was cut short says so.

The page has states that say what is missing. An organization whose plan lacks the feature sees "The graph lens is not in your plan", with a pointer to billing. A deployment that has no graph database shows "The graph lens is not set up on this deployment", with what the operator does: start the graph service and set its address, user name and password. A deployment with a graph but no skills yet shows an empty page that points to the repositories, because the graph reads the relations after the first publish.

What do I do with a collision?

Say in both descriptions what each skill is for and when not to use it, with a SKIP: clause that names the other, or merge the two. Then add a routing test for the task that they both claim, so the fix stays fixed.