Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/XxYouDeaDPunKxX/ChatGPT-SKILL-SYSTEM/llms.txt

Use this file to discover all available pages before exploring further.

The repository includes scripts/build_packages.py, a Python build script that creates and validates the core package and all skill packages in a single run. It enforces ZIP structure rules, POSIX path separator requirements, path safety, and manifest correctness before writing any output to dist/. If any validation step fails, the script exits immediately with a descriptive error — no partial output is written.

​
Running the build

From the repository root, run: 
python scripts/build_packages.py
On a successful build, the script prints one line per package written: 
built dist/GPT.SKILLS.zip
built dist/skills/skill-adapter.zip
No output is written until all validations pass for a given package.

​
What the build script does

The script processes the core and all skills in a fixed sequence:
1

Build the core package

Reads the GPT.SKILLS/ source directory and packages it as dist/GPT.SKILLS.zip. The ZIP must have SYSTEM_CORE/ and SKILLS/ at its root — there must be no GPT.SKILLS/ wrapper folder inside the archive. The script validates the core manifest, required file presence, UTF-8 readability, load sequence, and POSIX path separators.
2

Build each skill package

For each subdirectory under skill_sources/ that contains a MANIFEST.json, the script reads and validates the manifest, then packages the skill as dist/skills/<skill_name>.zip. The source folder name must match skill_name in the manifest.
3

Write with POSIX path separators

All ZIP entries are written using POSIX / path separators. Backslashes (\) in any entry name are a hard fail. The script calls .as_posix() on every path before writing it to the archive.
4

Validate each ZIP after writing

After writing each ZIP, the script reopens it and validates the archive again — checking entry names, manifest fields, wrapper directory detection, and nested ZIP detection. This post-write check catches any discrepancy between source validation and the written archive.

​
What is validated

The build script performs the following checks for every package it builds. Any failure is a hard stop.

Package shape

The ZIP root contents match the expected layout — SYSTEM_CORE/ and SKILLS/ for the core; MANIFEST.json at root for skills.

ZIP path separators

Every ZIP entry uses POSIX / separators. Any entry containing \ causes an immediate failure.

Manifest fields

Required fields are present and have the correct types. system_name and version are validated against exact expected values for the core.

Load files

All files in load_sequence exist, are readable as UTF-8, and are not scripts or binary assets.

Support files

All declared support_files exist and have safe relative paths.

Tool files

All declared tool_files exist and are readable as UTF-8.

Asset files

All declared asset_files exist and have safe relative paths.

Wrapper directory detection

The ZIP is checked for a single wrapper directory surrounding the package contents. Wrapper directories are a hard fail.

Unsafe path detection

Absolute paths, .. segments, drive letters, backslash paths, and empty path segments are all rejected.

Nested ZIP detection

No .zip file may appear inside a built package.

​
Repository layout

GPT.SKILLS/
  SYSTEM_CORE/
  SKILLS/

skill_sources/
  skill-adapter/

dist/
  GPT.SKILLS.zip
  skills/
    skill-adapter.zip

docs/
  ADAPTING_A_SKILL.md
  PACKAGING.md
  SKILL_PACKAGE_FORMAT.md

scripts/
  build_packages.py
The dist/ directory is the build output directory. It is created automatically on the first build run. The GPT.SKILLS/ and skill_sources/ directories are the source inputs — never edit files in dist/ directly.

​
Adding your own skills

To include a new skill in the build:
  1. Create a folder under skill_sources/<skill-name>/. The folder name must match the skill_name you intend to use.
  2. Add MANIFEST.json with at minimum skill_name and version.
  3. Add your skill files — at minimum SKILL.md for fallback mode, or the file declared as primary_file for explicit mode.
  4. Run the build: 
    python scripts/build_packages.py
The built ZIP appears at dist/skills/<skill-name>.zip. If validation fails, the script prints the specific error and exits before writing any output for that skill.

​
Core ZIP structure

The most common packaging mistake is creating a ZIP with a wrapper directory. If you zip the GPT.SKILLS/ folder itself rather than its contents, the archive root will contain GPT.SKILLS/ — and when the runtime extracts it, the paths resolve to /mnt/data/GPT.SKILLS/GPT.SKILLS/SYSTEM_CORE/, which is invalid. Always zip the contents of GPT.SKILLS/, not the folder.
SKILL CORE UNPACK extracts GPT.SKILLS.zip into /mnt/data/GPT.SKILLS/. For the extracted tree to be valid, the ZIP must contain SYSTEM_CORE/ and SKILLS/ directly at its root — not wrapped in a parent folder. Valid core ZIP root: 
GPT.SKILLS.zip
  SYSTEM_CORE/       ← at ZIP root
    MANIFEST.json
    ENTRY.md
    ...
  SKILLS/            ← at ZIP root
    README.md
Invalid core ZIP root: 
GPT.SKILLS.zip
  GPT.SKILLS/        ← wrapper folder, hard fail
    SYSTEM_CORE/
    SKILLS/
The build script enforces this rule automatically — it will fail with "core ZIP contains GPT.SKILLS wrapper" if the wrapper is detected. The same no-wrapper rule applies to all skill ZIPs: MANIFEST.json must appear at the skill ZIP root, never inside a subfolder named after the skill.

Build docs developers (and LLMs) love

Get started for freeTalk to us