# Skills and scripts

Teach your agent how your business works: step-by-step instructions it loads only when it needs them, with scripts for the heavy lifting.

Tools are what your agent *can* do. **Skills** are how it *should* do it: your best person's playbook, written down. *"To review the week's jobs: list late jobs, check each crew's hours, flag anything over budget, then summarize in three bullets."* The agent follows the same steps every time, and only reads them when the job calls for them.

## A skill: SKILL.md, references and assets

A skill is a small folder:

| Part | What goes in it |
|---|---|
| **SKILL.md** | A name, a one-paragraph description of *when* to use it, then the steps |
| **references/** | Longer lookup material: price rules, fault codes, who to escalate to |
| **assets/** | Templates and examples, such as a report layout |
| **scripts/** | Small programs for work that's easier in code |

The agent sees only each skill's **name and description** at the start of a conversation. When a request matches, it reads the steps; it opens a reference file only when the steps point to it. So a module can carry many skills without slowing anything down.

Skills follow the open Agent Skills format, so they also work in other assistants that support it.

## Who reads your skills

- **Your module's agent**, in the app.
- **Claude or ChatGPT** with the Data Visions connector, before doing a task in your module.

Write them for a person **using** your module, not for a developer: the jobs they do, which tools to use in what order, what to show before a change, and what never to do.

Loading data from spreadsheets, emails or photos? Don't write that method yourself: add the platform's **data collection upload** skill, and a short skill of your own that says which of your tools do each step.

## Scripts with their own libraries

A script must:

1. Explain itself with `--help`.
2. Take its input as options, never by asking questions.
3. Print results as JSON, and errors separately.
4. Be safe to run twice.

A script can list the libraries it needs at its top, in the standard script header, so the script carries its own setup. Keep anything that must check permissions or change records in a [tool](article:8b4baa95-08a0-4e8e-a7e4-890815c6005b), not a script: tools carry the permission check and the audit.

## Writing instructions an agent follows well

- **Make the description do the work.** Say *when* to use it, and when not: "TRIGGER when: the user asks for a weekly review… DO NOT TRIGGER when: they ask about one job."
- **Number the steps** and name the tool for each one.
- **Say what to check and show** before anything changes, and wait for a yes.
- **Short and focused.** Keep SKILL.md to the workflow; push detail into references.
- **List what never to do.** "Never close a job with open hours."

## Ask the Module Builder

> *"Write a skill for the weekly job review: list late jobs, compare hours to budget for each crew, flag anything 10% over, and end with a three-bullet summary for the owner."*

## For developers

```markdown
---
name: weekly-job-review
description: >
  Review the week's jobs for the owner. TRIGGER when: the user asks for a weekly
  review, late jobs or hours over budget. DO NOT TRIGGER when: they ask about one job.
metadata:
  tools_required: [find_late_jobs, crew_hours]
---
## Workflow
1. Call `find_late_jobs`...
```

It lives in `ai/skills/weekly-job-review/SKILL.md`, listed under `ai.skills` in your manifest. The folder name must match `name`.

## Good to know

- **Not for "how do I… in the app".** The agent already answers those from your module's help. See [Module help and Show me](article:53508199-cd90-4a4c-a453-f6e5c68bdd8e).
- **Every module with tools should have at least one skill.** The module check reminds you.
- **Workspace Admins can read your skills** on the agent's **Skills** tab under **System settings › Agents**, but can't edit them; they arrive with your module's version.


Source: https://datavisions.ai/docs/creators/platform-services/skills-and-scripts
