Hosting a GitHub Skillset

You can host your own skillset as a GitHub repository. Once published, anyone with access to the repository can add it to their SuperAgent instance and install skills from it.

Repository structure

A skillset repository has a flat structure with an index.json manifest at the root and skill directories organized under a skills/ folder.

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

Each skill lives in its own directory under skills/. The directory name becomes the skill's identifier -- it is used as the folder name when the skill is installed into an agent's workspace.

Naming conventions

• Use kebab-case for skill directory names (e.g., email-triage, nda-review). SuperAgent converts these to Title Case for display (e.g., "Email Triage").
• Keep directory names short and descriptive. They must not contain path separators, .., or other special characters.

The index.json manifest

The index.json file at the repository root is the entry point that SuperAgent reads when it clones or refreshes a skillset. It declares the skillset metadata and lists every skill available in the repository.

{
  "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 include agent templates alongside skills. Agent templates are listed in an optional agents array in index.json:

{
  "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. This file uses YAML frontmatter for metadata and Markdown for the skill's 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 skill's instructions in Markdown. This is what the agent reads and follows when the skill is invoked. Be specific, step-by-step, and clear about what the agent should do.

---
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 response within 1 hour
   - **Action Required** -- requires 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

Skills can include additional files alongside SKILL.md. These are copied to the agent's workspace when the skill is installed. Common uses include:

• Templates -- Output format templates, checklists, or boilerplate text.
• Reference data -- JSON or CSV files with lookup tables, schemas, or configuration.
• Examples -- Sample inputs and outputs to guide the agent.

All files in the skill directory (except internal metadata files like .skillset-metadata.json) are part of the skill package.

Versioning

Each skill in a skillset has its own version, declared both in the index.json manifest and in the SKILL.md frontmatter. SuperAgent uses these versions to detect when updates are available.

Version conventions

Follow Semantic Versioning:

• PATCH (e.g., 1.0.0 to 1.0.1) -- Bug fixes, typo corrections, minor wording tweaks.
• MINOR (e.g., 1.0.0 to 1.1.0) -- New features, added capabilities, significant improvements.
• MAJOR (e.g., 1.0.0 to 2.0.0) -- Breaking changes, fundamental restructuring.

How updates are detected

SuperAgent determines that an update is available when either:

1. The version field in index.json for a skill differs from the version recorded when it was installed.
2. The content hash of the skill's files in the repository differs from the hash recorded at install time.

This means that even if you forget to bump the version number, SuperAgent will still detect content changes. However, bumping the version is recommended so that users can see what changed.

Keeping versions in sync

The version in index.json and the version in SKILL.md frontmatter should match. When SuperAgent generates PR suggestions for skill modifications, it proposes a new version based on the nature of the changes.

Sharing your skillset

Public repositories

If your repository is public on GitHub, anyone can add it to their SuperAgent instance:

1. Share the repository URL (e.g., 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 (download-only, no Git required).

Private repositories

For private repositories, users need read access to the repository. They also need SSH authentication configured for Git, since SuperAgent clones with GIT_TERMINAL_PROMPT=0 (no interactive prompts).

To set up SSH access:

1. Generate an SSH key if you do not have one.
2. Add the public key to your GitHub account.
3. Use the SSH URL when adding the skillset (e.g., git@github.com:your-org/your-skillset.git).

Accepting contributions

When users modify installed skills and submit pull requests, the PRs are created against your repository. The standard GitHub pull request workflow applies -- you can review changes, request modifications, and merge when ready.

SuperAgent's PR flow works as follows:

1. The contributor forks your repository (via the GitHub CLI).
2. A branch is created with the modified skill files.
3. A pull request is opened from the contributor's fork to your repository's default branch.

The PR title, description, and version bump are AI-generated based on the diff, but the contributor can edit them before submitting.

Quick start checklist

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