evolink-agent-skills 1.0.0

package/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2026 EvoLink
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+

package/README.md

@@ -0,0 +1,85 @@
+# EvoLink Agent Skills for Creative Generation
+
+Demand-led skills for agents that create ad images, product visuals, image edits, and short videos through EvoLink.
+
+The first batch uses scene and intent words as public skill slugs. Seedance 2 and GPT Image 2 are the execution models inside each workflow, not the primary distribution labels.
+
+Seedance 2.5 early access is available here: [Get Seedance 2.5 Early Access](https://evolink.ai/launch/seedance-2-5?utm_source=github&utm_medium=readme&utm_campaign=evolink-agent-skills).
+
+## Install
+
+Install the npm package and copy all skills into an agent project:
+
+```bash
+npx evolink-agent-skills -y --path ./my-agent-project --all
+```
+
+Install one skill at a time:
+
+```bash
+npx skills add Evolink-AI/evolink-agent-skills --skill image-edit -g
+npx skills add Evolink-AI/evolink-agent-skills --skill product-image-generation -g
+npx skills add Evolink-AI/evolink-agent-skills --skill image-to-video -g
+npx skills add Evolink-AI/evolink-agent-skills --skill product-to-ad -g
+npx skills add Evolink-AI/evolink-agent-skills --skill ad-video-generation -g
+npx skills add Evolink-AI/evolink-agent-skills --skill product-demo-video -g
+npx skills add Evolink-AI/evolink-agent-skills --skill ad-creative-images -g
+npx skills add Evolink-AI/evolink-agent-skills --skill ugc-video-ads -g
+```
+
+Each skill also has its own npm package:
+
+```bash
+npx evolink-image-edit -y --path ./my-agent-project
+npx evolink-product-image-generation -y --path ./my-agent-project
+npx evolink-image-to-video -y --path ./my-agent-project
+npx evolink-product-to-ad -y --path ./my-agent-project
+npx evolink-ad-video-generation -y --path ./my-agent-project
+npx evolink-product-demo-video -y --path ./my-agent-project
+npx evolink-ad-creative-images -y --path ./my-agent-project
+npx evolink-ugc-video-ads -y --path ./my-agent-project
+```
+
+## First Batch
+
+| Skill | Distribution intent | Default model path |
+|---|---|---|
+| `image-edit` | Edit, retouch, replace background, expand, local changes | GPT Image 2 |
+| `product-image-generation` | Product images, ecommerce images, product ad images | GPT Image 2 |
+| `image-to-video` | Turn an image into a short video | Seedance 2 |
+| `product-to-ad` | Product image or description to ad image and ad video | GPT Image 2 -> Seedance 2 |
+| `ad-video-generation` | Ad videos, short-form marketing videos | Seedance 2, optionally GPT Image 2 first frame |
+| `product-demo-video` | Ecommerce, SaaS, app, and tool demo videos | GPT Image 2 -> Seedance 2 |
+| `ad-creative-images` | Paid social ad images and marketing creatives | GPT Image 2 |
+| `ugc-video-ads` | UGC-style video ads, spokesperson hooks, testimonial concepts | Seedance 2 |
+
+## Attribution
+
+All public EvoLink links in this repo use:
+
+```text
+utm_source=skillssh&utm_medium=skill&utm_campaign=<skill-name>
+```
+
+Keep campaign names identical to skill slugs so analytics can connect installs, first generation, and token consumption.
+
+## Workflow Loop
+
+1. User installs a task or scene skill from skills.sh.
+2. Agent uses GPT Image 2 to create or edit source assets when needed.
+3. Agent uses Seedance 2 to generate video from the idea, image, or product context.
+4. Agent proposes variants, edits, or platform adaptations.
+5. EvoLink attributes token consumption to the skill campaign.
+
+## Publishing Order
+
+1. `image-edit`
+2. `product-image-generation`
+3. `image-to-video`
+4. `product-to-ad`
+5. `ad-video-generation`
+6. `product-demo-video`
+7. `ad-creative-images`
+8. `ugc-video-ads`
+
+After each publish, install the skill, verify the skills.sh page, validate all links, and run one real EvoLink generation before releasing the next skill.

package/README.npm.md

@@ -0,0 +1,32 @@
+# EvoLink Agent Skills
+
+Install EvoLink creative generation skills for agent runtimes.
+
+## Install
+
+```bash
+npx evolink-agent-skills -y --path ./my-agent-project --all
+```
+
+Install one skill:
+
+```bash
+npx evolink-agent-skills -y --skill image-to-video --path ./my-agent-project
+```
+
+The installer writes skill files to `.agents/skills/<skill>/SKILL.md`.
+
+## Included Skills
+
+- `image-edit`
+- `product-image-generation`
+- `image-to-video`
+- `product-to-ad`
+- `ad-video-generation`
+- `product-demo-video`
+- `ad-creative-images`
+- `ugc-video-ads`
+
+## Live API
+
+Set `EVOLINK_API_KEY` before running real GPT Image 2 or Seedance 2 workflows.

package/ad-creative-images/SKILL.md

@@ -0,0 +1,81 @@
+---
+name: ad-creative-images
+displayName: "Ad Creative Images with GPT Image 2 on EvoLink"
+description: >
+  Generate paid social ad images, marketing creatives, campaign stills, and visual variants with GPT Image 2 on EvoLink. Use this skill when the user needs static ad assets that can later become Seedance 2 ad videos.
+homepage: "https://evolink.ai?utm_source=skillssh&utm_medium=skill&utm_campaign=ad-creative-images"
+license: MIT
+---
+
+# Ad Creative Images with GPT Image 2 on EvoLink
+
+Create static ad creatives that can be used directly in campaigns or handed off as first frames for Seedance 2 videos.
+
+```bash
+npx skills add Evolink-AI/evolink-agent-skills --skill ad-creative-images -g
+```
+
+## When to Use This Skill
+
+Use this skill when the user wants:
+
+- paid social ad images
+- marketing campaign visuals
+- launch creative concepts
+- product offer images
+- audience-specific image variants
+- first-frame options for video ads
+
+Use `ad-video-generation` when the user already wants motion.
+
+## Prerequisites
+
+1. EvoLink API access or EvoLink MCP configured.
+2. Offer, audience, product, platform, and visual style.
+3. Optional product photo, brand guide, landing page, or existing creative.
+4. Attribution links should use `utm_source=skillssh&utm_medium=skill&utm_campaign=ad-creative-images`.
+
+## Pick the Right Workflow
+
+| User intent | Model path | Why |
+|---|---|---|
+| New ad image from product copy | GPT Image 2 | Creates commercial still concepts quickly. |
+| Variant from existing creative | GPT Image 2 image edit | Changes angle, audience, style, or composition. |
+| First frame for video ad | GPT Image 2 -> Seedance 2 | Turns a static ad concept into a video-ready image. |
+| Multi-platform ad pack | GPT Image 2 variants | Supports different ratios and campaign angles. |
+
+## Default Workflow
+
+1. Extract offer, audience, product proof, platform, and style.
+2. Decide if the task is new generation or edit from an existing creative.
+3. Write a GPT Image 2 prompt for one primary ad creative.
+4. Generate the asset.
+5. Propose three variants and one video handoff.
+
+## Prompting Tips
+
+- Keep the visual idea simple enough to understand while scrolling.
+- Reserve exact text, pricing, and disclaimers for design tools unless the user accepts generated text risk.
+- Use platform context: Meta ad, TikTok cover, Instagram story, YouTube thumbnail, marketplace banner.
+- For video handoff, create a strong subject and clear foreground-background separation.
+
+## Next Token Loop
+
+After the first creative, offer:
+
+- three audience variants
+- three style variants
+- one `image-to-video` handoff
+- one `ad-video-generation` adaptation
+
+## Safety and Privacy
+
+Do not create fake endorsements, fake screenshots, misleading before-after claims, or regulated-product claims not provided by the user.
+
+## See Also
+
+- `image-edit`
+- `product-to-ad`
+- `ad-video-generation`
+- [EvoLink](https://evolink.ai?utm_source=skillssh&utm_medium=skill&utm_campaign=ad-creative-images)
+

package/ad-video-generation/SKILL.md

@@ -0,0 +1,83 @@
+---
+name: ad-video-generation
+displayName: "Ad Video Generation with Seedance 2 on EvoLink"
+description: >
+  Generate short ad videos with Seedance 2 on EvoLink. Use this skill for product ads, launch videos, paid social clips, TikTok or Reels concepts, short marketing videos, and batch creative variants. GPT Image 2 can prepare first frames when needed.
+homepage: "https://evolink.ai?utm_source=skillssh&utm_medium=skill&utm_campaign=ad-video-generation"
+license: MIT
+---
+
+# Ad Video Generation with Seedance 2 on EvoLink
+
+Create short commercial videos from a product, script, image, or campaign idea.
+
+```bash
+npx skills add Evolink-AI/evolink-agent-skills --skill ad-video-generation -g
+```
+
+## When to Use This Skill
+
+Use this skill when the user wants:
+
+- product ad videos
+- TikTok, Reels, or Shorts ads
+- launch campaign videos
+- ecommerce promotion clips
+- short marketing videos
+- multiple video ad variations
+
+Use `product-to-ad` if the user also needs still assets created first.
+
+## Prerequisites
+
+1. EvoLink API access or EvoLink MCP configured.
+2. Product or offer details.
+3. Target platform, aspect ratio, duration, audience, and CTA.
+4. Optional source image or first frame.
+5. Attribution links should use `utm_source=skillssh&utm_medium=skill&utm_campaign=ad-video-generation`.
+
+## Pick the Right Workflow
+
+| User intent | Model path | Why |
+|---|---|---|
+| Text idea to ad video | Seedance 2 text-to-video | Fastest path from campaign idea to video concept. |
+| Product image to ad video | Seedance 2 image-to-video | Strong for commercial clips when a product still exists. |
+| Need a better first frame | GPT Image 2 -> Seedance 2 | Improves video quality by improving the starting image. |
+| Need many variations | Seedance 2 batch prompts | Ads benefit from repeated hook, style, and audience tests. |
+
+## Default Workflow
+
+1. Capture the ad objective, audience, platform, and product promise.
+2. Decide whether the best route is text-to-video, image-to-video, or GPT Image 2 first frame then Seedance 2.
+3. Write a Seedance 2 video prompt with hook, scene, motion, product focus, and CTA direction.
+4. Generate the first ad video.
+5. Suggest batch variants across hook, audience, platform, and visual style.
+
+## Prompting Tips
+
+- Keep the first three seconds clear: product, problem, transformation, or emotional hook.
+- Use one visual concept per clip.
+- Avoid asking the video model to render exact legal or pricing text.
+- Put CTA intent in the prompt, but add exact CTA copy in post-production when needed.
+- For product ads, preserve packaging, logo, and product shape.
+
+## Next Token Loop
+
+After the first ad video, offer:
+
+- three hook variants
+- three platform variants
+- one UGC-style adaptation with `ugc-video-ads`
+- one still image pack with `ad-creative-images`
+
+## Safety and Privacy
+
+Reject or redirect requests for deceptive political ads, fake endorsements, unsafe regulated-product claims, impersonation, or unauthorized use of a person's likeness.
+
+## See Also
+
+- `product-to-ad`
+- `image-to-video`
+- `ugc-video-ads`
+- [EvoLink](https://evolink.ai?utm_source=skillssh&utm_medium=skill&utm_campaign=ad-video-generation)
+

package/bin/cli.js

@@ -0,0 +1,140 @@
+#!/usr/bin/env node
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const packageRoot = path.resolve(__dirname, "..");
+const packageJson = JSON.parse(fs.readFileSync(path.join(packageRoot, "package.json"), "utf8"));
+
+const skills = [
+  "image-edit",
+  "product-image-generation",
+  "image-to-video",
+  "product-to-ad",
+  "ad-video-generation",
+  "product-demo-video",
+  "ad-creative-images",
+  "ugc-video-ads",
+];
+
+function usage() {
+  console.log(`evolink-agent-skills v${packageJson.version}
+
+Install EvoLink creative generation skills for agents.
+
+Usage:
+  npx evolink-agent-skills -y --path ./my-agent-project --all
+  npx evolink-agent-skills -y --skill image-edit --path ./my-agent-project
+  npx evolink-agent-skills --llms
+
+Options:
+  -y, --yes          Accept install prompts.
+  --all             Install all bundled skills. Default when no --skill is set.
+  --skill <slug>    Install one skill. Can be repeated or comma-separated.
+  --path <dir>      Install into this project directory. Defaults to cwd.
+  --llms            Print llms-install.md.
+  --skill-doc <slug> Print a bundled SKILL.md.
+  --no-open         Accepted for CI compatibility.
+  --version         Print package version.
+  --help            Show this help.
+
+Skills:
+  ${skills.join("\n  ")}
+`);
+}
+
+function parseArgs(argv) {
+  const args = {
+    target: process.cwd(),
+    selected: [],
+    printLlms: false,
+    printSkill: "",
+  };
+
+  for (let i = 0; i < argv.length; i += 1) {
+    const arg = argv[i];
+    if (arg === "-y" || arg === "--yes" || arg === "--all" || arg === "--no-open") {
+      continue;
+    }
+    if (arg === "--skill") {
+      const value = argv[i + 1] || "";
+      args.selected.push(...value.split(",").map((item) => item.trim()).filter(Boolean));
+      i += 1;
+      continue;
+    }
+    if (arg === "--path") {
+      args.target = path.resolve(argv[i + 1] || "");
+      i += 1;
+      continue;
+    }
+    if (arg === "--llms") {
+      args.printLlms = true;
+      continue;
+    }
+    if (arg === "--skill-doc") {
+      args.printSkill = argv[i + 1] || "";
+      i += 1;
+      continue;
+    }
+    if (arg === "--version") {
+      console.log(packageJson.version);
+      process.exit(0);
+    }
+    if (arg === "--help" || arg === "-h") {
+      usage();
+      process.exit(0);
+    }
+
+    console.error(`Unknown argument: ${arg}`);
+    usage();
+    process.exit(2);
+  }
+
+  if (args.selected.length === 0) args.selected = [...skills];
+  return args;
+}
+
+function assertSkill(skill) {
+  if (!skills.includes(skill)) {
+    console.error(`Unknown skill: ${skill}`);
+    console.error(`Known skills: ${skills.join(", ")}`);
+    process.exit(2);
+  }
+}
+
+function printFile(file) {
+  process.stdout.write(fs.readFileSync(path.join(packageRoot, file), "utf8"));
+}
+
+const args = parseArgs(process.argv.slice(2));
+
+if (args.printLlms) {
+  printFile("llms-install.md");
+  process.exit(0);
+}
+
+if (args.printSkill) {
+  assertSkill(args.printSkill);
+  printFile(path.join(args.printSkill, "SKILL.md"));
+  process.exit(0);
+}
+
+const installed = [];
+for (const skill of args.selected) {
+  assertSkill(skill);
+  const source = path.join(packageRoot, skill, "SKILL.md");
+  const destination = path.join(args.target, ".agents", "skills", skill);
+  fs.mkdirSync(destination, { recursive: true });
+  fs.copyFileSync(source, path.join(destination, "SKILL.md"));
+  installed.push({ skill, destination });
+}
+
+for (const entry of installed) {
+  console.log(`INSTALLED_SKILL=${entry.skill}`);
+  console.log(`INSTALL_PATH=${entry.destination}`);
+}
+
+console.log("EVOLINK_KEY_URL=https://evolink.ai?utm_source=npm&utm_medium=skill&utm_campaign=evolink-agent-skills");
+console.log("ENV_VAR_EXPORT=export EVOLINK_API_KEY=<your_evolink_api_key>");
+console.log("AGENT_NEXT_ACTION=Use the installed SKILL.md files for matching EvoLink creative generation requests.");

package/docs/api-reference.md

@@ -0,0 +1,20 @@
+# API Reference
+
+This package routes agent workflows to EvoLink model APIs.
+
+## Image Generation
+
+- Endpoint: `POST /v1/images/generations`
+- Default model in smoke tests: `gpt-image-2`
+- Required auth: `Authorization: Bearer $EVOLINK_API_KEY`
+
+## Video Generation
+
+- Endpoint: `POST /v1/videos/generations`
+- Default model in smoke tests: `seedance-2.0-text-to-video`
+- Required auth: `Authorization: Bearer $EVOLINK_API_KEY`
+
+## Task Polling
+
+- Endpoint: `GET /v1/tasks/{task_id}`
+- Poll until the task reaches a terminal completed or failed status.

package/docs/callbacks.md

@@ -0,0 +1,5 @@
+# Callbacks
+
+The bundled smoke tests use polling through `GET /v1/tasks/{task_id}`.
+
+For production systems, use EvoLink callback support when available so the application can receive task completion events without long polling. Validate callback signatures and store the final task payload before exposing result URLs to users.

package/docs/errors.md

@@ -0,0 +1,11 @@
+# Errors
+
+Common failure classes:
+
+- Missing `EVOLINK_API_KEY`.
+- Invalid API key or insufficient credits.
+- Model payload rejected by the upstream endpoint.
+- Task polling timeout.
+- Completed task without a result URL.
+
+Every real API smoke run writes a Markdown report under `test-results/` with a redacted key and the request/response evidence.

package/docs/publishing-checklist.md

@@ -0,0 +1,48 @@
+# skills.sh Publishing Checklist
+
+Use this checklist for every first-batch skill before publishing the next one.
+
+## Pre-Publish
+
+- Run static validation:
+
+```bash
+node scripts/validate-skills.mjs
+```
+
+- Run local skills CLI smoke install:
+
+```bash
+node scripts/smoke-install-skills.mjs
+```
+
+- Directory slug matches `SKILL.md` frontmatter `name`.
+- Skill slug uses demand or scene wording, not model-only wording.
+- `displayName` names the execution model: Seedance 2, GPT Image 2, or both.
+- Description includes user intent words and execution model names.
+- Install command uses `Evolink-AI/evolink-agent-skills` and the exact skill slug.
+- All EvoLink links use `utm_source=skillssh&utm_medium=skill&utm_campaign=<skill-name>`.
+- The skill includes a route table with GPT Image 2 and/or Seedance 2 model paths.
+- Image skills include a video handoff.
+- Video skills include variant or iteration suggestions.
+
+## Publish Order
+
+1. `image-edit`
+2. `product-image-generation`
+3. `image-to-video`
+4. `product-to-ad`
+5. `ad-video-generation`
+6. `product-demo-video`
+7. `ad-creative-images`
+8. `ugc-video-ads`
+
+## Post-Publish
+
+- Run the install command from a clean machine or container.
+- Confirm the skill appears on skills.sh with the correct title and description.
+- Confirm `skills.sh.json` grouping renders after cache refresh.
+- Click each EvoLink link and verify analytics campaign attribution.
+- Run one real EvoLink generation through the documented path.
+- Confirm backend analytics can connect campaign, first generation, and token consumption.
+- Record the install count baseline before publishing the next skill.

package/docs/quickstart.md

@@ -0,0 +1,27 @@
+# Quickstart
+
+Install all bundled skills:
+
+```bash
+npx evolink-agent-skills -y --path ./my-agent-project --all
+```
+
+Install one skill:
+
+```bash
+npx evolink-agent-skills -y --skill product-to-ad --path ./my-agent-project
+```
+
+Set credentials before live API usage:
+
+```bash
+export EVOLINK_API_KEY=<your_evolink_api_key>
+```
+
+Run local checks:
+
+```bash
+npm run validate
+npm run smoke:install
+npm run smoke:npm-local
+```

package/docs/real-api-test-plan.md

@@ -0,0 +1,94 @@
+# Real API Test Plan
+
+This plan keeps live EvoLink tests as cheap as possible while still proving that the repository can drive real model calls.
+
+## Non-Billable Tests
+
+Run these before any real API call:
+
+```bash
+node scripts/validate-skills.mjs
+node scripts/smoke-install-skills.mjs
+```
+
+They validate repository structure, skills.sh compatibility, local install, and lockfile behavior. They do not call EvoLink APIs.
+
+## Billable Test 1: GPT Image 2 Minimal Smoke Test
+
+Default command:
+
+```bash
+node scripts/real-api-smoke-test.mjs
+```
+
+Cheapest profile:
+
+```json
+{
+  "model": "gpt-image-2",
+  "size": "1:1",
+  "resolution": "1K",
+  "quality": "low",
+  "n": 1
+}
+```
+
+Purpose:
+
+- Verify `EVOLINK_API_KEY` works.
+- Verify `/v1/images/generations` accepts the request.
+- Verify polling through `/v1/tasks/{task_id}`.
+- Verify at least one final result URL is returned.
+
+## Billable Test 2: Seedance 2 Minimal Smoke Test
+
+Only run this after the image test passes:
+
+```bash
+node scripts/real-api-smoke-test.mjs --video
+```
+
+Cheapest profile:
+
+```json
+{
+  "model": "seedance-2.0-text-to-video",
+  "duration": 4,
+  "quality": "480p",
+  "aspect_ratio": "16:9",
+  "generate_audio": false
+}
+```
+
+Purpose:
+
+- Verify `/v1/videos/generations` accepts the request.
+- Verify the lowest video duration and resolution path works.
+- Verify polling returns a final video URL.
+
+## Reports
+
+Every real API run writes a local Markdown report under `test-results/`.
+
+The report includes:
+
+- Date
+- Status
+- Redacted API key
+- Request payload
+- Cheapest profile
+- Task creation response
+- Final task response
+- Result URL or error
+
+`test-results/` is ignored by git so task IDs, URLs, and account-specific responses are not pushed accidentally.
+
+## Alternate Env Source
+
+By default, the script reads `.env`. To force the script to use only `process.env`, run:
+
+```bash
+EVOLINK_API_KEY=your_key node scripts/real-api-smoke-test.mjs --dotenv none
+```
+
+The argument is named `--dotenv` intentionally. Do not use `--env-file`; Node.js has its own `--env-file` option and may intercept it before the script sees it.

package/docs/response-schema.md

@@ -0,0 +1,14 @@
+# Response Schema
+
+Generation requests return a task identifier such as `id` or `task_id`.
+
+Completed tasks should expose result assets through one of these fields:
+
+- `results[].url`
+- `results[].image_url`
+- `results[].video_url`
+- `url`
+- `image_url`
+- `video_url`
+
+The smoke script accepts any of these fields and fails if no result URL is present after completion.

package/docs/task-lifecycle.md

@@ -0,0 +1,8 @@
+# Task Lifecycle
+
+1. Select the right skill from the user intent.
+2. Build the model payload with the cheapest useful profile for smoke tests.
+3. Submit the generation request.
+4. Poll `GET /v1/tasks/{task_id}` until completion.
+5. Read back the result URL and record the report.
+6. Continue the skill's next-token loop with variants or a handoff.