
maxgent
Skills for operations teams: macOS app installation, video concatenation, video trimming
- version
- 0.1.0
Install
/plugin install maxgent@maxgentRun it inside Claude Code after adding the marketplace with /plugin marketplace add maxgent-ai/maxgent-plugin.
Contents
Discovered from sourceSkills 10
Audio Transcriber
Speech recognition using WhisperX with multi-language support and word-level timestamp alignment.
Prerequisites
Requires Python 3.12 (uv manages this automatically).
Usage
When the user wants to transcribe audio/video: $ARGUMENTS
Instructions
Step 1: Get input file
If the user has not provided an input file path, ask them to provide one.
Supported formats:
- Audio: MP3, WAV, FLAC, M4A, OGG, etc.
- Video: MP4, MKV, MOV, AVI, etc. (audio is extracted automatically)
Verify the file exists:
ls -la "$INPUT_FILE"
Step 2: Ask user for configuration
Warning: You MUST use AskUserQuestion to collect user preferences. Do not skip this step.
Use AskUserQuestion to collect the following:
-
Model size: Choose the recognition model
- Options:
- "base - Balanced speed and accuracy (Recommended)"
- "tiny - Fastest, lower accuracy"
- "small - Faster, moderate accuracy"
- "medium - Slower, higher accuracy"
- "large-v2 - Slowest, highest accuracy"
- Options:
-
Language: What language is the audio?
- Options:
- "Auto-detect (Recommended)"
- "Chinese (zh)"
- "English (en)"
- "Japanese (ja)"
- "Other"
- Options:
-
Word-level alignment: Do you need word-level timestamps?
- Options:
- "Yes - Precise timing for each word (Recommended)"
- "No - Sentence-level timing only (faster)"
- Options:
-
Output format: What format to output?
- Options:
- "TXT - Plain text with timestamps (Recommended)"
- "SRT - Subtitle format"
- "VTT - Web subtitle format"
- "JSON - Structured data (with word-level info)"
- Options:
-
Output path: Where to save?
- Default: same directory as input file, named
<original_name>.txt(or matching format)
- Default: same directory as input file, named
Step 3: Run transcription script
Use the transcribe.py script in the skill directory:
uv run /path/to/skills/audio-transcribe/transcribe.py "INPUT_FILE" [OPTIONS]
Parameters:
--model,-m: Model size (tiny/base/small/medium/large-v2)--language,-l: Language code (en/zh/ja/...), auto-detect if not specified--no-align: Skip word-level alignment--no-vad: Disable VAD filtering (use if transcription has time jumps or missing segments)--output,-o: Output file path--format,-f: Output format (srt/vtt/txt/json)
Examples:
# Basic transcription (auto-detect language)
uv run skills/audio-transcribe/transcribe.py "video.mp4" -o "video.txt"
# Chinese transcription, output SRT subtitles
uv run skills/audio-transcribe/transcribe.py "audio.mp3" -l zh -f srt -o "subtitles.srt"
# Fast transcription, skip word alignment
uv run skills/audio-transcribe/transcribe.py "audio.wav" --no-align -o "transcript.txt"
# Use a larger model, output JSON (with word-level timestamps)
uv run skills/audio-transcribe/transcribe.py "speech.mp3" -m medium -f json -o "result.json"
# Disable VAD filtering (fix time jumps / missing segments)
uv run skills/audio-transcribe/transcribe.py "audio.mp3" --no-vad -o "transcript.txt"
Step 4: Present results
After transcription completes:
- Show the full output file path
- Display a preview of the transcription content
- Report total duration and segment count
Output format reference
TXT format
[00:00:00.000 - 00:00:03.500] This is the first sentence
[00:00:03.500 - 00:00:07.200] This is the second sentence
SRT format
1
00:00:00,000 --> 00:00:03,500
This is the first sentence
2
00:00:03,500 --> 00:00:07,200
This is the second sentence
JSON format (with word-level)
[
{
"start": 0.0,
"end": 3.5,
"text": "This is the first sentence",
"words": [
{"word": "This", "start": 0.0, "end": 0.5, "score": 0.95},
...
]
}
]
Troubleshooting
Slow on first run:
- WhisperX needs to download model files; first run will be slower
- Subsequent runs use the cached model
Out of memory:
- Use a smaller model (tiny or base)
- Ensure the system has enough memory
Low recognition accuracy:
- Try a larger model (medium or large-v2)
- Explicitly specify the language instead of auto-detect
Browser Automation
Browser automation that maintains page state across command executions. Write small, focused commands to accomplish tasks incrementally.
Choosing Your Approach
- Local/source-available sites: Read the source code first to write selectors directly
- Unknown page layouts: Use
snapshotto discover elements, thenselect-refto interact - Visual debugging: Take
screenshotto see current page state
Prerequisites
# Check browser server running (Max must be open)
curl -s http://localhost:9222/ | head -1 || echo "SERVER_NOT_RUNNING"
Running Commands
All commands use client.py from the skill directory:
uv run skills/browser/client.py <command> [arguments]
⚠️ IMPORTANT: Always use
uv run client.py, NOTuv run python client.py. Theuv runcommand automatically handles Python and dependencies frompyproject.toml. Addingpythonbreaks dependency resolution.
Workflow Loop
Follow this pattern for complex tasks:
- Run a command to perform one action
- Observe the output
- Evaluate - did it work? What's the current state?
- Decide - is the task complete or do we need another command?
- Repeat until task is done
No TypeScript in Browser Context
Code passed to page.evaluate() runs in the browser, which doesn't understand TypeScript:
// ✅ Correct: plain JavaScript
const text = await page.evaluate(() => {
return document.body.innerText;
});
// ❌ Wrong: TypeScript syntax will fail at runtime
const text = await page.evaluate(() => {
const el: HTMLElement = document.body; // Type annotation breaks in browser!
return el.innerText;
});
Waiting
uv run skills/browser/client.py wait-load main # After navigation
uv run skills/browser/client.py wait-selector main ".results" # For specific elements
uv run skills/browser/client.py wait-url main "**/success" # For specific URL
Scraping Data
For large datasets, intercept and replay API requests rather than scrolling DOM. See refs/scraping.md for the complete guide covering request capture, schema discovery, and paginated API replay.
Inspecting Page State
Screenshots
uv run skills/browser/client.py screenshot main screenshot.png
uv run skills/browser/client.py screenshot main full.png --full-page # Capture entire scrollable page
ARIA Snapshot (Element Discovery)
Use snapshot to discover page elements. Returns YAML-formatted accessibility tree:
- banner:
- link "Hacker News" [ref=e1]
- navigation:
- link "new" [ref=e2]
- main:
- heading "Products" [ref=e3] [level=1]
- list:
- listitem:
- link "Article Title" [ref=e4]
- button "Add to Cart" [ref=e5]
- listitem:
- link "Another Article" [ref=e6]
- button "Add to Cart" [ref=e7] [nth=1]
- contentinfo:
- textbox [ref=e8]
- /placeholder: "Search"
Interpreting refs:
[ref=eN]- Element reference for interaction[nth=N]- Nth duplicate element with same role+name (0-indexed, first one omitted)[checked],[disabled],[expanded]- Element states[level=N]- Heading level/url:,/placeholder:- Element properties
Interacting with refs:
# Get snapshot to find refs
uv run skills/browser/client.py snapshot main
# Only show interactive elements (buttons, links, inputs, etc.)
uv run skills/browser/client.py snapshot main -i
# Use ref to interact
uv run skills/browser/client.py select-ref main e2 click
uv run skills/browser/client.py select-ref main e7 click # Click second "Add to Cart"
uv run skills/browser/client.py select-ref main e8 fill "search term"
Error Recovery
Page state persists after failures. Debug with:
# Take screenshot to see current state
uv run skills/browser/client.py screenshot main debug.png
# Get page info
uv run skills/browser/client.py info main
# Get text content
uv run skills/browser/client.py text main "body"
Command Reference
Page Management
uv run skills/browser/client.py list # List all pages
uv run skills/browser/client.py create main # Create a new page
uv run skills/browser/client.py create main "https://..." # Create and navigate
uv run skills/browser/client.py goto main "https://..." # Navigate existing page
uv run skills/browser/client.py close main # Close a page
uv run skills/browser/client.py info main # Get page URL and title
uv run skills/browser/client.py release main # Release page (call when done!)
Element Interaction
uv run skills/browser/client.py click main "button.submit" # Click element
uv run skills/browser/client.py fill main "input#email" "test@example.com" # Fill input
uv run skills/browser/client.py hover main ".dropdown" # Hover over element
uv run skills/browser/client.py keyboard main "Enter" # Press key
uv run skills/browser/client.py text main "h1" # Get element text
JavaScript Execution
uv run skills/browser/client.py evaluate main "document.title"
uv run skills/browser/client.py evaluate main "document.querySelectorAll('.item').length"
Python Script (Advanced)
For complex tasks requiring loops or page.on() event handlers, use heredoc with BrowserClient:
cd skills/browser && uv run python <<'EOF'
from client import BrowserClient
client = BrowserClient()
page = client.get_playwright_page("main")
# Full Playwright API available
page.goto("https://example.com")
page.click("button")
# Event handlers for request interception
page.on("response", lambda r: print(r.url))
EOF
The page object is a standard Playwright Page.
Important: Release Page After All Operations
⚠️ CRITICAL: Call
releasecommand when you finish ALL operations on a page!
When browser skill operates on a page, Max UI shows an "Agent Operating" indicator and locks user interaction. You must call release when your entire operation sequence is complete:
# Example workflow
uv run skills/browser/client.py create main "https://example.com"
uv run skills/browser/client.py wait-load main
uv run skills/browser/client.py snapshot main
uv run skills/browser/client.py click main "button.submit"
uv run skills/browser/client.py wait-load main
# When ALL operations are done, release the page
uv run skills/browser/client.py release main
Why this matters:
- Without
release, the indicator stays for 30 seconds (timeout fallback) - User interaction is blocked during operations
- Calling
releaseimmediately unlocks user control
When to call release:
- After completing a task (e.g., filled a form, extracted data)
- Before reporting results to the user
- NOT after each individual command - only when the entire operation sequence is done
For Python scripts:
from client import BrowserClient
client = BrowserClient()
try:
page = client.get_playwright_page("main")
# ... perform ALL operations ...
finally:
client.release_page("main") # REQUIRED: Clear indicator
client.disconnect()
Image Generator
Generate or edit images via Maxgent FAL API proxy.
Prerequisites
MAX_API_KEYenvironment variable (auto-injected by Max)- Bun 1.0+ (built into Max)
Default Routing
- Text-to-image (default):
fal-ai/nano-banana-pro - Image editing (default):
fal-ai/nano-banana-pro/edit
Usage
bun skills/image-gen/image-gen.js \
--model MODEL --prompt "PROMPT" --aspect-ratio RATIO \
--num-images N --output-dir DIR \
[--input-image PATH] [--output-format FORMAT] \
[--seed N] [--guidance-scale X] [--steps N]
Parameters:
--model:auto(recommended),gpt-image-1.5,nano-banana-pro,flux-dev--prompt: image description or editing instruction--aspect-ratio:1:1,4:3,3:4,16:9,9:16--num-images: number of images to generate (default1)--output-dir: output directory — default to$MAX_PROJECT_PATH(the user's project root)--input-image: optional, for image editing mode--output-format:png,jpg,webp(defaultpng)--seed: random seed for reproducibility--guidance-scale: guidance scale for supported models--steps: number of inference steps for supported models
Examples
# Default routing, text-to-image
bun skills/image-gen/image-gen.js --model auto --prompt "a cat under the starry sky" --aspect-ratio "1:1" --output-dir "$MAX_PROJECT_PATH"
# Specify model
bun skills/image-gen/image-gen.js --model gpt-image-1.5 --prompt "modern building facade, cinematic" --aspect-ratio "16:9" --num-images 2 --output-dir "$MAX_PROJECT_PATH"
# Image editing
bun skills/image-gen/image-gen.js --model auto --prompt "change background to a beach at sunset" --aspect-ratio "1:1" --output-dir "$MAX_PROJECT_PATH" --input-image "/path/to/input.jpg"
Instructions
- Check that
MAX_API_KEYexists. - Use AskUserQuestion to collect: edit or generate, prompt, aspect ratio, count. Default output path to
$MAX_PROJECT_PATH. - Run the script and wait for result.
- On success, report the output path.
- On failure:
- HTTP 402 (insufficient credits): Stop immediately. Do NOT retry. Tell the user their API credits are exhausted.
- Other errors: retry once with a different model or simplified prompt. If it fails again, stop and report the error.
Maxmotion Video Editor Skill
The user's message contains an <editor /> tag with project path and selected element.
Context Format
<editor project="<path>" type="<type>" id="<id>" name="<name>" frame="<from>-<end>" />
Core Rule: Code First, JSON for Simple Edits
| Task | Approach |
|---|---|
| Create new content (new video segment, composition, animation) | Write Remotion code in <project>/src/*.tsx |
| Modify existing clip properties (color, text, animation) | Edit <project>/maxmotion.json |
| Modify existing sequence content/logic | Edit <project>/src/*.tsx source code |
Never hand-write large maxmotion.json from scratch. JSON clips are for simple overlay elements (solid rects, text labels). Creative content should be Remotion components in code.
Routing (for existing elements)
| Selected Type | How to Operate |
|---|---|
solid, text, image, video, audio, component | Edit <project>/maxmotion.json |
sequence | Edit <project>/src/*.tsx source code |
Operations
| Operation | Clip (JSON) | Sequence (Code) |
|---|---|---|
| Add | Create clip, append to tracks[].clips[] | Add <Sequence> in .tsx |
| Update | Find by id, modify fields | Find <Sequence name="">, modify code |
| Delete | Remove from tracks[].clips[] | Remove <Sequence> block |
AI vs UI Boundary
AI handles — content, color, animation, code logic, batch operations, add/delete elements, create new compositions
User handles in Editor UI — timing (drag timeline), position (drag canvas), resize, opacity
If the user asks to move/resize/adjust timing, reply suggesting they do it in the Editor UI. Match the user's language (Chinese/English).
JSON Schema (maxmotion.json)
{
"schemaVersion": 4,
"timelines": {
"<compositionId>": {
"tracks": [{
"id": "track_xxx",
"name": "Text",
"visible": true, "locked": false, "muted": false,
"clips": [{
"id": "clip_xxx",
"timing": { "from": 0, "duration": 150 },
"content": { "type": "solid", "color": "#3b82f6" },
"style": { "x": 100, "y": 100, "width": 200, "height": 200 },
"animation": { "fadeIn": 15, "fadeOut": 15 }
}]
}],
"sequenceOverrides": []
}
},
"assets": {
"<assetId>": {
"id": "<assetId>",
"type": "image",
"filename": "original-name.png",
"url": "stored-filename-in-public.png"
}
}
}
Clip Fields
| field | type | required | description |
|---|---|---|---|
id | string | yes | Unique ID: clip_<base36-timestamp>_<random6> |
timing | object | yes | { from: number, duration: number } (frames, NOT flat) |
content | object | yes | See Content Types below |
style | object | yes | See Clip Style below |
animation | object | no | See Clip Animation below |
Important:
fromanddurationmust be nested insidetiming, not flat on the clip object. Flatfrom/durationwill crash the renderer.
Clip Content Types
| type | fields |
|---|---|
solid | color |
text | text, fontSize, color, fontFamily?, align? |
image | assetId |
video | assetId, playbackRate?, volume? |
audio | assetId, volume? |
component | componentId, props |
Clip Style
| field | type | required | description |
|---|---|---|---|
x | number | yes | X position (px) |
y | number | yes | Y position (px) |
width | number | yes | Width (px) |
height | number | yes | Height (px) |
opacity | number | no | 0-1, default 1 |
rotation | number | no | Degrees |
borderRadius | number | no | Pixels |
transform3d | object | no | { perspective?, rotateX?, rotateY?, rotateZ?, translateZ? } |
Clip Animation
| field | type | description |
|---|---|---|
fadeIn | number | Fade-in frames |
fadeOut | number | Fade-out frames |
springConfig | object | { mass?, damping?, stiffness? } |
Sequence Overrides
timelines.<compositionId>.sequenceOverrides can override properties of code-defined <Sequence> elements:
| field | type | description |
|---|---|---|
id | string | Sequence ID (required) |
name | string | Sequence name (for matching) |
from | number | Override start frame |
duration | number | Override duration frames |
visible | boolean | Show/hide (default true) |
style | object | { x?, y?, width?, height?, opacity? } |
Asset Schema
Clips with assetId (image/video/audio) reference entries in assets. Each asset key is the asset ID.
| field | type | description |
|---|---|---|
id | string | Same as the key in assets object |
type | string | image | video | audio |
filename | string | Original display name (e.g. photo.png) |
url | string | Filename in public/ directory or full HTTP URL |
Important: Use url (not src) and filename (not name). Wrong field names will crash the renderer.
Timing
All values are frames. Get fps from <project>/src/Root.tsx:
<Composition id="Main" fps={30} width={1920} height={1080} ... />
Convert: seconds * fps = frames
Remotion Code Pattern
import { AbsoluteFill, Sequence, useCurrentFrame, interpolate } from 'remotion';
export const MyComp = () => (
<AbsoluteFill>
<Sequence from={0} durationInFrames={90} name="intro">
<h1 style={{ fontSize: 60 }}>Title</h1>
</Sequence>
</AbsoluteFill>
);
When creating new content, write proper Remotion components using Sequence, AbsoluteFill, useCurrentFrame, interpolate, spring, etc. Register in Root.tsx via <Composition>.
Remotion Quick Reference
Project Structure
video/
├── src/
│ ├── index.ts # registerRoot(RemotionRoot)
│ ├── Root.tsx # <Composition> registration
│ └── MyComp.tsx # Component implementation
├── public/ # Static assets (images, fonts, videos)
├── remotion.config.ts # Remotion config
└── maxmotion.json # Editor timeline data
Core Components
| Component | Purpose | Example |
|---|---|---|
<Composition> | Register a video (in Root.tsx) | <Composition id="Main" component={MyComp} fps={30} width={1920} height={1080} durationInFrames={300} /> |
<AbsoluteFill> | Full-screen container (position: absolute, inset: 0) | <AbsoluteFill style={{ backgroundColor: '#000' }}> |
<Sequence> | Time-scoped section | <Sequence from={30} durationInFrames={60} name="intro"> |
<Video> | Video playback | <Video src={staticFile('clip.mp4')} /> |
<Audio> | Audio playback | <Audio src={staticFile('music.mp3')} volume={0.5} /> |
<Img> | Image (preloaded) | <Img src={staticFile('logo.png')} /> |
<Series> | Sequential sequences (auto-calculates from) | <Series><Series.Sequence durationInFrames={60}>...</Series.Sequence></Series> |
Core Hooks
| Hook | Returns | Usage |
|---|---|---|
useCurrentFrame() | number | Current frame (0-based, resets inside each <Sequence>) |
useVideoConfig() | { fps, width, height, durationInFrames } | Composition config |
Animation Utilities
import { interpolate, spring, Easing } from 'remotion';
// Linear interpolation
const opacity = interpolate(frame, [0, 30], [0, 1], { extrapolateRight: 'clamp' });
// Spring animation
const scale = spring({ frame, fps, config: { damping: 12, stiffness: 200 } });
// With easing
const x = interpolate(frame, [0, 60], [0, 500], { easing: Easing.bezier(0.25, 0.1, 0.25, 1) });
Static Assets
import { staticFile } from 'remotion';
// References files in public/ directory
<Img src={staticFile('logo.png')} />
<Video src={staticFile('intro.mp4')} />
Validation
After editing maxmotion.json, always run validation to catch schema errors:
cd <project> && npx maxmotion validate
If validation fails, fix the errors before telling the user the edit is done.
Notes
- After editing JSON: user needs to refresh Editor. After editing .tsx: HMR auto-updates.
- New clip IDs:
clip_<base36-timestamp>_<random6>. Keep 2-space JSON indent. - The first
<Composition>in Root.tsx is selected by default in the Editor. After creating a new composition, remove empty/unused ones (e.g. components returningnull) to avoid a black screen.
Media Processing
Process audio and video files using ffmpeg. Claude already knows ffmpeg well — this skill only defines the interaction flow.
Usage
When the user wants to process audio/video files: $ARGUMENTS
Instructions
Step 0: Choose interaction mode
On first interaction, use AskUserQuestion:
- Question: "Are you familiar with video processing?"
- Options:
- "Simple mode — just pick the best options for me (Recommended)"
- "Pro mode — I want full control over parameters"
If the user uses technical terms (CRF, codec, bitrate, etc.) in simple mode, automatically switch to pro mode.
Step 1: Analyze input files
Run ffprobe to inspect each input file:
ffprobe -v error -show_entries format=duration,size,bit_rate -show_entries stream=codec_name,codec_type,width,height,r_frame_rate,sample_rate,channels,bit_rate -of json "$INPUT_FILE"
Simple mode: show duration, resolution, file size. Pro mode: show full codec, bitrate, sample rate, and other technical details.
Step 2: Confirm key parameters before executing
You MUST use AskUserQuestion to confirm key parameters before running any ffmpeg command. Only ask questions relevant to the operation.
Simple mode — describe effects, not parameters
Trim example:
- "Where should it start? Where should it end?"
- "Output quality?" → "Same as original (fastest)" / "Slightly compressed (smaller file)" / "More compressed (much smaller)"
- "Keep the audio?" → "Yes" / "No"
Merge example:
- Show file list, confirm concatenation order
- "These files have different resolutions — which size should the output use?"
Extract audio example:
- "Output format?" → "MP3 (universal)" / "WAV (lossless)" / "AAC (high quality, small size)"
Pro mode — expose technical parameters
- Show codec, CRF, preset, bitrate options
- Allow custom parameter input
- For merging: offer concat demuxer vs concat filter choice
Extra checks for merging
When merging multiple files, you must:
- Check whether all files share the same resolution, codec, and audio codec
- If they differ, inform the user and ask how to handle it
- Confirm concatenation order
Step 3: Execute
- Build the ffmpeg command
- In pro mode, show the full command before running
- Execute and report progress
Step 4: Verify output
Run ffprobe on the output file and report:
Simple mode:
Done!
- Duration: 2m 30s
- File size: 45 MB (60% smaller than original)
- Saved to: /path/to/output.mp4
Pro mode:
Done!
- Output: 1920x1080, H.264 CRF 23, AAC 128kbps
- Duration: 2:30 | Size: 45.2 MB (was 112 MB, -60%)
- Path: /path/to/output.mp4
- Command: ffmpeg -ss 00:01:30 -to 00:04:00 -i input.mp4 ...
Key Principles
- Don't be an ffmpeg manual — Claude already knows ffmpeg; don't enumerate parameters
- Only ask what's needed — tailor questions to the specific operation, don't ask a long checklist every time
- Output path — default to current working directory, with an operation suffix (e.g.
_trimmed,_merged) - Error handling — if ffmpeg fails, explain the cause in plain language and suggest a fix
Media Understanding
Analyze multimedia content via Maxgent FAL API proxy, using the default route.
Supported Formats
| Type | Formats | Max Size |
|---|---|---|
| Image | jpg, jpeg, png, gif, webp | 20MB |
| Video | mp4, mpeg, mov, webm, YouTube URL | 100MB |
| Audio | wav, mp3, aiff, aac, ogg, flac, m4a | 100MB |
Prerequisites
MAX_API_KEYenvironment variable (auto-injected by Max)- Bun 1.0+ (built into Max)
Routing
default- Endpoint:
openrouter/router/openai/v1/chat/completions - Model:
DEFAULT_MM_MODEL, defaults togoogle/gemini-2.5-pro(override with--model)
- Endpoint:
Usage
bun skills/media-understand/media-understand.js \
--media PATH_OR_URL --prompt "PROMPT" \
[--language chinese|english] [--model MODEL_ID] \
[--max-tokens N] [--temperature X]
Parameters:
--media: local file path or YouTube URL--prompt: analysis question--language:chinese(default) orenglish--model: override the default model--max-tokens: max output tokens (default4096)--temperature: sampling temperature (default0.2)
Examples
# Image OCR
bun skills/media-understand/media-understand.js --media ./screenshot.png --prompt "extract all text from this image" --language english
# Video summary (YouTube)
bun skills/media-understand/media-understand.js --media "https://youtube.com/watch?v=xxx" --prompt "summarize this video" --language english
# Local audio analysis
bun skills/media-understand/media-understand.js --media ./meeting.m4a --prompt "summarize key points and list action items" --language english
Instructions
- Check
MAX_API_KEY. - Identify media type and validate size limits.
- Analyze using the default route; override the model with
--modelif needed. - Local images/videos/audio are auto-uploaded via FAL upload proxy before analysis.
- On success, return readable text.
- On failure:
- HTTP 402 (insufficient credits): Stop immediately. Do NOT retry. Tell the user their API credits are exhausted.
- Other errors: retry once with a different model. If it fails again, stop and clearly indicate whether it's an upload / proxy / model parameter issue.
Memory - Long-term Context
Read the current session's long-term memory files to access historical context preserved across compacts.
Background
Claude Code's /compact compresses conversations to save context. Repeated compaction causes "memory decay" - important early details gradually get lost.
Max's memory system automatically saves accumulated content to files during each compact, ensuring important information is never lost.
Memory Files
| File | Content | Priority |
|---|---|---|
errors.md | Error fix records | Highest - Avoid repeating mistakes |
context.md | User messages + technical concepts | Medium - Full background |
files.md | Code file references | Low - Only when needed |
Instructions
Use the memory.py script to read files with automatic truncation (large files are trimmed to last ~15000 chars to save context):
# Read errors.md only (default, recommended)
cd /path/to/skills/memory && uv run memory.py errors.md
# Read specific files
cd /path/to/skills/memory && uv run memory.py errors.md context.md
# Read all files
cd /path/to/skills/memory && uv run memory.py all
The script automatically:
- Reads from
~/.claude/projects/$MAX_PROJECT_ID/max/$MAX_SESSION_ID/memory/ - Truncates files > 15000 chars (keeps most recent content)
- Skips non-existent files
When to Read Memory
After compact - When you see "Earlier details saved to..." in the summary:
- Always read
errors.mdfirst - Critical to avoid repeating past mistakes
On demand - Read specific files based on the situation:
| Situation | Command |
|---|---|
| Encountering errors / Tests failing | uv run memory.py errors.md |
| Need to recall previous discussions | uv run memory.py context.md |
| Reusing code patterns / Finding files | uv run memory.py files.md |
Notes
- Memory files are automatically updated during each
/compact - Files are appended with timestamps, newest content at the bottom
- Large files are truncated to ~15000 chars (≈3% of context) to prevent context overflow
Skill Creator
This skill provides guidance for creating effective skills.
About Skills
Skills are modular, self-contained packages that extend Claude's capabilities by providing specialized knowledge, workflows, and tools. Think of them as "onboarding guides" for specific domains or tasks—they transform Claude from a general-purpose agent into a specialized agent equipped with procedural knowledge that no model can fully possess.
What Skills Provide
- Specialized workflows - Multi-step procedures for specific domains
- Tool integrations - Instructions for working with specific file formats or APIs
- Domain expertise - Company-specific knowledge, schemas, business logic
- Bundled resources - Scripts, references, and assets for complex and repetitive tasks
Core Principles
Concise is Key
The context window is a public good. Skills share the context window with everything else Claude needs: system prompt, conversation history, other Skills' metadata, and the actual user request.
Default assumption: Claude is already very smart. Only add context Claude doesn't already have. Challenge each piece of information: "Does Claude really need this explanation?" and "Does this paragraph justify its token cost?"
Prefer concise examples over verbose explanations.
Set Appropriate Degrees of Freedom
Match the level of specificity to the task's fragility and variability:
High freedom (text-based instructions): Use when multiple approaches are valid, decisions depend on context, or heuristics guide the approach.
Medium freedom (pseudocode or scripts with parameters): Use when a preferred pattern exists, some variation is acceptable, or configuration affects behavior.
Low freedom (specific scripts, few parameters): Use when operations are fragile and error-prone, consistency is critical, or a specific sequence must be followed.
Think of Claude as exploring a path: a narrow bridge with cliffs needs specific guardrails (low freedom), while an open field allows many routes (high freedom).
Anatomy of a Skill
Every skill consists of a required SKILL.md file and optional bundled resources:
skill-name/
├── SKILL.md (required)
│ ├── YAML frontmatter metadata (required)
│ │ ├── name: (required)
│ │ ├── description: (required)
│ │ └── compatibility: (optional, rarely needed)
│ └── Markdown instructions (required)
└── Bundled Resources (optional)
├── scripts/ - Executable code (Python/Bash/etc.)
├── references/ - Documentation intended to be loaded into context as needed
└── assets/ - Files used in output (templates, icons, fonts, etc.)
SKILL.md (required)
Every SKILL.md consists of:
- Frontmatter (YAML): Contains
nameanddescriptionfields (required), plus optional fields likelicense,metadata, andcompatibility. Onlynameanddescriptionare read by Claude to determine when the skill triggers, so be clear and comprehensive about what the skill is and when it should be used. Thecompatibilityfield is for noting environment requirements (target product, system packages, etc.) but most skills don't need it. - Body (Markdown): Instructions and guidance for using the skill. Only loaded AFTER the skill triggers (if at all).
Bundled Resources (optional)
Scripts (scripts/)
Executable code (Python/Bash/etc.) for tasks that require deterministic reliability or are repeatedly rewritten.
- When to include: When the same code is being rewritten repeatedly or deterministic reliability is needed
- Example:
scripts/rotate_pdf.pyfor PDF rotation tasks - Benefits: Token efficient, deterministic, may be executed without loading into context
- Note: Scripts may still need to be read by Claude for patching or environment-specific adjustments
References (references/)
Documentation and reference material intended to be loaded as needed into context to inform Claude's process and thinking.
- When to include: For documentation that Claude should reference while working
- Examples:
references/finance.mdfor financial schemas,references/mnda.mdfor company NDA template,references/policies.mdfor company policies,references/api_docs.mdfor API specifications - Use cases: Database schemas, API documentation, domain knowledge, company policies, detailed workflow guides
- Benefits: Keeps SKILL.md lean, loaded only when Claude determines it's needed
- Best practice: If files are large (>10k words), include grep search patterns in SKILL.md
- Avoid duplication: Information should live in either SKILL.md or references files, not both. Prefer references files for detailed information unless it's truly core to the skill—this keeps SKILL.md lean while making information discoverable without hogging the context window. Keep only essential procedural instructions and workflow guidance in SKILL.md; move detailed reference material, schemas, and examples to references files.
Assets (assets/)
Files not intended to be loaded into context, but rather used within the output Claude produces.
- When to include: When the skill needs files that will be used in the final output
- Examples:
assets/logo.pngfor brand assets,assets/slides.pptxfor PowerPoint templates,assets/frontend-template/for HTML/React boilerplate,assets/font.ttffor typography - Use cases: Templates, images, icons, boilerplate code, fonts, sample documents that get copied or modified
- Benefits: Separates output resources from documentation, enables Claude to use files without loading them into context
What to Not Include in a Skill
A skill should only contain essential files that directly support its functionality. Do NOT create extraneous documentation or auxiliary files, including:
- README.md
- INSTALLATION_GUIDE.md
- QUICK_REFERENCE.md
- CHANGELOG.md
- etc.
The skill should only contain the information needed for an AI agent to do the job at hand. It should not contain auxilary context about the process that went into creating it, setup and testing procedures, user-facing documentation, etc. Creating additional documentation files just adds clutter and confusion.
Progressive Disclosure Design Principle
Skills use a three-level loading system to manage context efficiently:
- Metadata (name + description) - Always in context (~100 words)
- SKILL.md body - When skill triggers (<5k words)
- Bundled resources - As needed by Claude (Unlimited because scripts can be executed without reading into context window)
Progressive Disclosure Patterns
Keep SKILL.md body to the essentials and under 500 lines to minimize context bloat. Split content into separate files when approaching this limit. When splitting out content into other files, it is very important to reference them from SKILL.md and describe clearly when to read them, to ensure the reader of the skill knows they exist and when to use them.
Key principle: When a skill supports multiple variations, frameworks, or options, keep only the core workflow and selection guidance in SKILL.md. Move variant-specific details (patterns, examples, configuration) into separate reference files.
Pattern 1: High-level guide with references
# PDF Processing
## Quick start
Extract text with pdfplumber:
[code example]
## Advanced features
- **Form filling**: See [FORMS.md](FORMS.md) for complete guide
- **API reference**: See [REFERENCE.md](REFERENCE.md) for all methods
- **Examples**: See [EXAMPLES.md](EXAMPLES.md) for common patterns
Claude loads FORMS.md, REFERENCE.md, or EXAMPLES.md only when needed.
Pattern 2: Domain-specific organization
For Skills with multiple domains, organize content by domain to avoid loading irrelevant context:
bigquery-skill/
├── SKILL.md (overview and navigation)
└── reference/
├── finance.md (revenue, billing metrics)
├── sales.md (opportunities, pipeline)
├── product.md (API usage, features)
└── marketing.md (campaigns, attribution)
When a user asks about sales metrics, Claude only reads sales.md.
Similarly, for skills supporting multiple frameworks or variants, organize by variant:
cloud-deploy/
├── SKILL.md (workflow + provider selection)
└── references/
├── aws.md (AWS deployment patterns)
├── gcp.md (GCP deployment patterns)
└── azure.md (Azure deployment patterns)
When the user chooses AWS, Claude only reads aws.md.
Pattern 3: Conditional details
Show basic content, link to advanced content:
# DOCX Processing
## Creating documents
Use docx-js for new documents. See [DOCX-JS.md](DOCX-JS.md).
## Editing documents
For simple edits, modify the XML directly.
**For tracked changes**: See [REDLINING.md](REDLINING.md)
**For OOXML details**: See [OOXML.md](OOXML.md)
Claude reads REDLINING.md or OOXML.md only when the user needs those features.
Important guidelines:
- Avoid deeply nested references - Keep references one level deep from SKILL.md. All reference files should link directly from SKILL.md.
- Structure longer reference files - For files longer than 100 lines, include a table of contents at the top so Claude can see the full scope when previewing.
Skill Creation Process
Skill creation involves these steps:
- Understand the skill with concrete examples
- Plan reusable skill contents (scripts, references, assets)
- Initialize the skill (run init_skill.py)
- Edit the skill (implement resources and write SKILL.md)
- Package the skill (run package_skill.py)
- Iterate based on real usage
Follow these steps in order, skipping only if there is a clear reason why they are not applicable.
Step 1: Understanding the Skill with Concrete Examples
Skip this step only when the skill's usage patterns are already clearly understood. It remains valuable even when working with an existing skill.
To create an effective skill, clearly understand concrete examples of how the skill will be used. This understanding can come from either direct user examples or generated examples that are validated with user feedback.
For example, when building an image-editor skill, relevant questions include:
- "What functionality should the image-editor skill support? Editing, rotating, anything else?"
- "Can you give some examples of how this skill would be used?"
- "I can imagine users asking for things like 'Remove the red-eye from this image' or 'Rotate this image'. Are there other ways you imagine this skill being used?"
- "What would a user say that should trigger this skill?"
To avoid overwhelming users, avoid asking too many questions in a single message. Start with the most important questions and follow up as needed for better effectiveness.
Conclude this step when there is a clear sense of the functionality the skill should support.
Step 2: Planning the Reusable Skill Contents
To turn concrete examples into an effective skill, analyze each example by:
- Considering how to execute on the example from scratch
- Identifying what scripts, references, and assets would be helpful when executing these workflows repeatedly
Example: When building a pdf-editor skill to handle queries like "Help me rotate this PDF," the analysis shows:
- Rotating a PDF requires re-writing the same code each time
- A
scripts/rotate_pdf.pyscript would be helpful to store in the skill
Example: When designing a frontend-webapp-builder skill for queries like "Build me a todo app" or "Build me a dashboard to track my steps," the analysis shows:
- Writing a frontend webapp requires the same boilerplate HTML/React each time
- An
assets/hello-world/template containing the boilerplate HTML/React project files would be helpful to store in the skill
Example: When building a big-query skill to handle queries like "How many users have logged in today?" the analysis shows:
- Querying BigQuery requires re-discovering the table schemas and relationships each time
- A
references/schema.mdfile documenting the table schemas would be helpful to store in the skill
To establish the skill's contents, analyze each concrete example to create a list of the reusable resources to include: scripts, references, and assets.
Step 3: Initializing the Skill
At this point, it is time to actually create the skill.
Skip this step if the skill being developed already exists, and iteration or packaging is needed. In this case, continue to the next step.
When creating a new skill from scratch, always run the init_skill.py script. The script conveniently generates a new template skill directory that automatically includes everything a skill requires, making the skill creation process much more efficient and reliable.
Usage:
skills/skill-creator/scripts/init_skill.py --name <skill-name> --path <output-directory>
The script:
- Creates the skill directory at the specified path
- Generates a SKILL.md template with proper frontmatter and TODO placeholders
- Creates example resource directories:
scripts/,references/, andassets/ - Adds example files in each directory that can be customized or deleted
After initialization, customize or remove the generated SKILL.md and example files as needed.
Step 4: Edit the Skill
When editing the (newly-generated or existing) skill, remember that the skill is being created for another instance of Claude to use. Include information that would be beneficial and non-obvious to Claude. Consider what procedural knowledge, domain-specific details, or reusable assets would help another Claude instance execute these tasks more effectively.
Learn Proven Design Patterns
Consult these helpful guides based on your skill's needs:
- Multi-step processes: See references/workflows.md for sequential workflows and conditional logic
- Specific output formats or quality standards: See references/output-patterns.md for template and example patterns
These files contain established best practices for effective skill design.
Start with Reusable Skill Contents
To begin implementation, start with the reusable resources identified above: scripts/, references/, and assets/ files. Note that this step may require user input. For example, when implementing a brand-guidelines skill, the user may need to provide brand assets or templates to store in assets/, or documentation to store in references/.
Added scripts must be tested by actually running them to ensure there are no bugs and that the output matches what is expected. If there are many similar scripts, only a representative sample needs to be tested to ensure confidence that they all work while balancing time to completion.
Any example files and directories not needed for the skill should be deleted. The initialization script creates example files in scripts/, references/, and assets/ to demonstrate structure, but most skills won't need all of them.
Update SKILL.md
Writing Guidelines: Always use imperative/infinitive form.
Frontmatter
Write the YAML frontmatter with name and description:
name: The skill namedescription: This is the primary triggering mechanism for your skill, and helps Claude understand when to use the skill.- Include both what the Skill does and specific triggers/contexts for when to use it.
- Include all "when to use" information here - Not in the body. The body is only loaded after triggering, so "When to Use This Skill" sections in the body are not helpful to Claude.
- Example description for a
docxskill: "Comprehensive document creation, editing, and analysis with support for tracked changes, comments, formatting preservation, and text extraction. Use when Claude needs to work with professional documents (.docx files) for: (1) Creating new documents, (2) Modifying or editing content, (3) Working with tracked changes, (4) Adding comments, or any other document tasks"
Do not include any other fields in YAML frontmatter.
Body
Write instructions for using the skill and its bundled resources.
Step 5: Write the Skill to the Project
IMPORTANT: All generated skills must be saved under the current project's .claude/skills/ directory so they are project-scoped and only take effect in this project.
The project root path is available via the MAX_PROJECT_PATH environment variable.
$MAX_PROJECT_PATH/.claude/skills/<skill-name>/
├── SKILL.md
├── scripts/ (if needed)
├── references/ (if needed)
└── assets/ (if needed)
When running init_skill.py, use $MAX_PROJECT_PATH/.claude/skills/ as the output path:
skills/skill-creator/scripts/init_skill.py --name <skill-name> --path "$MAX_PROJECT_PATH/.claude/skills"
If Python scripts are created, make them executable:
chmod +x "$MAX_PROJECT_PATH/.claude/skills/<skill-name>/scripts/<script>.py"
Create Commands Symlink
Claude CLI resolves project-scoped slash commands from .claude/commands/, not .claude/skills/. Create a symlink so /project:<skill-name> works:
mkdir -p "$MAX_PROJECT_PATH/.claude/commands"
ln -sf "$MAX_PROJECT_PATH/.claude/skills/<skill-name>/SKILL.md" "$MAX_PROJECT_PATH/.claude/commands/<skill-name>.md"
Note:
init_skill.pycreates this symlink automatically when the output path is$MAX_PROJECT_PATH/.claude/skills.
Step 6: Iterate
After testing the skill, users may request improvements. Often this happens right after using the skill, with fresh context of how the skill performed.
Iteration workflow:
- Use the skill on real tasks
- Notice struggles or inefficiencies
- Identify how SKILL.md or bundled resources should be updated
- Implement changes and test again
Video Generator
Generate videos via Maxgent FAL API proxy. Supports text-to-video, image-to-video, and first/last frame mode.
Prerequisites
MAX_API_KEYenvironment variable (auto-injected by Max)- Python 3.10+ (supports
uv runorpython3)
Routing
- Default auto-routing (high quality)
- Text-to-video:
fal-ai/veo3.1 - Image-to-video:
fal-ai/sora-2/image-to-video/pro
- Text-to-video:
- Optional explicit models
veo-3.1sora-2-prokling-v3-prokling-v3-standard
First/last frame default routing:
fal-ai/veo3.1/first-last-frame-to-video- With
--fast-first-last:fal-ai/veo3.1/fast/first-last-frame-to-video
Usage
uv run skills/video-gen/video-gen.py \
--model MODEL --prompt "PROMPT" --size SIZE --seconds N \
--output-dir DIR \
[--start-image PATH] [--end-image PATH] \
[--frame-mode auto|start|start-end] [--fast-first-last] \
[--generate-audio true|false] [--enhance-prompt true|false] \
[--negative-prompt TEXT] [--cfg-scale N]
Parameters:
--model:auto(recommended),veo-3.1,sora-2-pro,kling-v3-pro,kling-v3-standard--prompt: video description--size:720P,1080P,1280x720,720x1280--seconds: duration, e.g.8or8s--output-dir: output directory — default to$MAX_PROJECT_PATH(the user's project root)--start-image: start frame image path or URL (for image-to-video)--end-image: end frame image path or URL (for first/last frame mode)--frame-mode:auto(default),start,start-end--fast-first-last: use Veo fast first/last frame route--generate-audio: enable audio generation (defaulttrue)--enhance-prompt: enable prompt enhancement (defaulttrue)--negative-prompt: negative prompt (Kling only)--cfg-scale: CFG scale (Kling only)
Examples
# Text-to-video (default routing)
uv run skills/video-gen/video-gen.py --model auto --prompt "a golden retriever running on the beach, camera follows" --size 720P --seconds 8 --output-dir "$MAX_PROJECT_PATH"
# Image-to-video (Sora Pro)
uv run skills/video-gen/video-gen.py --model sora-2-pro --prompt "make the person smile and wave" --size 1280x720 --seconds 8 --output-dir "$MAX_PROJECT_PATH" --start-image "/path/to/start.jpg"
# First/last frame (Veo)
uv run skills/video-gen/video-gen.py --model auto --prompt "smooth transition from winter to spring" --size 1080P --seconds 8 --output-dir "$MAX_PROJECT_PATH" \
--start-image "/path/to/start.jpg" \
--end-image "/path/to/end.jpg" \
--frame-mode start-end
Instructions
- Check
MAX_API_KEY. - Use AskUserQuestion to collect: prompt, duration, resolution, first/last frame option, quality tier. Default output path to
$MAX_PROJECT_PATH. - For local images, the script auto-uploads via proxy to get an accessible URL.
- Wait for queue completion and download the output mp4.
- On success, report the saved path.
- On failure:
- HTTP 402 (insufficient credits): Stop immediately. Do NOT retry. Tell the user their API credits are exhausted.
- Other errors: retry once with a different model or adjusted parameters. If it fails again, stop and report the error.
YouTube Downloader
Download YouTube videos, audio, or subtitles using yt-dlp, with Chrome cookies for authenticated content.
Prerequisites
Uses uvx to run yt-dlp — no manual installation required.
Usage
When the user wants to download from YouTube: $ARGUMENTS
Instructions
Important: All yt-dlp commands use uvx yt-dlp. uvx handles installation and environment isolation automatically.
Step 1: Get video URL
If the user has not provided a video URL, ask them to provide one.
Supported sites include but are not limited to:
- YouTube (youtube.com, youtu.be)
- Bilibili (bilibili.com)
- Twitter/X (twitter.com, x.com)
- And other sites supported by yt-dlp
Step 2: Parse video info
Fetch video info with yt-dlp using Chrome cookies:
uvx yt-dlp --cookies-from-browser chrome -j "$VIDEO_URL" 2>/dev/null
Extract key info from the JSON output:
title: video titleduration: duration (seconds)formats: available format listsubtitles: available subtitlesautomatic_captions: auto-generated captions
Show the user:
- Video title
- Duration
- Available video qualities (e.g. 1080p, 720p, 480p)
- Available audio formats
- Available subtitle languages
If parsing fails, it may require login or the video is unavailable — inform the user of the specific reason.
Step 3: Ask user for download options
Warning: You MUST use AskUserQuestion to collect user preferences. Do not skip this step.
Use AskUserQuestion to collect the following:
-
Download content: What do you want to download?
- Options:
- "Video + Audio - Complete video file (Recommended)"
- "Audio only - MP3/M4A format"
- "Subtitles only - SRT/VTT format"
- "Video + Audio + Subtitles - Download all"
- Options:
-
Video quality (if downloading video): Choose video quality
- Options:
- "Best quality (Recommended)"
- "1080p - Full HD"
- "720p - HD"
- "480p - SD (save space)"
- "Lowest quality (smallest file)"
- Options:
-
Audio format (if downloading audio only): Choose audio format
- Options:
- "MP3 - Universal format (Recommended)"
- "M4A - High quality"
- "Best quality (keep original format)"
- Options:
-
Subtitle language (if subtitles available): Choose subtitle language
- Dynamically generate options based on parsed results
- Common options: Chinese, English, Japanese, auto-generated captions
-
Output path: Where to save?
- Default: current directory
- Allow custom path
Step 4: Build yt-dlp command
Build the yt-dlp command based on user choices:
Base options (always used)
--cookies-from-browser chrome # Use Chrome cookies
-o "%(title)s.%(ext)s" # Output filename format
--no-playlist # Don't download playlists
Video + Audio download
# Best quality
uvx yt-dlp --cookies-from-browser chrome -f "bestvideo+bestaudio/best" --merge-output-format mp4 -o "OUTPUT_PATH/%(title)s.%(ext)s" "URL"
# Specific resolution
uvx yt-dlp --cookies-from-browser chrome -f "bestvideo[height<=1080]+bestaudio/best[height<=1080]" --merge-output-format mp4 -o "OUTPUT_PATH/%(title)s.%(ext)s" "URL"
# 720p
uvx yt-dlp --cookies-from-browser chrome -f "bestvideo[height<=720]+bestaudio/best[height<=720]" --merge-output-format mp4 -o "OUTPUT_PATH/%(title)s.%(ext)s" "URL"
Audio only download
# MP3 format
uvx yt-dlp --cookies-from-browser chrome -x --audio-format mp3 --audio-quality 0 -o "OUTPUT_PATH/%(title)s.%(ext)s" "URL"
# M4A format
uvx yt-dlp --cookies-from-browser chrome -x --audio-format m4a --audio-quality 0 -o "OUTPUT_PATH/%(title)s.%(ext)s" "URL"
# Best quality (original format)
uvx yt-dlp --cookies-from-browser chrome -x --audio-quality 0 -o "OUTPUT_PATH/%(title)s.%(ext)s" "URL"
Subtitles only download
# Download all subtitles
uvx yt-dlp --cookies-from-browser chrome --write-subs --skip-download -o "OUTPUT_PATH/%(title)s.%(ext)s" "URL"
# Download specific language subtitles
uvx yt-dlp --cookies-from-browser chrome --write-subs --sub-langs "zh,en" --skip-download -o "OUTPUT_PATH/%(title)s.%(ext)s" "URL"
# Download auto-generated captions
uvx yt-dlp --cookies-from-browser chrome --write-auto-subs --sub-langs "zh,en" --skip-download -o "OUTPUT_PATH/%(title)s.%(ext)s" "URL"
# Convert to SRT format
uvx yt-dlp --cookies-from-browser chrome --write-subs --sub-format srt --convert-subs srt --skip-download -o "OUTPUT_PATH/%(title)s.%(ext)s" "URL"
Video + Subtitles together
uvx yt-dlp --cookies-from-browser chrome -f "bestvideo+bestaudio/best" --merge-output-format mp4 --write-subs --sub-langs "zh,en" --embed-subs -o "OUTPUT_PATH/%(title)s.%(ext)s" "URL"
Step 5: Execute download
- Show the full yt-dlp command to the user before execution
- Run the command and show download progress
- Report success or failure
Step 6: Verify output
After download completes:
ls -la "OUTPUT_PATH"
Report:
- Downloaded filename and size
- List subtitle files if downloaded
- Any warnings or issues
Troubleshooting
Login-required content:
- Ensure the user is logged in to the site in Chrome
- If still failing, suggest manually exporting cookies
Region-restricted:
- Inform the user they may need a proxy
- Try
--geo-bypassto bypass restrictions
Download failure:
- Check if the URL is correct
- Try updating yt-dlp:
uvx --refresh yt-dlp --version - Check network connectivity
Sponsors
Details
- Marketplace
- maxgent-ai/maxgent-plugin
- Author
- Maxgent AI
- Category
- Community
- License
- MIT
- Keywords
- macos, homebrew, video, ffmpeg, automation