> For the complete documentation index, see [llms.txt](https://surecloud.gitbook.io/surecloud-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://surecloud.gitbook.io/surecloud-docs/documentation/gracie/personas-and-skills/write-and-test-custom-skills.md).

# Write and Test Custom Skills

Write custom Gracie skills that trigger reliably, stay grounded in real data and confirm before writing.

SureCloud comes with built-in skills, and you can create your own for your organisation's processes. This page shows you how to write a skill that is narrow, grounded and predictable, and how to test it before you turn it on.

### The four parts of a skill

| Field                 | What to put in it                                                                                                                                |
| --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ |
| **Name**              | A short, action-led name in lower case with hyphens, such as `create-risk` or `triage-incident`.                                                 |
| **Description**       | What the skill does and how people are likely to ask for it. This field matters most: Gracie uses it to decide when the skill matches a request. |
| **Supporting skills** | Any skills this skill calls. Only list what this skill depends on.                                                                               |
| **Instructions**      | The playbook: when to use the skill, what it does, what it needs, what the output should look like, and the guardrails it must follow.           |

### Write for the outcome, not the mechanics

Tell the skill what outcome to achieve. Don't spell out how to use the platform: Gracie already knows how to search, create records, find references and format results. Spend your words on the judgement, the shape of the output and the guardrails that make the skill trustworthy.

### Five rules for trustworthy skills

1. **Ground everything in real data.** Never invent records, values, dates, IDs or citations.
2. **Say something substantive.** Explain cause, event and consequence instead of restating a title.
3. **Draft before you write.** Show the full proposed record first, then wait for confirmation.
4. **Stop if the source can't be read.** Never guess what a document says.
5. **Make counts add up.** If the summary says three gaps, the detail must show three gaps.

{% hint style="success" %}
If data is missing, the skill should say so plainly.
{% endhint %}

### Start with build-skill

Use the `build-skill` skill to help shape a new skill. Describe the job in plain English, for example:

* `build a skill that drafts a risk from a vendor email`
* `create a skill to review supplier certificates`
* `draft a skill that triages incidents`

`build-skill` drafts the four fields, checks them against the rules above, and bases the draft on the real fields and options of the record type you're targeting.

### Test a new skill before you turn it on

Run these checks against real data in your platform.

{% stepper %}
{% step %}

#### Check the trigger

Ask for the skill in the words your team would use, then try an unrelated request. The skill should run when it should, and stay quiet when it shouldn't.
{% endstep %}

{% step %}

#### Check the grounding

Make sure every record, figure and citation is real. If the source doesn't support a field, the skill should leave it blank or say it can't answer.
{% endstep %}

{% step %}

#### Check confirmation

If the skill writes data, it should show a full draft first. Nothing should be written until you confirm.
{% endstep %}

{% step %}

#### Check the output

Make sure the response is short, clear and in the shape you intended.
{% endstep %}
{% endstepper %}

### Format skill output

Skill output should be easy to scan. Use **bold labels** for key fields, short bulleted or numbered lists, and links to records where they help. Avoid long essays and heavy layout.

### Checklist before you turn a skill on

Before you turn on a skill, check that it:

* clearly describes what it does
* includes the phrases people are likely to use
* grounds every answer in real data
* stops if a source can't be read
* confirms before any write
* keeps counts and details aligned
* does one job well

### Related articles

* [Personas and Skills](https://surecloud.gitbook.io/surecloud-docs/documentation/gracie/personas-skills-and-agents)
* [Skills](https://surecloud.gitbook.io/surecloud-docs/documentation/gracie/personas-skills-and-agents/skills)
* [Skill and persona reference](https://surecloud.gitbook.io/surecloud-docs/documentation/gracie/personas-skills-and-agents/skill-and-persona-reference)