Creating Skills

This guide walks you through writing a custom skill from scratch. By the end, you'll have a SKILL.md file that any AI agent can use to execute your creative workflow through XainFlow.

SKILL.md Format

Every skill is a markdown file with YAML frontmatter followed by instructions for the AI agent.

Required Fields

---
name: my-skill-name
description: What this skill does in one sentence.
category: photography
argument-hint: [product image URL or file path]
---

Field	Rules	Example
name	Lowercase, hyphens only, max 64 characters	product-shots
description	Single sentence describing the skill's purpose	Professional product photography variations.
category	One of: photography, social, branding, tools, video, marketing, workflow, custom	photography
argument-hint	Describes the expected user input, in brackets	[product image URL or file path]

Optional Fields

---
name: my-skill-name
description: What this skill does in one sentence.
category: photography
argument-hint: [product image URL or file path]
display-name: My Skill Name
tags: [product, ecommerce, photography]
output-folder: product-shots
create-folder: true
default-model: seadream-4
default-ratio: "1:1"
credit-budget: 15
asset-type: product
reference-assets: true
use-styles: true
use-variables: true
requires-context: [brand_guidelines, color_palette, brand_logo]
---

Field	Purpose	Default
display-name	Human-readable name shown in the UI	Derived from name
tags	Keywords for search and discovery	None
output-folder	Where generated assets are saved	Project root
create-folder	Whether to create the output folder if it doesn't exist	false
default-model	Recommended AI model for generation	None
default-ratio	Default aspect ratio (W:H format)	None
credit-budget	Estimated credits per execution	None
asset-type	Type of asset this skill produces (product, character, background, logo)	None
reference-assets	Whether the skill uses reference images	false
use-styles	Whether to pull workspace styles	false
use-variables	Whether to pull workspace variables	false
requires-context	List of workspace context fields to inject at runtime	None

Writing Instructions

The markdown body tells the AI agent what to do. Structure it clearly so the agent can follow the steps without ambiguity.

Recommended Sections

# Skill Title

Brief description of what this skill creates and who it's for.

## Inputs

What to ask the user for:
- Product image (file, URL, or existing asset)
- Style preferences (optional)
- Target platform (optional)

## Workflow Structure

How to build the generation workflow:
1. **Clean Product Shot** — Remove background, place on white, 1:1 ratio
2. **Lifestyle Shot** — Generate environmental scene with product, 4:3 ratio
3. **Detail Shot** — Close-up macro view highlighting textures, 1:1 ratio

## Organization

Where to save results:
- Create folder: `product-shots/{product-name}/`
- Name convention: `{shot-type}-{timestamp}`

## Before Executing

Show the user:
- Total credit cost breakdown per shot
- Models and ratios selected
- Ask for explicit confirmation before running

Tips for Effective Instructions

• Be specific about outputs. Instead of "generate some product photos," specify the exact shot types, aspect ratios, and models.
• Use numbered steps. The AI follows sequential instructions more reliably than paragraph text.
• Reference tools by name. Say "use generate_image" instead of "create an image." The agent maps these to MCP tool calls.
• Include fallbacks. If a user doesn't provide a preference, specify sensible defaults.

Available MCP Tools

Skills can reference these XainFlow MCP tools. The AI agent already knows their parameters — your skill just needs to say when and why to use each one.

Tool	What It Does
generate_image	Generate images with AI models (Seadream 4.0)
generate_video	Generate videos with AI models (Veo, Sora, Kling, Seedance)
remove_background	Remove image backgrounds using AI
upscale	Upscale images to higher resolution
vectorize	Convert raster images to SVG vector format
list_assets	Browse existing assets in the workspace
list_styles	Retrieve workspace style definitions
list_variables	Retrieve workspace prompt variables
manage_folders	Create and organize asset folders
manage_assets	Move, rename, or organize generated assets

info

You don't need to specify tool parameters in your skill. The AI agent reads tool descriptions from the MCP server and fills in the correct parameters. Your skill just needs to describe the desired outcome.

Context Requirements

If your skill should adapt to each workspace's brand, use requires-context to request brand data injection at runtime.

Available Context Fields

Field	What Gets Injected
brand_guidelines	Overall brand rules, mission, and positioning
color_palette	Brand colors defined in workspace styles
tone_of_voice	Writing style and personality guidelines
brand_logo	Workspace logo asset for overlays and compositions
target_audience	Description of who the content targets
brand_fonts	Typography preferences from workspace styles

How It Works

1. Add the fields you need to requires-context in your frontmatter.
2. When the skill runs, XainFlow pulls those values from the user's workspace styles and variables.
3. The AI agent receives the skill instructions with brand data injected, producing output tailored to that workspace.

Example

A brand-assets skill with requires-context: [brand_guidelines, color_palette, brand_logo] will:

• Read the workspace's brand guidelines to understand tone and positioning.
• Use the color palette for consistent brand colors in generated images.
• Include the brand logo in compositions where appropriate.

Two different workspaces running the same skill get completely different results based on their brand data.

Best Practices

Always Confirm Before Executing

Every skill should include a confirmation step before spending credits:

## Before Executing

Present the user with:
- Number of generations and estimated credit cost per item
- Total credit cost
- Models and settings selected
- Ask: "Ready to execute? This will use approximately X credits."

warning

Skills that skip confirmation and immediately spend credits create a poor user experience. Always show costs first.

Set Realistic Credit Budgets

The credit-budget field sets user expectations. Calculate it based on the actual operations your skill performs:

• Image generation: ~5 credits per image
• Video generation: ~15-60 credits per second (varies by model)
• Background removal: ~2 credits
• Upscaling: ~3 credits

Never Hardcode IDs

Don't include workspace IDs, project IDs, or asset IDs in your skill. These are workspace-specific and will break for other users. Instead, instruct the agent to look up resources dynamically:

<!-- Bad -->
Use project ID `abc-123-def` for output.

<!-- Good -->
Ask the user which project to use, or list available projects and let them choose.

Handle Errors Gracefully

Tell the agent what to do when things go wrong:

If image generation fails, inform the user of the error and ask if they want to:
1. Retry with the same settings
2. Try a different model
3. Skip this shot and continue with the rest

Publishing Your Skill

Once your skill is ready, you can share it with the community.

From the App

1. Go to your Skills list.
2. Open the skill you want to share.
3. Click Publish to Hub.
4. Fill in the details and confirm.

Your skill appears in the Skills Hub for others to discover and clone.

Via GitHub

You can also contribute skills to the open source repository:

1. Fork github.com/xainflow/skills.
2. Create your skill folder in skills/community/.
3. Add your SKILL.md file.
4. Submit a pull request.

See Skills for Developers for the full contribution workflow.

Full Specification

For the complete SKILL.md format specification, including validation rules and edge cases, see the SKILL.md Spec on GitHub.

Related Pages

• Skills Overview — how skills work, types, and basic usage
• Skills Hub — browse, clone, and publish skills
• Skills for Developers — open source repo, API access, contributing