Nullgap.dev Docs

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:

FieldRequiredRule
nameYes1 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.
descriptionYes1 to 1,024 characters: what the skill does and when to use it.
licenseNoA licence name, or the name of a bundled licence file.
compatibilityNo1 to 500 characters: what the skill needs from its environment.
metadataNoA map of text keys to text values.
allowed-toolsNoA 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.

KeyValuesDefault
author, versionFree textnone, 1.0.0
categoryappsec, devsecops, secrets, secure-sdlc, compliance, incident-responseappsec
nullgap.titleThe display nameTaken from name
nullgap.scopefile (works over the files that match) or repository (works once)repository
nullgap.pipelinesAny of review, pentest, live, on-demandon-demand
nullgap.file-patternsGlobs relative to the repository root, such as **/*.tf Dockerfile*none
nullgap.languagesLanguage names, such as python go typescriptnone
nullgap.technologiesTechnology names, such as terraform graphqlnone
nullgap.toolsTool ids. The catalogue lists the ids your installation knowsnone
nullgap.inputsrepository, pull_request, finding, findings, threat_model, text, artifacts. A ? after a name makes it optionalrepository
nullgap.outputfindings, triage, or document: followed by a document kinddocument:report
nullgap.token-shareThe largest share of a run's discovery budget the skill may use, from 0.005 to 0.1 for a custom skill0.05
nullgap.time-minutes1 to 3010
nullgap.max-steps2 to 2412

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 the live pipeline.
  • A skill that returns a triage verdict must require the finding input.
  • A skill that runs in reviews cannot require finding or text.
  • 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

  1. Open Skills and choose the Custom skills tab.
  2. Under Add a custom skill, start from the template. It is a valid skill you can edit.
  3. 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.
  4. 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.

LimitValue
Archive size2 MB
Files in the archive200
UnpackingThe 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:

CallWhat 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/importUpload a skill folder. The request body is the archive itself
DELETE /api/orgs/:org/skills/:idDelete 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 codeMeaning
400 invalid_skillThe skill did not pass the check. The message lists every problem. Nothing was saved
400 bad_archiveThe upload could not be unpacked, or is over a limit
403 forbiddenThe id is a built-in skill. Built-in skills cannot be edited or deleted; switch one off instead
409 duplicate_nameA custom skill with that name exists. Edit it, or choose another name
409 limit_reachedThe 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.md is kept. Nothing else in the folder is read as instructions, opened or executed on Nullgap.
  • Its allowed-tools field is ignored. The field is kept for display. What a custom skill may call is decided by metadata.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-triage stays 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