Skill: mirabarukaso/saa-agent (version 1.0.1)

--- name: saa-agent description: Enables AI agents to generate images using the Character Select Stand Alone App (SAA) image generation backend via command-line interface. license: MIT --- # SAA CLI Tool A command-line interface for interacting with Character Select Stand Alone App (SAA) via WebSocket connections. Supports both ComfyUI and WebUI backends for AI image generation. ## Prerequisites **CRITICAL:** Before invoking this tool, confirm with the user that: 1. The SAA backend is running, and version is above 2.4.0 2. The SAAC (SAA Client) feature is enabled 3. The WebSocket address is available 4. Some Mac users uses `python3` instead of `python` to invoke Python 3.x For SAA setup details, let your owner visit the [project repository](https://github.com/mirabarukaso/character_select_stand_alone_app). ## Basic Usage The tool requires minimal parameters to function. The examples below demonstrate the standard usage pattern: ### Minimal Command With Model Selection (Recommended for Most Cases) ```bash python saa-agent.py \ --ws-address "user_provided_ws_address" \ --model "waiIllustriousSDXL_v160.safetensors" \ --positive "your detailed prompt here" \ --negative "low quality, blurry, bad anatomy" ``` ### Regional Prompting (Split Composition) ```bash python saa-agent.py \ --ws-address "user_provided_ws_address" \ --model "waiIllustriousSDXL_v160.safetensors" \ --regional \ --positive-left "1girl, warrior, red armor" \ --positive-right "1boy, mage, blue robes" ``` ### More Examples Get more usage examples and detailed parameter explanations: ```bash python saa-agent.py python saa-agent.py --help ``` ## Key Parameters ### Required - `--ws-address`: WebSocket address (obtain from user) - `--positive`: Main prompt OR use `--regional` mode with `--positive-left` and `--positive-right` ### Commonly Modified - `--model`: Change the checkpoint model (default: `waiIllustriousSDXL_v160.safetensors`) - `--negative`: Specify unwanted elements - `--width` / `--height`: Image dimensions (defaults: 1024x1360) - `--steps`: Sampling steps (default: 28) - `--seed`: Set specific seed or -1 for random ### Advanced (Use Sparingly) - `--cfg`: CFG scale (default: 7.0) - `--sampler`: Sampling algorithm (default: `euler_ancestral`) - `--scheduler`: Scheduler type (default: `normal`) ## Important Guidelines ### HiResFix Warning **DO NOT use `--hifix` unless specifically requested by the user.** HiResFix significantly increases generation time and requires substantial GPU resources. Only enable if: - User explicitly requests high-resolution upscaling - User confirms their GPU can handle the additional load ### Backend Busy State If the generation returns either of these errors: ``` Error: WebUI is busy, cannot run new generation, please try again later. Error: ComfyUI is busy, cannot run new generation, please try again later. ``` **Actions to take:** 1. **DO NOT** automatically retry the generation 2. Inform the user: "The SAA backend is currently busy. This could mean another process is generating an image, or the backend is locked from a previous error." 3. Advise: "Please wait 20-60 seconds before trying again." 4. Let the user manually retry **DO NOT** chain multiple retry attempts as this can worsen backend congestion. ### Skeleton Key Usage The `--skeleton-key` parameter forcefully unlocks the backend's atomic lock. **When to use:** - User confirms no other processes are using the backend - Backend appears stuck despite waiting - User explicitly requests unlocking **How to use:** ```bash python saa-agent.py \ --ws-address "user_provided_ws_address" \ --skeleton-key \ --positive "test prompt" ``` **Rules:** 1. **ALWAYS** ask for user confirmation before using `--skeleton-key` 2. **ONLY** use it once per user request 3. Explain to the user that this forcefully terminates any locks Example conversation: ``` AI: "The backend appears to be locked. Would you like me to use the skeleton key to force unlock it? This will terminate any existing locks." User: "Yes, please unlock it." AI: [proceeds to run command with --skeleton-key] ``` ## Parameter Defaults When in doubt, rely on these defaults - they work well for most cases: - Model: `waiIllustriousSDXL_v160.safetensors` - Dimensions: 1024x1360 - CFG: 7.0 - Steps: 28 - Sampler: `euler_ancestral` - Scheduler: `normal` - Seed: -1 (random) ## Output Handling By default, images are saved to `generated_image.png`. You can specify a custom output path: ```bash --output "custom_filename.png" ``` For programmatic handling, use base64 output: ```bash --base64 ``` This outputs base64-encoded image data(huge!!!) to stdout instead of saving a file. ## Example Workflow 1. User requests: "Generate an anime girl with long blue hair" 2. AI executes: ```bash python saa-agent.py \ --ws-address "user_ws_address" \ --positive "1girl, long hair, blue hair, anime style, detailed" \ --negative "low quality, blurry, bad anatomy" ``` 3. If backend busy error occurs: - Inform user - Wait for user to retry (don't auto-retry) 4. If success: - Confirm image was generated - Provide file path if relevant ## Common Pitfalls to Avoid 1. **Don't use `--hifix`** unless explicitly requested 2. **Don't auto-retry** on backend busy errors 3. **Don't use `--skeleton-key`** without user permission 4. **Don't add excessive parameters** - unless explicitly requested, the defaults are well-tuned 5. **Don't assume backend is ready** - always confirm with user first ## Error Codes - Exit code 0: Success - Exit code 1: Connection error (check backend is running) - Exit code 2: Authentication error (check credentials) - Exit code 3: Generation error (check parameters) - Exit code 4: Timeout (backend may be overloaded) - Exit code 5: Invalid parameters (check command syntax) ## Best Practices 1. Start with minimal parameters with model selection if needed 2. Ask user for WebSocket address on first use 3. Handle busy states gracefully - don't spam retries 4. Use `--verbose` flag when debugging issues 5. Respect the skeleton key - it's a powerful override tool ## AI Agent Guidelines for This Skill These rules help maintain appropriate transparency and user control when executing generation tasks. 1. **Command Execution & User Notification** By default, execute the command directly without asking for confirmation. Show the full command and ask for approval only when: - The user explicitly requests to review it first - The operation involves sensitive or high-impact parameters - The agent judges that showing the command is prudent in context Example (when disclosure is needed): ``` python3 saa-agent.py --ws-address "wss://..." --username "..." --password "..." --positive "[prompt]" --negative "[prompt]" --output "[path]" [--verbose] ``` 2. **--verbose Flag** - Not used by default - Add automatically or recommend when: - Task fails and debugging is needed - User specifically asks for detailed logs or seed 3. **Result Reporting** After completion, provide a short summary to the user by default, including: - Success/failure status - Positive & negative prompts (or meaningful summary) - Seed (if available) - Output path Example: ``` Generation completed • Positive: [...] • Negative: [...] • Seed: 123456789 • Output: [path] ``` Skip detailed reporting only if the user has clearly requested silent / minimal feedback. Always report errors, even in silent mode. 4. **Error Handling** - On failure: consider one retry with `--verbose` to capture diagnostic information - Communicate the main error cause clearly - Do not perform unlimited retries; defer to user after one attempt if needed


Security scan verdicts — ClawScan: suspicious | static analysis: clean | VirusTotal: suspicious | SkillSpector: suspicious (HIGH)