nexus-skills

Voice intents as data — one GitHub repo, every Nexus client.

This is the catalog of Nexus skills, served as plain JSON over HTTPS. Every Nexus host — the Android app today, the desktop/web app tomorrow — fetches index.json from this repo on launch, then pulls only the packs each device wants. Skills are data, not code, so a PR is just a JSON diff and ships to every client on next launch.

If you are looking for the Nexus application itself (installer, source code, app icon), see the Nexus umbrella repo. This repo only holds skill packs.

---

Live endpoints

Resource	URL
Registry (entry point)	https://raw.githubusercontent.com/TVcraft01/Nexus/main/index.json
Core pack manifest	https://raw.githubusercontent.com/TVcraft01/Nexus/main/skills/core/manifest.json
Manifest JSON Schema	https://raw.githubusercontent.com/TVcraft01/Nexus/main/schemas/skill-manifest.v1.json
Registry JSON Schema	https://raw.githubusercontent.com/TVcraft01/Nexus/main/schemas/registry.v1.json

All four are stable across versions and serve application/json with permissive CORS — hosts cache by ETag.

---

Current packs

From index.json:

Pack ID	Version	Status	Min Nexus
com.nexus.skills.core	1.0.0	bundled (always on)	1.7.0
com.nexus.skills.productivity	1.0.0	opt-in	1.7.0

The core pack currently ships 62 intents mirroring the Android host's Skills.CATALOGUE — see skills/core/manifest.json. The productivity pack stubs the shopping / todo / note intents described in SPEC.md Appendix A; they're awaiting an executor on the Android host.

---

Layout

nexus-skills/
├── README.md                       ← you are here
├── CONTRIBUTING.md                 ← how to add or edit a pack
├── index.json                      ← registry of every pack + their URLs/etags
├── schemas/
│   ├── skill-manifest.v1.json      ← JSON Schema for skills/*/manifest.json
│   └── registry.v1.json            ← JSON Schema for index.json
├── skills/
│   ├── core/manifest.json          ← bundled-by-default intents
│   └── productivity/manifest.json  ← opt-in productivity pack
└── scripts/
    ├── generate_core_manifest.py   ← re-emit skills/core/manifest.json from Skills.kt
    ├── validate.py                 ← schema-validate index.json + every pack
    └── doctor.py                   ← (planned Phase 3) cross-check executors vs host

nexus-skills ships zero per-platform code. The whole point is that every client reads the same JSON.

---

How a host consumes it

At app start, every Nexus client:

1. GET /index.json with If-None-Match: <last-etag>. 304 ⇒ skip.
2. For each enabled pack: GET /skills/<id>/manifest.json with If-None-Match: <etag>. 304 ⇒ skip.
3. Schema-validate the body against schemas/skill-manifest.v1.json.
4. Cross-check every intents[].executor against the host's local SkillExecutorRegistry. Unknown executor ⇒ skip only that intent, keep the rest of the pack.
5. Cross-check min_nexus_version ≤ host_version, device_compatibility and os against the host identity. Skip the pack on mismatch.
6. IntentResolver.resolve() runs against the validated union of bundled + remote packs.

No background polling — updates happen on app launch. The user can force-refresh from the host's "Skills" settings screen. On network failure, cached manifests are used and a non-blocking banner surfaces on the host's DiagnosticsActivity.

Full protocol, failure-mode table, and design rationale: SPEC.md in the umbrella repo.

---

What an intent looks like

Each pack is a single manifest.json matching schemas/skill-manifest.v1.json:

{
  "$schema": "https://raw.githubusercontent.com/TVcraft01/Nexus/main/schemas/skill-manifest.v1.json",
  "id": "com.nexus.skills.productivity",
  "name": "Productivity Pack",
  "version": "1.0.0",
  "min_nexus_version": "1.7.0",
  "device_compatibility": ["phone", "tablet", "desktop"],
  "os": ["android", "linux", "windows", "macos"],
  "locale": ["en-US"],
  "permissions": ["storage:write"],
  "intents": [
    {
      "name": "shopping_add",
      "title": "Add to Shopping List",
      "phrases": ["add {item} to my shopping list", "put {item} on the list"],
      "params": [{ "name": "item", "type": "string", "required": true }],
      "executor": "shopping_add",
      "examples": ["add milk to my shopping list"],
      "requires_confirmation": false
    }
  ]
}

• phrases — natural-language patterns with {param} slots; the resolver matches at decision time.
• executor — the host's local skill handler. Not defined here; the host's SkillExecutorRegistry owns it.
• requires_confirmation: true — destructive intents (*_clear, wipe_*, delete_*) surface a "did you really mean X?" prompt before executing. Default is false.
• permissions — exact strings the host checks against its permission system before enabling the pack.

Full schema reference: schemas/skill-manifest.v1.json.

---

Validate locally

# 1. Install jsonschema (one-time)
pip install --user jsonschema

# 2. Validate a single manifest
python3 scripts/validate.py skills/<pack-id>/manifest.json

# 3. Validate index.json + every pack in the repo
python3 scripts/validate.py --all

# 4. Re-emit the core pack from Skills.kt (idempotent; safe to run repeatedly)
python3 scripts/generate_core_manifest.py

CI runs validate.py --all on every PR and push to main. PRs that fail schema validation do not merge.

---

Add or edit a pack

See CONTRIBUTING.md. Short version:

1. Create skills/<your-pack>/manifest.json (use skills/core/manifest.json as the structural template).
2. Validate: python3 scripts/validate.py skills/<your-pack>/manifest.json.
3. Add an entry to index.json under packs[]. Bump generated_at to the current UTC time.
4. Confirm every intents[].executor you reference ships on at least one host (Android today; desktop/web later). Cross-reference: Android app/src/main/java/com/nexusandroid/app/Skills.kt + MainActivity.executeSkill.
5. Open a PR. Title format: [skills/<id>] <one-line summary>.

PR title conventions, semver bump rules, and reviewer checklist are in CONTRIBUTING.md.

---

Roadmap

Phase	Status	Scope
0	shipped	SPEC.md — design contract
1	shipped	this repo: schemas + registry + 62 verbatim intents from Skills.CATALOGUE + generator + validator
2	next	Android loader: SkillPackFetcher, SkillManifestValidator, SkillPackStore, SkillExecutorRegistry
3	planned	nexus-skills CLI (Rust single binary) + GitHub Actions CI on every PR
4	planned	Desktop port — reuses these JSON files verbatim
5	later	Web port (browser fetch() + localStorage)

Open questions (signing, marketplace, self-host vs public) are tracked in SPEC.md §13.

---

License

Skill packs are released under the same terms as the host Nexus application. Adding a pack to this repo affirms you have the right to ship the phrases and the executor side-effects it describes.

Yours completely. Open source. Grows with you.