Resource references

The instructions of a skill or a rule can cite resources with the same syntax NiuCore's chat uses. A skill that says “search {{workspace:31}} before answering” does not just name the library: when attached to a turn, it brings it along.

{
  "name": "Responder reclamos",
  "instructions": "Antes de responder, buscá la política vigente en {{workspace:31}} y, si el cliente pide un reintegro, usá la plantilla de {{file:902}}. Seguí además {{skill:147}}.",
  "level": "company",
  "visibility": "public"
}

#Syntax

• The separator may be : or -; on save it is always rewritten with :, so the GET returns the canonical form ({{skill-3}} → {{skill:3}}).
• Only the types in the table count, in lowercase. {{customer}} or {{Skill:3}} stay as literal text: they are your own variables.
• Up to 20 distinct references per type and 60 in total per text.

#Validation on save

POST and PATCH on /skills and /rules validate the references before writing anything, against the permissions of the user who owns the credential. If any fails, they answer 422 prompt_refs_invalid and the skill or rule stays as it was.

{
  "status": "error",
  "message": "Hay referencias no disponibles o inválidas en el texto.",
  "message_code": "prompt_refs_invalid",
  "data": [
    {
      "denied": [{ "type": "workspace", "id": 88 }],
      "invalid": ["{{file:abc}}"],
      "unsupported": ["{{agent:5}}"],
      "over_limit": [],
      "cycle": []
    }
  ],
  "meta": { "request_id": "9f1c0a3e-7b2d-4f18-9a55-2c6e0d1b4a77" }
}

• A PATCH that does not change instructions revalidates nothing: you can rename a skill even if it cites a resource that was later revoked.
• If you change the text, every reference is revalidated, including the ones already there. An invalid or unsupported token that was already saved is kept, so you can still edit the rest.
• instructions is capped at 12,000 characters for a skill and 4,000 for a rule; exceeding it returns 422 prompt_text_too_long.

#In an API turn

When you attach a skill with attachments.skill_ids, the turn receives its content with the citations resolved, and the libraries, files, skills, connectors and tools it cites join the turn — but only those within your credential's scope. A credential limited to library 31 does not reach library 88 because a skill names it: that citation is silently dropped.

• Citations of people and shared contexts do not reach an API turn: the credential has no such resource types.
• Attaching resources still requires its companion scope (libraries:read, skills:read, connectors:use). What a skill adds never exceeds what the credential could already attach.
• {{…}} tokens written directly into content are not a supported channel: use attachments. A token in content pointing outside the credential's scope makes the turn fail.

#Agents