Skills
Running a skill on demand
Start one skill by itself against a repository, a pull request, a finding or two versions of an artefact, and read what it returns and how far to rely on it.
A skill that lists "on demand" can be started by itself, outside a review or a pentest. Use this to get a document (a threat model, a test plan, an incident runbook), a second look at one finding, or a comparison of two versions.
An on-demand run is one skill working once. Its output is not sent through the independent check and nothing in it is reproduced in the sandbox. Every run says so in its assurance field, in words written by Nullgap and not by the skill. For findings held to the assurance levels, run a pull request review or a pentest.
#What you need
- Any member can start a run. With the API, a key with the
writescope. - An active trial or plan. Without one the call answers
402plan_inactive; at the monthly usage ceiling it answers402usage_limit. See usage. - The skill must be switched on for the organisation and for the repository, and it must list "on demand". The catalogue says which do.
#What a skill can work on
Each skill states its inputs, and whether each is required. The catalogue shows them under What it works from.
| Input | You give | Used by, for example |
|---|---|---|
| A repository | The repository, and optionally a branch, tag or commit | Most skills |
| A pull request | The repository and the pull request number | secure-code-review, secure-design-review |
| A finding | The finding's id; the repository is taken from the finding | finding-triage, exploited-vulnerability-response |
| Text | Logs, an alert, a feature description, up to 200,000 characters | security-event-analysis, security-requirements |
| Two versions | Two uploaded artefacts, or two refs of one repository | patch-diff-analysis |
Do not put credentials in the text you supply.
#In the console
- Open Skills and choose the Run a skill tab.
- Choose the Skill. Only skills that are switched on and can run on demand are listed.
- Fill in what that skill works on: a repository and optionally a version, a pull request, a finding, text, or two versions to compare.
- Start the run. It appears under Recent runs with its status, and opens with its result when it has finished.
#With the API
Start a run on a repository's default branch:
curl -s -X POST -H "Authorization: Bearer $NULLGAP_API_KEY" \
-H "Content-Type: application/json" \
-d '{"skillId":"threat-modeling","repoId":"repo_4c1d2e3f5a6b"}' \
"$NULLGAP_URL/api/orgs/$NULLGAP_ORG/skill-runs"
| Field | Meaning |
|---|---|
skillId | The skill's id. Required. |
repoId | The repository. Required unless findingId or artifacts is given. |
ref | A branch, tag or commit. Default: the repository's default branch. |
prNumber | A pull request number, for a skill that takes one. |
findingId | A finding, for a skill that takes one. |
baseRef | With ref: compare baseRef (older) with ref (newer), for a skill that compares two versions. |
artifacts | { "before": "<upload id>", "after": "<upload id>" }: two uploads to compare. No repository is involved. |
text | Text for the skill to work on. |
The answer is the run, with status queued and no output yet (abridged):
{
"id": "skr_9d2c4b7a1e3f",
"skillId": "threat-modeling",
"skillTitle": "Threat modeling",
"skillVersion": "1.0.0",
"origin": "built-in",
"repoId": "repo_4c1d2e3f5a6b",
"repoFullName": "acme/shop",
"target": { "kind": "repository", "ref": "main" },
"hasText": false,
"status": "queued",
"error": null,
"assurance": "Produced by one skill run on request. It was not sent through the independent check or reproduced in the sandbox, so nothing in it is a verified or proven finding. Run a review or a pentest for findings held to that standard.",
"output": null,
"tools": [],
"createdBy": "dana@acme.example",
"createdAt": "2026-11-16T10:02:11.000Z",
"startedAt": null,
"finishedAt": null
}
Read it until status is completed, failed or cancelled. A run takes minutes, so ask every 15 seconds or so, not in a tight loop:
curl -s -H "Authorization: Bearer $NULLGAP_API_KEY" \
"$NULLGAP_URL/api/orgs/$NULLGAP_ORG/skill-runs/skr_9d2c4b7a1e3f"
Other calls:
| Call | What it does |
|---|---|
GET /api/orgs/:org/skill-runs | Runs, newest first, without their output. Takes limit, offset and skillId. |
GET /api/orgs/:org/skill-runs/:id | One run with its output. |
GET /api/orgs/:org/skill-runs/:id/logs | The run's log lines. |
POST /api/orgs/:org/skill-runs/:id/cancel | Cancel a run that is queued or running. A finished run answers 400 not_running. |
Refusals when starting:
| Status and code | Meaning |
|---|---|
400 not_on_demand | The skill runs only inside reviews and pentests, or only in live testing |
400 skill_disabled | The skill is switched off for the organisation or for this repository |
400 bad_request | An input the skill needs is missing, or one it does not take was sent. The message says which |
402 plan_inactive, usage_limit | No active plan, or the monthly usage ceiling has been reached |
404 not_found | The skill, the repository, the finding or an upload does not exist |
#Reading the result
A finished run has three things to read: output, tools and assurance.
#tools
One entry for each tool the skill named, with what happened to it:
status | Meaning |
|---|---|
ran | The tool ran |
offered | The tool was available and the skill did not call it |
unavailable | The tool is not installed on this installation |
not-permitted | Your organisation does not permit this tool |
failed | The tool was started and did not finish |
A tool that did not run is not a clean result. The output's limits say what was not examined because of it.
#output
What comes back depends on the skill, and has one of three fixed shapes.
A document ("kind": "document"): a title, a summary, sections with a heading and a body each, items, and limits. Each item is one row: a control, a requirement, a policy check or a timeline entry, with a ref, a title, a detail, an optional location and a status from a fixed neutral set:
status | Meaning |
|---|---|
evidence-found | Something in the code or the data supports it |
gap-observed | Something expected was looked for and not found |
not-examined | It was not looked at |
not-applicable | It does not apply here |
info | A note |
There is no "pass" or "fail" in that set on purpose: a document from a skill is material for your own judgement.
Candidate leads ("kind": "findings"): leads, each shaped like a finding with a title, a severity, a location and a description. They are candidates only. They are not added to your organisation's findings, they were not checked independently, and they were not reproduced. To have one confirmed, run a review or a pentest that covers the code.
A triage verdict ("kind": "triage"): the verdict on one existing finding, from finding-triage. It is recorded on the finding and shown in the finding's triage verdict and trace. It does not change the finding's state: deciding stays with a person.
Every output ends with limits: what was not examined and what cannot be concluded. Nullgap adds to this list itself, for example when a tool was unavailable. A skill cannot remove entries from it.
#Comparing two versions
patch-diff-analysis compares two versions of an artefact and describes what changed, the flaw the change most likely fixed and its root cause with before and after code, a confidence, which versions are affected and how to check whether you are exposed. It does not write exploit code.
You can compare two refs of a connected repository:
curl -s -X POST -H "Authorization: Bearer $NULLGAP_API_KEY" \
-H "Content-Type: application/json" \
-d '{"skillId":"patch-diff-analysis","repoId":"repo_4c1d2e3f5a6b","baseRef":"v2.3.0","ref":"v2.3.1"}' \
"$NULLGAP_URL/api/orgs/$NULLGAP_ORG/skill-runs"
Or two uploaded files. Upload each version first; the request body is the file itself, and the display name goes in the name query parameter:
curl -s -X POST -H "Authorization: Bearer $NULLGAP_API_KEY" \
-H "Content-Type: application/octet-stream" \
--data-binary @library-2.3.0.jar \
"$NULLGAP_URL/api/orgs/$NULLGAP_ORG/skill-uploads?name=library-2.3.0.jar"
The answer carries the upload's id. Start the run with both ids:
curl -s -X POST -H "Authorization: Bearer $NULLGAP_API_KEY" \
-H "Content-Type: application/json" \
-d '{"skillId":"patch-diff-analysis","artifacts":{"before":"sku_1a2b3c4d5e6f","after":"sku_6f5e4d3c2b1a"}}' \
"$NULLGAP_URL/api/orgs/$NULLGAP_ORG/skill-runs"
| Uploads | |
|---|---|
| Accepted | Source archives (.zip, .tar.gz), Java archives (.jar, .war, .ear) and .NET files (.dll, .exe, .nupkg) |
| Largest file | 200 MB |
| Kept at a time | 20 per organisation. DELETE /api/orgs/:org/skill-uploads/:id removes one |
| Kept for | 7 days, then removed |
| Listing | GET /api/orgs/:org/skill-uploads |
An upload is unpacked under the same rules as an uploaded source archive. The comparison itself is done by code: files are hashed and compared, and changed files are ranked by how likely they are to be a security fix. Compiled code is decompiled in the sandbox when a decompiler is installed on the installation; when none is, the run says what it could not read.
#From an MCP client
run_skill starts a run and get_skill_run reads it; list_skills shows the catalogue and the uploads available for a comparison. Starting needs a write key. See MCP tools.
#Limits
| Limit | Value |
|---|---|
| Text supplied to a run | 200,000 characters through the API, 100,000 through the MCP tool |
| Time for one skill | Set by the skill, between 1 and 30 minutes |
| Usage | A run stops when it reaches its own usage limit or your workspace's monthly ceiling, and says so |
A run that fails says why in error, and its log has the detail. See getting help.
Nullgap documentation