chuk-skills

The skill catalog for Chuk Chat. Each skill is a folder holding a SKILL.md (and optionally references/, scripts/, assets/ sub-folders). The app fetches index.json — a manifest carrying every skill's name, description, content hash and resource list — then pulls bodies and resources lazily.

Skills follow the open Agent Skills spec: https://agentskills.io/specification

Layout

index.json                 # generated manifest — the client fetches this first
skills/
  <skill-name>/
    SKILL.md               # required: YAML frontmatter + Markdown body
    references/            # optional: docs the agent reads on demand
    scripts/               # optional: code (run by the agent's own tools)
    assets/                # optional: templates, data files
tools/
  gen_index.py             # regenerates index.json from the skills/ tree

SKILL.md frontmatter

Required: name (1-64 chars, lowercase a-z0-9 and single hyphens, must equal the folder name) and description (≤1024 chars, says what the skill does and when to use it). Optional: license, compatibility, metadata (a flat string map — a version goes here, e.g. version: "1.0"), allowed-tools (a space-separated string), and the two toggles below (which live inside metadata).

---
name: browser-skill
description: Drive a headless browser. Use when a task needs a real page render.
license: Apache-2.0
allowed-tools: bash
metadata:
  version: "1.0"
  enabled: "true"
  cowork_only: "false"
---

Instructions go here.

Toggles: enabled and cowork_only

Both live inside metadata and both default sensibly, so leave them out unless you want to change them. They sit in metadata because the client's frontmatter parser rejects unknown top-level keys — a stray top-level key would make the whole SKILL.md fail to load. Write them as quoted strings ("true" / "false"); the generator hoists them to real booleans in index.json, so the manifest doubles as a switch panel you can flip by hand.

• enabled (default true) — set to "false" to make a skill vanish. It stays in the manifest but the client never exposes it to the model. A pristine stored copy is dropped and comes back if you re-enable it; a copy the user edited is left alone (their edits are never auto-deleted).
• cowork_only (default false) — set to "true" to offer the skill only while the app is in CoWork mode. It is hidden from the normal chat UI. Use it for skills that are useless in plain chat — browser-to-curl is marked this way because its whole job is driving a machine, which only CoWork does.

Flip either one in the SKILL.md metadata and regenerate, or edit the boolean directly in index.json for a quick toggle without touching the source.

How updates reach users

The app stores each user's copy of a skill locally and remembers the catalog hash it was seeded from. On refresh:

• a skill the user does not have yet is added automatically;
• a skill the user never edited is updated silently when its hash changes;
• a skill the user edited gets an update suggestion, never a silent overwrite.

So editing a skill here and regenerating the manifest is all it takes to push a change to every client.

Adding or changing a skill

1. Create or edit skills/<name>/SKILL.md (and any sub-folders).
2. Run python3 tools/gen_index.py to regenerate index.json.
3. Commit and push. Clients pick it up on their next catalog refresh.

The generator validates the frontmatter, enforces name == folder name, and computes each skill's content hash. Do not hand-edit the computed fields (hash, resources); the enabled and cowork_only toggles are the only values safe to flip by hand.