Hosting a GitHub Skillset

Repository structure

A skillset repository has an index.json manifest at the root and one directory per skill under skills/:

my-skillset/
  index.json
  skills/
    email-triage/
      SKILL.md
    nda-review/
      SKILL.md
      templates/
        review-checklist.md
    database-query/
      SKILL.md
      schema-reference.json

The directory name is the skill's identifier and becomes the folder name when the skill is installed into an agent's workspace.

Naming conventions

• Use kebab-case for directory names (email-triage, nda-review). Gamut converts them to Title Case for display ("Email Triage").
• Keep names short and descriptive. Path separators, .., and other special characters are not allowed.

The index.json manifest

Gamut reads index.json whenever it clones or refreshes the skillset:

{
  "skillset_name": "Acme Team Skills",
  "description": "Shared skills for the Acme engineering and ops team.",
  "version": "1.0.0",
  "skills": [
    {
      "name": "Email Triage",
      "path": "skills/email-triage/SKILL.md",
      "description": "Triages incoming emails by urgency and category.",
      "version": "1.0.0"
    },
    {
      "name": "NDA Review",
      "path": "skills/nda-review/SKILL.md",
      "description": "Reviews NDAs for standard clause coverage.",
      "version": "2.1.0"
    },
    {
      "name": "Database Query",
      "path": "skills/database-query/SKILL.md",
      "description": "Queries a PostgreSQL database and formats results.",
      "version": "1.3.0"
    }
  ]
}

Required fields

Skill entry fields

Each entry in the skills array describes one skill:

Agent templates (optional)

Skillsets can also ship agent templates, listed in an optional agents array:

{
  "skillset_name": "Acme Team Skills",
  "description": "...",
  "version": "1.0.0",
  "skills": [...],
  "agents": [
    {
      "name": "Research Assistant",
      "path": "agents/research-assistant/",
      "description": "Pre-configured agent for research workflows.",
      "version": "1.0.0"
    }
  ]
}

Writing a SKILL.md file

Each skill directory must contain a SKILL.md file: YAML frontmatter for metadata, Markdown for the instructions.

Frontmatter format

---
name: Email Triage
description: Triages incoming emails by urgency and category.
metadata:
  version: 1.0.0
  required_env_vars:
    - name: GMAIL_FILTER_LABEL
      description: Gmail label to filter incoming messages
---

Top-level fields:

Metadata fields (nested under metadata):

Each entry in required_env_vars has:

Skill body

After the frontmatter, write the instructions the agent follows when the skill is invoked. Be specific and step-by-step.

---
name: Email Triage
description: Triages incoming emails by urgency and category.
metadata:
  version: 1.0.0
---
 
# Email Triage
 
When asked to triage emails, follow this process:
 
1. Fetch unread emails from the inbox.
2. For each email, classify it into one of these categories:
   - **Urgent**: requires a response within 1 hour
   - **Action Required**: requires a response within 24 hours
   - **Informational**: no response needed
   - **Spam**: can be archived
3. Present a summary table sorted by urgency.
4. For urgent items, draft a brief response for review.

Supporting files

Files alongside SKILL.md are copied to the agent's workspace at install time. Common uses:

• Templates: output formats, checklists, boilerplate text.
• Reference data: JSON or CSV lookup tables, schemas, configuration.
• Examples: sample inputs and outputs that guide the agent.

Everything in the skill directory is part of the skill package, except internal metadata files like .skillset-metadata.json.

Versioning

Each skill carries its own version, declared in both index.json and the SKILL.md frontmatter. The two should match; Gamut's PR suggestions propose a bump automatically when a skill changes.

Follow Semantic Versioning:

• PATCH (1.0.0 to 1.0.1): bug fixes, typos, minor wording tweaks.
• MINOR (1.0.0 to 1.1.0): new features, added capabilities.
• MAJOR (1.0.0 to 2.0.0): breaking changes, fundamental restructuring.

How updates are detected

Gamut reports an update when either the skill's version in index.json or the content hash of its files differs from what was recorded at install. A forgotten version bump still surfaces as an update through the content hash, but bumping the version shows users what changed.

Sharing your skillset

Public repositories

Anyone can add a public repository:

1. Share the repository URL (https://github.com/your-org/your-skillset).
2. The recipient opens Settings > Skillsets, pastes the URL, and clicks Add.

Public repositories work with both the GitHub provider (requires Git) and the public provider (ZIP download, no Git required).

Private repositories

Private repositories require read access and SSH authentication, since Gamut clones with GIT_TERMINAL_PROMPT=0 and cannot answer interactive prompts.

To set up SSH access:

1. Generate an SSH key if none exists.
2. Add the public key to the GitHub account.
3. Use the SSH URL when adding the skillset (git@github.com:your-org/your-skillset.git).

Accepting contributions

When users modify installed skills and submit them, pull requests are opened against the repository:

1. Gamut forks the repository via the GitHub CLI.
2. A branch is created with the modified skill files.
3. A pull request is opened from the fork against the default branch.

The PR title, description, and version bump are AI-generated from the diff; contributors can edit them before submitting. The standard GitHub review workflow applies from there.

Quick start checklist

1. Create a new GitHub repository.
2. Add an index.json at the root with the skillset name and an empty skills array.
3. Create a skills/ directory.
4. For each skill, add a subdirectory with a SKILL.md containing frontmatter and instructions.
5. List each skill in the skills array with its name, path, description, and version.
6. Push to GitHub and share the repository URL.