openskills

A curated collection of agent skills — reusable capability packs that plug into skill-aware coding agents like Codex, Claude, and Cursor. Each skill is self-contained: one folder, one SKILL.md entry point, plus the scripts and references needed to do the job well.

This repository is a multi-skill collection. The discovery convention is:

skills/<skill-name>/SKILL.md

That is the same collection layout used by repositories such as obra/superpowers, where one repo publishes multiple independently installable skills.

How This Collection Works

You can treat this repository in two ways:

1. As a collection: install GargantuaX/openskills and let your agent discover any bundled skill.
2. As a package of individual skills: install only the one sub-skill you want, such as nanobanana or gpt-image-2.

In other words, the repository itself is the distribution unit, while each skills/<name>/ directory is an installable skill unit.

What is a skill?

A skill is a small, versioned folder that teaches an agent how to perform a specific task reliably:

• SKILL.md — the agent-facing manual: triggers, workflow, rules, examples.
• scripts/ — deterministic code the agent can execute instead of re-deriving logic.
• references/ — deep docs loaded on demand.
• agents/ — optional runtime-specific registration files (e.g. Codex YAML).

Skills follow the skill-creator conventions: concise frontmatter (name + description), imperative workflow, one source of truth per topic.

Skills in this repo

Repository layout

openskills/
└─ skills/
   └─ <skill-name>/
      ├─ SKILL.md
      ├─ README.md        # optional, human-facing
      ├─ agents/          # optional, runtime registration
      ├─ references/      # optional, deep docs
      ├─ scripts/         # optional, executable helpers
      └─ assets/          # optional, templates and sample files

Using a skill

Most skills are designed to be consumed two ways:

1. By an agent — install either the full collection or a single skill through Skills.
2. By hand — read the skill's own README.md for human-facing setup, then run scripts/ directly from a terminal.

Install the full collection:

pnpm dlx skills add GargantuaX/openskills

For Codex specifically, a simpler option is to junction the repository's skills/ directory into your local agent skills root instead of copying skills into many agent-specific folders. See .codex/INSTALL.md.

Install one skill from the collection:

pnpm dlx skills add https://github.com/GargantuaX/openskills --skill nanobanana
pnpm dlx skills add https://github.com/GargantuaX/openskills --skill gpt-image-2

skills.sh ecosystem docs also show a shorthand form for single-skill installs:

pnpm dlx skills add GargantuaX/openskills@nanobanana
pnpm dlx skills add GargantuaX/openskills@gpt-image-2

Prefer the --skill form in human-facing docs when you want the most explicit command. Use the owner/repo@skill shorthand when brevity matters or when another tool expects a single package-like token.

Each skill folder documents its own requirements, configuration, and commands. Start there.

Quick Setup

For the fastest path:

1. Install the full repo with pnpm dlx skills add GargantuaX/openskills, or install one skill with either pnpm dlx skills add https://github.com/GargantuaX/openskills --skill <name> or pnpm dlx skills add GargantuaX/openskills@<name>.
2. Open the target skill's README.md.
3. Copy the repository-level .env.example or the skill's documented .env example, then set your own API key and endpoint.
4. Run that skill's documented --dry-run command first to verify configuration before making live API calls.

For the current image skills, detailed setup and env vars are documented in skills/gpt-image-2/README.md, skills/gpt-image-2/references/config.md, skills/nanobanana/README.md, and skills/nanobanana/references/config.md.

Shared .env Strategy

For this collection, the recommended setup is to keep one shared .env at your project root and let each skill inherit from it.

The current lookup order is:

1. --env-file <path>
2. Process environment variables
3. The nearest .env found by searching from the current working directory upward through parent directories
4. Built-in defaults

This means you can place a single .env in a project root and run gpt-image-2 or nanobanana from nested subdirectories without duplicating config files.

Adding a new skill

1. Scaffold a new folder under skills/ (e.g. via skill-creator).
2. Write SKILL.md with a frontmatter name and a trigger-rich description.
3. Put deterministic logic in scripts/, deep docs in references/, templates in assets/.
4. Validate the layout (quick_validate.py from skill-creator, or equivalent).
5. Add an entry to the Skills in this repo table above.

Conventions

• Skills must be self-contained; do not share code across skills at the repo level.
• Keep SKILL.md body ASCII-friendly when tooling reads it with the platform default encoding.
• Prefer the standard library and zero third-party dependencies in scripts/ unless there is a clear reason not to.
• Never commit API keys or other secrets; rely on environment variables and .env files that are gitignored.

License

MIT. See LICENSE.