Where it goes
Contoso keeps assess-renewal-risk in skills/assess-renewal-risk.yaml. The loader reads every YAML file under the package root, so folders are a convention you can change. Name it in lowercase kebab-case. The name must be unique among the package's Skill resources.
Limits
The validator checks a skill's references, arguments and shape. Planning, evidence and output stages are being built.
Fields
The keys under spec. Nested shapes follow SkillSpec in the GOL JSON Schema.
| Field | Presence | Shape |
|---|---|---|
use | Required | enum: answer, output |
purpose | Optional | string |
triggers | Optional | object |
prompt | Optional | string |
evidence | Optional | array |
checks | Optional | array |
onFail | Optional | enum: notice, refuse |
runs | Optional | refList |
output | Optional | object |
pii | Optional | object |
verifyClaims | Optional | boolean |
tests | Optional | testRefs |
Syntax and rules
The examples are fragments. Put them in a package next to the resources they reference. A ... stands for a CEL expression you write yourself.
9.7 Skill
A versioned, tested instruction set: when it applies, what evidence it needs and how fresh, what it may run and how the answer is shaped. A flat resource with a kebab name, referenced as skill:<name>. Decided 2026-10-10 (Waseem): company skills are GOL, personal skills are rows with the same schema (docs/plans/gluon-context.md, section 6).
kind: Skill
metadata:
{ name: assess-renewal-risk, title: Assess renewal risk, owners: ["team:procurement-data"] }
spec:
use: answer # answer | output
purpose: Say whether a supplier's {{procurement.Contract}} renewals are at risk.
triggers:
questions: ["Is the {{procurement.Contract}} with this supplier at risk?"]
intents: [renewal-risk]
prompt: |
A contract is at risk when {{procurement.Contract#renewalDate}} is within 30 days.
Name the {{procurement.Contract | properties}} you relied on.
evidence:
- {
tool: "tool:erp-live/contracts-by-supplier",
args: { supplierId: $entity.party.Supplier },
freshness: live,
}
- { view: "view:procurement.ContractsRenewingSoon", freshness: PT24H }
- { search: true, k: 6 }
checks:
- {
expr: "facts.exists(f, f.tool == 'tool:erp-live/contracts-by-supplier')",
message: The register was not read,
}
onFail: notice # notice (a row in "What needs attention") | refuse
runs: ["procurement.RenewContract"] # may propose; the action's own approval still applies
output: { schema: { type: object, required: [tier, reasons] }, cites: required } # cites: required | optional
pii: { wipe: default }
tests: ["test:renewal-assistant"]
evidenceentries are{tool, args?, freshness},{view, freshness}or{search: true, k}.freshnessislive(never from memory) or an ISO duration, a ceiling over the source'sfreshness.maxAge(the stricter wins).evidence[].argsvalues are literals,$entity.<Type>(the id of the plan's entity of that type; the type resolves like any ref) or$question.<name>(a named input the planner extracts), nothing else (GLN-E272). This is what the egress rule admits.checks[].expris CEL overfacts,packetandsubject, checked like every other CEL site (E201 to E203).prompt,purposeandtriggers.questionscarry references in text (2.2).- A
use: outputskill writes the final text from the draft and the packet and takes onlyprompt,output,pii,verifyClaimsandtests; any other key isGLN-E271. verifyClaims: falseturns the claim check off for answers the skill shapes (added 2026-10-27, F31). By default, after an answer that cites a passage settles, one fast call on the planner's route quotes the passage words behind each claim and code checks the quotes are there; partial and unsupported claims get the dotted underline. The Capability has the same switch.
Check your package
gluon validate examples/contoso
gluon test examples/contoso
validate reports each problem with a GLN code and its place in the file. test runs the package's Test resources. See the language guide and the diagnostics.