Overview
- One package, every agent. A NeoSpark Skill installs into Claude Code, Codex, Cursor, GitHub Copilot, and any other agent that reads SKILL.md.
- Two ways to build. Use the NeoSpark Skill Creator Skill inside your agent, or write SKILL.md and the tool scripts yourself.
- Validate before upload. The platform runs the same checks locally and on upload; fix errors early to avoid review delays.
Before you start
- An agent that reads
SKILL.md— Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, Windsurf, Cline, Grok or any agent listed on the install page. - A NeoSpark account if you plan to upload and publish.
- Basic familiarity with Markdown; Python is only needed for subprocess Skills.
Use the NeoSpark Skill Creator
The fastest way to build a Skill is to install the NeoSpark Skill Creator Skill in your agent. It scaffolds a spec-compliant package, adds media adapters when needed, validates the result, and produces the upload-ready ZIP.
Install the Skill Creator
Copy this prompt into Claude Code, Codex, or any supported agent:
Read https://useneospark.com/install/agent.md and follow the instructions to connect NeoSpark, then install the NeoSpark Skill Creator Skill (neospark_skill_creator) and use it for my next task.Create a Skill with the creator
Once the creator is installed, describe what you want. For example:
“Build a Skill that turns messy meeting notes into a decision log with owners and due dates.”
The creator asks the one question that matters for packaging: does it generate images, video, or files? It then:
- Scaffolds a draft with correct frontmatter and execution mode.
- Writes the SKILL.md body, replacing placeholders with your workflow.
- Adds Python tools if the Skill needs files, APIs, or media.
- Validates the package and reports concrete errors.
- Builds the ZIP, excluding local artifacts and credentials.
Creator tools
| Tool | Use it to |
|---|---|
| scaffold_skill | Start a draft package from a short brief |
| render_skill | Write a complete authored skill and optionally build the ZIP |
| validate_skill | Check a directory, file or ZIP and get exact errors |
| package_skill | Validate and produce the upload-ready ZIP |
Install the creator from the packaged ZIP
Download the ready-to-install package and upload it through your agent’s Skill installer, or place it in your agent’s skills directory.
Example: build a product-shot Skill
With the creator installed, paste this request into your agent:
Build a NeoSpark Skill called product-shot-studio that generates clean e-commerce product images from a description or a reference photo. It should be a subprocess skill with image media support.The creator will:
- Scaffold the package at
out/product-shot-studio. - Write the SKILL.md manifest with
execution_mode: subprocessand image generation tools. - Validate the package and build
product-shot-studio.zip.
Upload the resulting ZIP to useneospark.com/publish.
Creator source
The full source for the NeoSpark Skill Creator is available at E:\project\neospark_skill_creator. You can also copy that directory into ~/.claude/skills/neospark_skill_creator.
Write a Skill by hand
A Skill package is a folder with SKILL.md at its root and, for subprocess Skills, the Python scripts and requirements.txt it declares.
Minimum folder shape for a prompt-only Skill:
my-skill/
└── SKILL.mdMinimum folder shape for a subprocess Skill:
my-skill/
├── SKILL.md
├── requirements.txt
└── scripts/
└── my_tool.pyPackage format and limits
A submission is either a single SKILL.md file or a ZIP archive.
- Single Markdown file: maximum 512 KB.
- ZIP archive: maximum 20 MB compressed, 100 MB uncompressed, 200 files.
- The platform searches the archive for
SKILL.mdat any depth, case-insensitively. - All paths must stay inside the package; path-traversal entries are rejected.
- The frontmatter
idtakes precedence over any form value.
The SKILL.md manifest
SKILL.md starts with YAML frontmatter, followed by Markdown body text. The body explains what the Skill does, how to invoke it, and the shape of inputs and outputs.
| Field | Rule |
|---|---|
id | Unique lowercase slug: ^[a-z0-9][a-z0-9_-]{0,63}$ |
name | Public English title |
description | What it does and when to use it; this triggers the model |
version | major.minor.patch |
model | Optional; defaults to anthropic:claude-opus-5 |
tools | Optional platform tool names available to the Skill |
dependencies | Optional IDs of other Skills this Skill depends on |
execution_mode | inline or subprocess |
scripts | Tool name → Python path relative to SKILL.md |
file_generating_scripts | Subset of scripts whose files the user receives |
tool_inputs | Per-tool JSON parameter guidance |
env_whitelist | Environment variables the scripts read |
requirements | requirements.txt beside SKILL.md |
The description is the most important field for triggering. Name the tasks and phrasing a user would actually say. A description like “SEO helper” is too vague; “Turn a brief into a keyword-optimised outline and meta description” is not.
Choose an execution mode
| Mode | Use when | Result |
|---|---|---|
inline | Instructions, rewrite, classify | No scripts; one Markdown file |
inline + fenced Python | Compute on given text | Sandboxed Python inside SKILL.md; no file I/O or network |
subprocess | API calls, files, packages | Python scripts in the package; requirements installed |
subprocess + file_generating_scripts | Images, video, downloadable files | Declared file-producing tools return files to the user |
The most common mistake is putting an HTTP call or file write inside inline Python. The inline sandbox blocks imports like requests and calls like open(). If a step needs the network or filesystem, use subprocess.
Add scripts
Subprocess tools are Python scripts. Each entry in scripts becomes a tool named <skill_id>_<tool_name>.
The platform invokes each script with an output directory and a JSON payload:
python scripts/my_tool.py --output-dir <dir> --input-json '<json>'- Exit
0whether the operation succeeded or failed; report failure as JSON. - Print exactly one JSON line on stdout; diagnostics go to stderr.
- Combined stdout and stderr are capped at 10 MB.
- Write user-facing files inside
--output-dironly. - List the tool in
scripts; if it returns files, also list it infile_generating_scripts. - Respect the 300-second hard limit; for long work, persist an id and return
timed_out: true.
Add image or video
When a Skill generates images or video, prefer NeoSpark’s own APIs. The NeoSpark Skill Creator can copy working adapters into the package, or you can add them manually.
scripts/generate_image.py— text-to-image and image-to-image, with reference uploads, polling and downloads.scripts/generate_video.py— text-to-video, first/last-frame, reference media, and document-to-video.scripts/get_video_task.py— collect a video task later instead of resubmitting.scripts/list_models.py— read live model ids, resolutions and prices.
Declare NEOSPARK_API_KEY in env_whitelist; the platform injects it. Never ask for a key, print one, or package one.
Default to gemini-3.1-flash-image at 1K / 1:1 for images and seedance-2.0 at 5 s / 16:9 / 720p for video unless the request needs a capability the default lacks.
Validate and package
Validation catches mechanical problems before upload. The NeoSpark Skill Creator runs the same checks as the platform uploader.
Common validation errors
| Error | Fix |
|---|---|
missing_script | The path in scripts does not exist; correct it or add the file. |
script_outside_package | Use a path relative to SKILL.md without .. |
missing_manifest | Exactly one SKILL.md must exist, anywhere in the package. |
missing_tool_inputs | Describe each tool’s JSON input. |
unknown_file_generating_script | Only list tool names that exist in scripts. |
inline_blocked_import | Move network or file work to a subprocess script. |
inline_too_long | Keep inline Python under 500 merged lines, or switch mode. |
possible_secret | Remove credentials; the platform injects them via env_whitelist. |
Package the Skill as a ZIP with the tool scripts and requirements excluded from junk. Re-validate the ZIP before uploading.
Upload to NeoSpark
Go to useneospark.com/publish, upload the ZIP, and submit it for review. The review checks:
- A manifest with version, output and declared execution mode.
- A SKILL.md the agent can follow without you in the room.
- Previews rendered from work the Skill actually produced.
- No secrets, and no network call the manifest does not declare.
- A protection declaration confirming server-side execution and creator ownership.
Upload details:
- The endpoint is
POST /api/v1/skills/upload. - A Skill ID that is already registered or pending returns a 409 conflict.
- Up to 10 preview images are allowed, each no larger than 5 MB; the first image becomes the catalogue cover.
- If you do not upload preview images, the form uses the NeoSpark logo as a default placeholder.
Author checklist
- Use a unique, lowercase Skill ID and a valid semantic version.
- Write the public title and description in English.
- Keep SKILL.md instructions specific enough for an agent to follow without extra context.
- Use a ZIP whenever the manifest references external scripts.
- Make every
scriptspath point to an existing Python file inside the package. - List file-producing tools in
file_generating_scriptsand document their inputs intool_inputs. - Request only necessary environment variables and never package secrets.
- Include up to 10 representative preview images, with the intended cover first.
Reference
- Skill specification: /neospark-skill-spec.md
- Install guide: /install/
- Publish page: /publish/
- NeoSpark Skill Creator source:
E:\project\neospark_skill_creator - API reference: api.useneospark.com/docs