Skills
Custom skills
Write a skill of your own in the Agent Skills format or upload a skill folder, check it before saving, and know exactly what a custom skill cannot do on Nullgap.
Besides the built-in catalogue, your organisation can keep up to 40 skills of its own. A custom skill is written in the open Agent Skills format, unchanged, so a skill you already use with a coding agent can be brought to Nullgap, and one written here can be used elsewhere.
A custom skill guides where Nullgap AI looks. It does not change how results are checked or reported. The last section lists exactly what it cannot do.
Admins and owners write, upload, edit and delete custom skills. Every member can read them and run the ones that allow it.
#The format
A skill is a folder with a SKILL.md in it:
tenant-rules/
├── SKILL.md required: frontmatter, then the instructions in Markdown
├── scripts/ optional
├── references/ optional
└── assets/ optional
SKILL.md starts with frontmatter between two --- lines. These are the fields of the format:
| Field | Required | Rule |
|---|---|---|
name | Yes | 1 to 64 characters: lowercase letters, digits and hyphens. No hyphen at the start or the end, no two hyphens in a row. Must equal the folder name. It becomes the skill's id. |
description | Yes | 1 to 1,024 characters: what the skill does and when to use it. |
license | No | A licence name, or the name of a bundled licence file. |
compatibility | No | 1 to 500 characters: what the skill needs from its environment. |
metadata | No | A map of text keys to text values. |
allowed-tools | No | A space-separated list of tools. On Nullgap it is kept for display only; see below. |
After the frontmatter come the instructions: free-form Markdown, at least 40 characters. Nullgap accepts a SKILL.md of up to 48,000 characters. The format itself recommends staying under 500 lines.
#What Nullgap reads from metadata
Everything Nullgap needs beyond the format is under metadata, in keys that start with nullgap. so that they cannot collide with anyone else's. Every value is text, as the format requires; a list is words separated by spaces. A skill with none of these keys is valid: it runs on demand and returns a general report.
| Key | Values | Default |
|---|---|---|
author, version | Free text | none, 1.0.0 |
category | appsec, devsecops, secrets, secure-sdlc, compliance, incident-response | appsec |
nullgap.title | The display name | Taken from name |
nullgap.scope | file (works over the files that match) or repository (works once) | repository |
nullgap.pipelines | Any of review, pentest, live, on-demand | on-demand |
nullgap.file-patterns | Globs relative to the repository root, such as **/*.tf Dockerfile* | none |
nullgap.languages | Language names, such as python go typescript | none |
nullgap.technologies | Technology names, such as terraform graphql | none |
nullgap.tools | Tool ids. The catalogue lists the ids your installation knows | none |
nullgap.inputs | repository, pull_request, finding, findings, threat_model, text, artifacts. A ? after a name makes it optional | repository |
nullgap.output | findings, triage, or document: followed by a document kind | document:report |
nullgap.token-share | The largest share of a run's discovery budget the skill may use, from 0.005 to 0.1 for a custom skill | 0.05 |
nullgap.time-minutes | 1 to 30 | 10 |
nullgap.max-steps | 2 to 24 | 12 |
Document kinds: threat-model, security-requirements, design-review, test-plan, control-mapping, policy-evaluation, evidence-pack, incident-runbook, incident-timeline, patch-analysis, report.
Rules between the fields:
- A skill that returns a document or a triage verdict runs on demand only. Reviews and pentests take findings.
- A skill that names a tool which sends requests to a running application (
live-request,browser-check,web-scan) must list thelivepipeline. - A skill that returns a triage verdict must require the
findinginput. - A skill that runs in reviews cannot require
findingortext. - The name of a built-in skill cannot be used.
How triggers decide whether the skill applies to a repository is described under when a skill runs.
#An example
---
name: tenant-rules
description: Checks that every lookup of a customer record is scoped to the caller's tenant. Use when reviewing data access code or a change that adds a query.
license: Proprietary
metadata:
author: acme
version: "1.0"
category: appsec
nullgap.pipelines: review pentest on-demand
nullgap.file-patterns: "src/**/*.ts"
nullgap.tools: code-index
nullgap.output: findings
---
## What to look for
Queries on tenant-owned tables that take an id from the request and do not filter by tenant.
## How to confirm
Follow the id from the handler to the query. Check for the tenant filter in the query itself.
## What is not a finding
A lookup through `TenantRepository`, which adds the filter.
## How to report
File and line of the query, the entry point, each step between them, and the fix.
The four headings are a good habit, not a requirement: a custom skill's instructions are free-form.
#Write one in the console
- Open Skills and choose the Custom skills tab.
- Under Add a custom skill, start from the template. It is a valid skill you can edit.
- The editor checks the text as you go. Problems that must be fixed are listed under Fix these before saving, each with the field it is in; things under Worth a look are warnings and do not stop you.
- Save. The skill appears in the catalogue, switched on.
#Upload a skill folder
On the same tab, under Or upload a skill folder, choose a .zip or .tar.gz of one folder with a SKILL.md at its top level.
| Limit | Value |
|---|---|
| Archive size | 2 MB |
| Files in the archive | 200 |
| Unpacking | The same rules as any uploaded archive: regular files and folders only |
Only SKILL.md is kept. Every other file in the folder is listed by name and size on the skill, marked "kept as a list only", and discarded.
#With the API
Check a skill without saving it. Any key that may write can do this:
curl -s -X POST -H "Authorization: Bearer $NULLGAP_API_KEY" \
-H "Content-Type: application/json" \
-d "$(jq -Rs '{skillMd: .}' tenant-rules/SKILL.md)" \
"$NULLGAP_URL/api/orgs/$NULLGAP_ORG/skills/validate"
{
"ok": false,
"errors": ["metadata.nullgap.pipelines: \"reviews\" is not one of review, pentest, live, on-demand"],
"warnings": []
}
When ok is true the answer also carries the manifest as Nullgap read it.
Save, edit, upload and delete need a key with the admin scope:
| Call | What it does |
|---|---|
POST /api/orgs/:org/skills with { "skillMd": "..." } | Save a new custom skill |
PUT /api/orgs/:org/skills/:id with { "skillMd": "..." } | Replace the text of one. The name in the text must stay the same |
POST /api/orgs/:org/skills/import | Upload a skill folder. The request body is the archive itself |
DELETE /api/orgs/:org/skills/:id | Delete a custom skill, and its switches with it |
curl -s -X POST -H "Authorization: Bearer $NULLGAP_API_KEY" \
-H "Content-Type: application/zip" \
--data-binary @tenant-rules.zip \
"$NULLGAP_URL/api/orgs/$NULLGAP_ORG/skills/import"
| Status and code | Meaning |
|---|---|
400 invalid_skill | The skill did not pass the check. The message lists every problem. Nothing was saved |
400 bad_archive | The upload could not be unpacked, or is over a limit |
403 forbidden | The id is a built-in skill. Built-in skills cannot be edited or deleted; switch one off instead |
409 duplicate_name | A custom skill with that name exists. Edit it, or choose another name |
409 limit_reached | The organisation already has 40 custom skills |
Creating, importing, editing and deleting are written to the audit log as skill.created, skill.imported, skill.updated and skill.deleted. The log names the skill; it does not copy the skill's text.
#A skill is checked every time it is used
A custom skill is stored as you wrote it and checked again each time it is about to run. If a stored skill stops passing, for example because its name was later taken by a new built-in skill, it is left out of runs, and the run's notes say why.
#What a custom skill cannot do
These hold for every custom skill, whatever its text says. The console shows the same statement on each one.
- Its scripts are never run. From an uploaded folder only
SKILL.mdis kept. Nothing else in the folder is read as instructions, opened or executed on Nullgap. - Its
allowed-toolsfield is ignored. The field is kept for display. What a custom skill may call is decided bymetadata.nullgap.tools, by which tools exist on the installation, and by which tools your organisation permits. A skill cannot name a command. - It cannot change the result format. The answer is read by code that accepts one shape for findings, one for a document and one for a triage verdict. An answer in another form is discarded.
- It cannot change the rules of evidence or the proof standard. A custom skill's instructions are handed to Nullgap AI as data, placed between the run's own rules, which are stated before it and again after it. It can say where to look and what to check. It cannot say what counts as verified or proven: those are set by the independent check and by a reproduction. See assurance levels.
- It cannot widen the live-testing scope. Tools that send requests work only inside a pentest with a live-testing target, to that target, under the pentest's rules. A skill cannot name another host. See live testing.
- It cannot take the name of a built-in skill, and it may use at most a tenth of a run's discovery budget.
- It cannot switch off the independent check.
finding-triagestays on, and findings a custom skill raises in a review or a pentest are checked like any others.
A skill that states a preference or a style rule, not a flaw an attacker can use, will mostly produce nothing in reviews and pentests. That is the intended result.
Nullgap documentation