Skills and operating methods

Build and improve recurring Agent tasks as reusable Skills, primarily by working with the Agent itself and testing representative cases.

Skills are the main way to turn a general Agent into an Agent that knows how your organisation does specific recurring work.

For most builders, Skill creation is not a separate form-filling exercise. You build the Skill with the Agent, in the Agent. Give it representative work, examples, rules and corrections; the Agent writes or updates the Skill and presents the proposed change for review.

The Skills UI in Intelligence remains the canonical inventory, version-history and direct-edit surface. The Agent-side Skill-building UI is the guided authoring path.

What belongs in a Skill

A Skill can define or use:

• the desired outcome and task boundaries;

• business rules and checks;

• connected-system actions;

• reference material and Project files;

• structured Tables or other maintained data;

• templates, supporting files or scripts;

• Workflows that handle defined parts of the task;

• points where the Agent should stop and ask rather than guess;

• Agent-native interaction tools the Skill should use, such as asking the user for structured input or starting a live Call with Agent when a conversation is the better handoff;

• presentation tools the Skill should use, such as an in-stream HTML widget for a compact interactive result or an HTML artefact when the output needs a richer standalone view;

• evidence that shows the task is complete.

The Connection remains separate: the Skill can use an authorised Connection, but the Skill does not own or grant that credential.

Common Skill patterns

Classify a Skill by two questions: what does it deliver? and where does the person sit? That is usually more useful than classifying by industry.

Pattern	Job shape	What usually makes it good
Document generation	Produce an organisation document from structured data and an existing template.	Treat the template as the specification, resolve every placeholder deliberately and fail rather than silently deliver an incomplete document.
Recurring data check	Compare fresh data with a baseline and return what changed or needs attention.	Let code own deterministic numbers, keep thresholds maintained and show evidence behind each finding.
Staged work with checkpoints	Run several stages where a person approves or supplies an intermediate result.	Make stages restartable and keep durable intermediate state outside the conversation.
System connector	Wrap an external system as reusable named read/write operations.	Keep authority in Connections, bound the results and put consequential writes behind the right approval.
File intake	Turn a spreadsheet, PDF, CAD export, XML file or scan into structured rows plus unresolved items.	Read by named fields rather than position, preserve identifiers and surface unresolved source text instead of guessing.
Form completion	Fill a third-party form from maintained facts for human sign-off.	Keep provenance, distinguish unsupported values and do not silently submit.
Tender or bid response	Qualify an opportunity and compose a response from reusable and case-specific material.	Keep reusable company facts separate from prospect-specific facts and unresolved commercial decisions.
Constraint-checked options	Answer whether a change fits and what the viable options are.	Separate hard and soft constraints and allow the recommendation to be null.
Interactive report (supporting)	Render an upstream result as a page a person can inspect or share.	Keep business logic upstream and render from a controlled template.
Learning loop (supporting)	Turn repeated corrections into durable maintained rules.	Store reviewed rules structurally; do not append conversational corrections indefinitely.

A domain is not a Skill pattern. “CAD”, “scanned invoices” or “our ERP” usually describes a parser, rules file or connector inside one of these shapes.

Use Agent-native interaction tools deliberately

A Skill can instruct the Agent to use built-in interaction tools as part of the method, not only external-system tools.

Examples include:

• Ask user when the next step genuinely depends on missing information, judgement or a choice.

• Propose a call when the Skill reaches a point that is better handled as a live conversation. In the web Agent, a Skill can instruct the Agent to use propose_voice_call; the user then presses Call to enter Call with Agent. This proposal tool is not available in Slack, Teams, scheduled, Workflow, task or eval runs.

These are part of the Agent's interaction layer, not Connections. Use them to design the human boundary of the Skill: what can continue autonomously, what should become a structured question, and what is important enough to propose bringing a person into a live call.

Avoid using them as generic fallbacks. A good Skill should ask or call at a deliberate decision point, with enough context that the user understands why their input is needed and what happens next.

Choose the right presentation surface

A Skill can also instruct the Agent how to present the result.

Use an in-stream HTML widget when the result is compact and belongs directly in the conversation—for example, a summary card, small interactive comparison, status panel or focused decision surface.

Use an HTML artefact when the result needs more room, richer interaction or a standalone deliverable—for example, a multi-section report, dashboard-like output, tabbed analysis or a page that someone may want to inspect or share separately.

Keep deterministic rendering logic in code or controlled templates where possible. The Skill should define the intended information and interaction, while scripts or templates handle repetitive HTML generation.

Do not force rich HTML when plain text, a table or a file is the clearer result. The presentation surface should match the job, not become the job.

The Agent-side authoring flow

The customer-facing flow is representative work → draft or update → review → test → publish.

When the Agent starts building a Skill, the Skill panel opens inside the session. The Agent can propose the Skill's name, description, instructions and supporting components. Before anything becomes the maintained Skill, the builder gets an explicit review gate and can edit the proposal or cancel it.

When you correct an existing Skill in conversation, the Agent can propose a reviewed update rather than editing the live Skill silently. The current published version stays live until you approve the new version.

Test the method before publishing

Eligible Project builders can use Tests from Skill detail and Skill proposal views.

Use representative cases that cover the normal path and important exception boundaries. Depending on what happened, a test can distinguish a genuine failure from an inconclusive or errored run rather than treating every unfinished case as the same thing.

The Tests surface is evidence for the builder's decision. It does not silently publish a draft or automatically repair the production Skill.

See Skills for the current test, version and publishing controls.

What good Skills have in common

1. One job with one end state. A Skill should do one coherent job and make “finished” legible.

2. State the inputs and do not ask twice for standing information. Put durable facts and defaults in maintained context.

3. Ask independent questions together, before doing work. Add later questions only when an earlier answer genuinely changes them.

4. Name and describe the Skill for selection. The description helps the Agent decide when it is relevant.

5. Keep instructions to the happy path. Put long references and rarely-needed material in attached or maintained sources.

6. Let code do deterministic work. Repetitive parsing, looping, conversion and validation belong in scripts or coarse deterministic operations.

7. Validate mechanically where you can. Use model judgement for exceptions that actually need judgement.

8. Put people in front of consequential actions. Make retries safe against duplicate writes.

9. Classify failures and bound retries. Do not retry forever or repeat successful earlier stages unnecessarily.

10. Retrieve narrowly. Query only the rows and fields the task needs.

11. Keep the file bundle honest. Every referenced file should exist and unnecessary attachment sprawl should be removed.

12. Never put a credential in a Skill. Use the platform's Connection or credential path.

The practical lifecycle

A good build-and-improve loop is:

define outcome → collect representative examples → verify context and access → Agent writes draft Skill → review → run representative tests → correct → review diff → rerun previously-good cases → publish → improve from evidence

A reviewed Skill lifecycle from defining the outcome and representative examples through draft review, representative cases, corrections, production use and evidence-led improvements that return through the review gate.

Repeated operator corrections and negative session outcomes are useful evidence that the method may need improvement. They are not permission for the production Skill to rewrite itself silently.

When a correction should persist, decide whether the durable fix belongs in the Skill, a Table or Knowledge source, the Project description, the source system, or a Workflow used by the Skill.