Skill Authoring Guide

Add or modify a skill through a governed authoring path.

This page turns the checklist into an operating UI: create the skill package, register it, wire execution, bind local SOR/FIM sources, validate outputs, and promote only after governance gates pass. It is intentionally explicit because skill changes affect agents, evidence, replay, and source-system permissions.

Add a skill

Adding a skill creates a reusable governed capability. The goal is not just to add UI copy; the skill must have a contract, a package, a registry entry, execution behavior, source bindings, and tests.

1. Skill package

Create config/skills/<domain>/<mission>/<skill_name>/skill.yaml, SKILL.md, and role_variants/default.md.

2. Registry entry

Register the skill in skill_registry.yaml with skill_id, mission, roles, triggers, objects, owner, agents, package path, and autonomy ceiling.

3. Executor wiring

Wire a specific executor in SkillFabricService._execute_skill_logic(), use a generic category executor, or call a shared deterministic service.

4. Local source binding

Add candidate SOR/API/table/permission rows in skill_source_dependency_matrix.yaml so local SOR/FIM-shaped runtime can execute now.

5. Validation

Add tests for required outputs, evidence schema, source dependency state, replay hash, and any shared matcher/service behavior.

6. Promotion

Promote from local-runtime ready to BP-validated only after BP confirms production source, permissions, owner, cadence, and fallback.

Modify a skill

Modification depends on what is changing. Do not change an executor for a wording change, and do not change a role variant for a behavior change.

Contract/schema

Edit skill.yaml and tests when inputs, outputs, evidence requirements, autonomy ceiling, or output_schema changes.

Discovery/governance

Edit skill_registry.yaml when name, mission, role, trigger, object, owner, lifecycle, or agent mapping changes.

Behavior

Update the executor or shared deterministic service when the actual decision logic changes.

Role wording

Edit role_variants/*.md for analyst, supervisor, executive, or administrator wording without changing behavior.

Source binding

Update skill_source_dependency_matrix.yaml for local runtime mappings; keep BP production validation pending until data owners certify.

Safe rule: if an agent and skill need the same decision logic, extract a shared deterministic service and make both call it. That prevents agent/skill drift.

Authoring file previews

skill.yaml

skill_id: finance.p2p.duplicate_invoice_detection
name: Duplicate Invoice Detection Agent
domain: finance
subdomain: p2p
type: primary
inputs:
  required: [invoices]
outputs:
  required: [is_duplicate, duplicate_candidates, duplicate_risk_level]
evidence_requirements:
  - matched_invoice_ids
  - matched_fields
  - total_exposure
autonomy:
  default: AL-2
  max: AL-3

skill_registry.yaml

- skill_id: finance.p2p.duplicate_invoice_detection
  name: Duplicate Invoice Detection Agent
  missions: [p2p]
  roles: [p2p_analyst, tower_lead, administrator]
  triggers: [invoice received, payment run precheck]
  objects: [invoice, supplier, payment_run]
  agents: [iaf-duplicate-leakage-agent]
  package_path: finance/p2p/duplicate_invoice_detection
  autonomy_ceiling: AL-3

source dependency matrix

finance.p2p.duplicate_invoice_detection:
  source_systems: [FIM, SAP_ECC, SAP_S4HANA, Ariba, OpenText_VIM]
  api_endpoints: [/api/v1/invoices, /api/v1/purchase-orders]
  tables_or_views: [BKPF, BSEG, RBKP, RSEG, EKKO, EKPO, LFA1]
  permission_class: read_only
  read_permission: pending_bp_validation
  write_permission: governed_write_gateway_only
  data_owner: pending_bp_validation
  refresh_cadence: pending_bp_validation
  fallback_strategy: local_fixture_then_sor_confirmation

Promotion gates

Gate	What must be true	Why it matters
Contract valid	Inputs, outputs, output_schema, evidence_schema, and autonomy ceiling are explicit.	Agents can call the skill without guessing.
Local runtime ready	Candidate SOR/API/table mappings exist and local adapters can execute.	Demo and test do not wait for BP production access.
BP validation pending/complete	Production source, permissions, owner, cadence, classification, and fallback are tracked.	Prevents pretending local demo wiring is production certified.
Replay-ready	Execution returns evidence hash, lineage, and schema-bound outputs.	Every decision can be audited.
Tests pass	Contract, source dependency, executor, and UI contract tests pass.	Prevents silent drift.

Example: modifying duplicate invoice detection

Behavior change

Change duplicate_invoice_matcher.py, then update contract tests so both Duplicate Invoice Detection Agent and finance.p2p.duplicate_invoice_detection continue to return the same schema-bound verdict.

Source binding change

Update skill_source_dependency_matrix.yaml to add local runtime mappings first. Mark BP production validation separately when data owners certify the real source path.