Configuring your house's skills

Two places decide which skills run on a story, and they do different jobs:

Place	Says	Who sets it
Your house's configured instances	Which skills your house runs, with your values and your authority scale, and on which vendor's executor	You
The story's skills_config	Which of those are active on this story	Your story owner, in each snapshot

Values never travel on a story. SOM's skills_config.active_skills carries only ids, versions and a few flags (Skills for publishers), so the values live with your house. This is HyperContent position P-04.

Your configured instances

Each configured instance is a skill from the library, your label for it, and your values. Write them down per skill:

For each	Decide	Example
Skill	Which library skill, at which version	smart-stories/raise-flag-on-match, 0.2.2
Label	Your name for it, unique in your house. Every warning it raises carries it as rule_id, so pick something an editor understands	house-breaking-indicative-category
Values	The fields the skill's file lists: what to watch, what to match, how loud. Each skill's page in the skill library catalogue lists them	Watch lifecycle.phase for BREAKING, severity flag
Authority scale	For skills that compare who cleared something: your levels, most senior first	editor-in-chief, duty-editor, producer
Executor	Which vendor's executor runs it	The rundown vendor's executor

Every field a value names must be a real place in SOM 1.0's story.context, such as lifecycle.phase or tags[].value: an executor watching a field that doesn't exist raises nothing, and nobody notices.

Checked before you register them Available now

Write your configured instances down as a skills file and check them, all at once, with the skill catalogue API: the same checks the portal makes when you register them, with no sign-in, and nothing stored. A developer can run it from a script or CI whenever the file changes.

Registered with your house Available now

On the portal's Your house: skills page, owners and admins register each configured instance, with the bus checking every value against the skill and every field against SOM 1.0, and bind it to a vendor's executor connection whose app declares that skill at that version (vendors declare what their executors implement; the bind list offers only those). The executor reads its registrations from the bus, and sees only those bound to it. The page shows the whole chain: which executor runs each skill, what feeds it, and who may publish its warnings. It also shows whether each one is running: when its executor last read its skills, and the warnings it raised in the last 7 days. Your house gets an email when an executor stops reading its skills or is disconnected. You can pause a configured instance without unbinding it, and see its history and restore an earlier revision's values. See Run skills in your house and Is it running.

Skills as a file Available now

Keep your configured instances as one file, and change many at once. On Your house: skills:

• Export as file downloads every configured instance as YAML: skill, version, label, values, authority scale, and the executor that runs it. Any member of the house can export.
• Import from file reads a file and shows the plan first: what it would register, update (values or authority scale), bind, unbind or remove, what stays unchanged, and any problems. Nothing changes until an owner or admin presses Apply.

The file looks like this:

skills:
  - skill_id: smart-stories/raise-flag-on-match
    skill_version: 0.2.2
    instance_label: house-breaking-indicative-category
    values:
      match_field: lifecycle.phase
      match_value: BREAKING
      flag_name: BREAKING
      clearing_authority: duty-editor
    authority_scale: [editor-in-chief, duty-editor, producer]
    consumer: c0123456789ab          # the executor's connection in this house
    executor:                        # the same executor, by organisation and app
      org: Northlight Graphics
      app: northlight-flags

How a file is read:

• Matched by instance label. A label your house doesn't have is registered; one it has is updated to the file's values, scale and executor. A configured instance keeps its skill: to change the skill, use a new label.
• Library version. A new entry registers at the library's current version. An entry for a label your house has keeps that configured instance's version (leave skill_version out, or give the same one); a file never moves one to another version: upgrade it on the page instead.
• The executor is found by consumer, the connection id, first. In another house or on another bus that id names nothing, so executor, the organisation and app name, finds the same vendor's app connected there. Leave both out and the instance is registered unbound; leave them out of one your house has bound and the plan unbinds it. As with a single bind, a new binding needs an executor whose app declares the instance's skill at that version; a binding your house already has stays.
• Paused instances carry paused: true. A file that adds it pauses the instance; one that leaves it out of a paused instance resumes it. See Pause and resume.
• Nothing is removed unless you tick Also remove instances the file leaves out. Without it, those are kept and listed in the plan.
• Every entry is checked as a single registration is: the skill's fields, every story field against SOM 1.0, the authority scale, and the house's limit of 50 configured instances. A plan with problems can't be applied: fix the file and import it again.
• Apply applies the plan you saw. If someone changes the house's skills in between, or an executor disconnects, the bus refuses and asks you to plan again. Each change is recorded in your house's audit log, and a vendor's log records when its executor is bound, unbound, paused or resumed, as for a single change. Every change to an instance is a new revision in its history.

A house export carries the same skills: section, so you can also import one of those; its executors are named by connection only, so in another house bind them after importing, or add executor to each.

An executor that doesn't read its registrations

A vendor's executor that doesn't read its registrations from the bus needs your configured instances another way. Send them in the vendor's brief (step 3), ask the vendor to confirm what it loaded, and check the result in your scenarios. Keep one copy, yours, as the reference.

Narrowing per story with skills_config

Your story owner decides, snapshot by snapshot. This is how P-04 reads a story; ask your skill vendors to follow it too:

• No skills_config on a story: every configured instance of your house runs on it.
• With skills_config: only configured instances whose skill is listed in active_skills run. An empty list means none.
• A different skill_version in the list than the one you configured: that configured instance doesn't run on the story.

Keep it simple at first: leave skills_config off and let every configured instance run. Narrow it when you know which story types need which skills.

A story can switch a hold off for itself

A story whose active_skills leaves out a skill you rely on for holds (a legal or standards check, say) isn't evaluated by it. Decide who in your newsroom may do that, and test it in your scenarios.

Reference skills as a baseline

Start from something known to work before you tune values:

• The harness's configured instance. The bus's skill harness uses house-breaking-indicative-category of raise-flag-on-match: watch lifecycle.phase for BREAKING, severity flag. Every executor graded by the harness has run it, so it's a fair first configured instance for comparing vendors.
• HyperContent's reference executor for raise-flag-on-match is open source in sombus-dev-kit. In a rehearsal's skills stepAvailable now, the skill executor stand-in appliesthe same raise-flag-on-match rules to your configured instances that no executor runs, with your values, so you can see a warning come back before any vendor connects. Reference implementations of more library skills are Coming; until then, an instance of another skill with no executor is shown as not run.
• Then your own values, one change at a time, re-running the same scenario after each. If a change makes things worse, restore the revision before it.

A skill your newsroom writes itself, beyond the library, runs on your own executor: your developers follow Skills and executors like any vendor, and test it by hand in your workbench.

Next: Which executors cover your skills.