natureco-cli 5.18.2 → 5.19.0

package/skills/skills-cli/SKILL.md

@@ -0,0 +1,281 @@
+---
+name: skills-cli
+description: Use when users ask to discover, install, list, check, update, remove, back up, restore, sync, or initialize Agent Skills, mention `bunx skills`, `npx skills`, `skills.sh`, or `skills-lock.json`, ask "find a skill for X", or want help extending agent capabilities with installable skills.
+---
+
+Use this skill to help users work with the open Agent Skills ecosystem through the `skills` CLI.
+
+## Overview
+
+The `skills` CLI is the package manager for installable Agent Skills. Use it to discover skills, install them with the right flags, and manage them after installation.
+
+Examples below use `bunx skills`, but `npx skills` is the same workflow if Bun is not available in the user's environment.
+
+Always prefer the current CLI syntax:
+
+```bash
+bunx skills add <source> --skill <name>
+```
+
+Do not use older `owner/repo@skill-name` examples.
+
+## When to Use
+
+Use this skill when the user:
+
+- asks "find a skill for X", "is there a skill for X", or "how do I do X" and X sounds like a reusable workflow
+- asks "can you do X" and X sounds like a specialized capability that may already exist as a skill
+- wants help with `bunx skills`, `npx skills`, `skills.sh`, skill package installation, or `skills-lock.json`
+- wants to install a skill for a specific agent such as Codex or OpenCode
+- wants to list, check, update, remove, restore, sync, back up, or initialize installed skills
+- wants help searching for workflows, tools, templates, or domain-specific capabilities such as design, testing, deployment, documentation, or code review
+
+Do not use this skill when the user already has a local skill and wants help writing or improving its contents. In that case, use a skill-authoring workflow instead.
+
+## Discovery Workflow
+
+When a user needs a skill, follow this sequence:
+
+1. Identify the domain and task.
+   Examples: React performance, PR review, changelog generation, PDF extraction.
+   Also judge whether the task is common enough that a reusable skill is likely to exist.
+2. Check [skills.sh](https://skills.sh/) first.
+   Prefer well-known, well-installed skills when the domain is already covered there.
+3. If the leaderboard does not clearly answer the need, search with:
+
+```bash
+bunx skills find <query>
+```
+
+1. Verify quality before recommending anything:
+   - install count: prefer skills with 1K+ installs and be cautious with anything under 100
+   - source reputation: prefer official or well-established maintainers such as `openai`, `anthropics`, `microsoft`, or similarly trusted publishers
+   - repository quality: check the source repository and treat skills from repos with fewer than 100 stars skeptically
+2. Present the options clearly.
+   Include the skill name, what it helps with, the install count and source, why it looks trustworthy, the install command, and a link to learn more on `skills.sh`.
+3. Offer installation help if the user wants to proceed.
+4. If nothing fits, say so directly, help with the task using your general capabilities, and mention that the user can create their own package with `bunx skills init`.
+
+## Installation Quick Reference
+
+### Common sources
+
+```bash
+# GitHub shorthand
+bunx skills add xixu-me/skills
+
+# Full GitHub URL
+bunx skills add https://github.com/xixu-me/skills
+
+# Direct path to one skill inside a repo
+bunx skills add https://github.com/xixu-me/skills/tree/main/skills/skills-cli
+
+# GitLab URL
+bunx skills add https://gitlab.com/org/repo
+
+# Any git URL
+bunx skills add git@github.com:owner/repo.git
+
+# Local package path
+bunx skills add ./my-local-skills
+```
+
+### Common install patterns
+
+```bash
+# List skills in a package without installing
+bunx skills add <source> --list
+
+# Install one skill
+bunx skills add <source> --skill skills-cli
+
+# Install multiple skills
+bunx skills add <source> --skill pr-review --skill commit
+
+# Install globally
+bunx skills add <source> --skill skills-cli -g -y
+
+# Install to a specific agent
+bunx skills add <source> --skill skills-cli -a codex -y
+
+# Install all skills to all agents
+bunx skills add <source> --all
+
+# Install all skills to one agent
+bunx skills add <source> --skill '*' -a codex -y
+
+# Copy files instead of symlinking
+bunx skills add <source> --skill skills-cli -a codex --copy -y
+```
+
+### Installation methods
+
+When the user is choosing how to install:
+
+- symlink is the default and usually the best choice because updates stay centralized
+- `--copy` creates independent copies and is the fallback when symlinks are unsupported or inconvenient
+
+If the user only asks to install a skill, prefer the default symlink workflow unless they mention CI packaging, portability, filesystem restrictions, or explicitly ask for copies.
+
+### Important flags
+
+| Flag                  | Use                                            |
+| --------------------- | ---------------------------------------------- |
+| `--skill <name>`      | install one or more named skills               |
+| `-a, --agent <agent>` | target specific agents such as `codex`         |
+| `-g, --global`        | install at user scope instead of project scope |
+| `-y, --yes`           | skip prompts                                   |
+| `--list`              | list available skills in a package             |
+| `--copy`              | copy instead of symlink                        |
+| `--all`               | shorthand for all skills to all agents         |
+
+## Managing Installed Skills
+
+Use these commands for ongoing maintenance:
+
+```bash
+# List installed skills
+bunx skills ls
+bunx skills ls -g
+bunx skills ls -a codex
+bunx skills ls --json
+
+# Check for updates
+bunx skills check
+
+# Update installed skills
+bunx skills update
+
+# Remove installed skills
+bunx skills remove my-skill
+bunx skills remove my-skill -a codex
+bunx skills remove -g my-skill
+bunx skills remove --all
+
+# Initialize a new skill package
+bunx skills init
+bunx skills init my-skill
+
+# Restore from skills-lock.json
+bunx skills experimental_install
+
+# Sync node_modules skills into agent directories
+bunx skills experimental_sync
+bunx skills experimental_sync -a codex -y
+```
+
+When the user asks to initialize a skill, explain whether they want:
+
+- `bunx skills init` to create `SKILL.md` in the current directory
+- `bunx skills init <name>` to create a new subdirectory containing `SKILL.md`
+
+## Related Tool: Skills Vault
+
+If the user wants declarative backup and restore of installed skills across machines or teams, use [Skills Vault](https://github.com/xixu-me/skills-vault).
+
+Skills Vault is a separate CLI companion for the `skills` ecosystem. It is not a `skills add` installable skill source. Use it when the user wants to snapshot installed skills into a manifest, preview restore commands, or reproduce the same setup elsewhere.
+
+Common companion commands:
+
+```bash
+# Back up installed skills into skvlt.yaml
+bunx skvlt backup
+
+# Preview a restore
+bunx skvlt restore --dry-run
+
+# Restore everything from the manifest
+bunx skvlt restore --all
+
+# Diagnose the local environment
+bunx skvlt doctor
+```
+
+Prefer this tool over `skills experimental_*` when the user explicitly wants a portable manifest workflow, cross-machine backup and restore, or team-sharing of installed skill setups.
+
+## Recommendation Format
+
+When recommending a skill, keep the answer concrete and installable.
+
+Use a structure like this:
+
+```text
+I found a skill that should fit.
+
+Skill: <skill-name>
+Why it matches: <one sentence>
+Source: <owner/repo or URL>
+Quality check: <install count / source reputation / repository confidence note>
+Install:
+bunx skills add <source> --skill <skill-name> [optional flags]
+Learn more: https://skills.sh/<publisher>/<package>/<skill-name>
+
+If you want, I can install it for <agent-or-scope>.
+```
+
+If the user mentions a target agent or scope, include it in the command. Examples:
+
+```bash
+bunx skills add <source> --skill <skill-name> -a codex -y
+bunx skills add <source> --skill <skill-name> -g -y
+```
+
+Example:
+
+```text
+I found a skill that might help.
+
+Skill: screenshot
+Why it matches: it focuses on OS-level desktop and window screenshot capture.
+Source: openai/skills
+Quality check: high install volume, trusted publisher, and a widely used source repository.
+Install:
+bunx skills add openai/skills --skill screenshot
+Learn more: https://skills.sh/openai/skills/screenshot
+```
+
+## Common Skill Categories
+
+When the user's wording is vague, map it to likely categories:
+
+| Category        | Example queries                                    |
+| --------------- | -------------------------------------------------- |
+| Web Development | `react`, `nextjs`, `typescript`, `css`, `tailwind` |
+| Testing         | `testing`, `jest`, `playwright`, `e2e`             |
+| DevOps          | `deploy`, `docker`, `kubernetes`, `ci-cd`          |
+| Documentation   | `docs`, `readme`, `changelog`, `api-docs`          |
+| Code Quality    | `review`, `lint`, `refactor`, `best-practices`     |
+| Design          | `ui`, `ux`, `design-system`, `accessibility`       |
+| Productivity    | `workflow`, `automation`, `git`                    |
+
+## Search Tips
+
+- Use specific keywords. `react testing` is better than just `testing`.
+- Try alternative terms. If `deploy` fails, try `deployment` or `ci-cd`.
+- Check popular sources first. Many strong skills come from established publishers.
+- If the first search is too broad, narrow by domain plus task.
+
+## Common Mistakes
+
+- Recommending a skill from search results without checking whether it looks established.
+- Forgetting to specify `-a <agent>` when the user asked for one particular agent.
+- Treating `bunx skills find --help` like a real help command. Use `bunx skills --help` for command help instead.
+- Assuming no skill exists after one weak search term. Try a more specific or adjacent query first.
+
+## Troubleshooting
+
+If the user hits an error or confusing result:
+
+- "No skills found" - suggest a better query, check [skills.sh](https://skills.sh/), or help directly and mention `bunx skills init`
+- interactive prompts in automation or CI - add `-y`
+- wrong installation scope - switch between project install and `-g`
+- symlink issues - retry with `--copy`
+- uncertainty about available package contents - run `bunx skills add <source> --list`
+- uncertainty about installed state - run `bunx skills ls` or `bunx skills ls --json`
+- portable backup or restore across machines - mention [Skills Vault](https://github.com/xixu-me/skills-vault) and its `backup` / `restore --dry-run` workflow
+
+When you are unsure about exact flags, use:
+
+```bash
+bunx skills --help
+```

package/skills/slack-gif-creator/SKILL.md

@@ -0,0 +1,254 @@
+---
+name: slack-gif-creator
+description: Knowledge and utilities for creating animated GIFs optimized for Slack. Provides constraints, validation tools, and animation concepts. Use when users request animated GIFs for Slack like "make me a GIF of X doing Y for Slack."
+license: Complete terms in LICENSE.txt
+---
+
+# Slack GIF Creator
+
+A toolkit providing utilities and knowledge for creating animated GIFs optimized for Slack.
+
+## Slack Requirements
+
+**Dimensions:**
+- Emoji GIFs: 128x128 (recommended)
+- Message GIFs: 480x480
+
+**Parameters:**
+- FPS: 10-30 (lower is smaller file size)
+- Colors: 48-128 (fewer = smaller file size)
+- Duration: Keep under 3 seconds for emoji GIFs
+
+## Core Workflow
+
+```python
+from core.gif_builder import GIFBuilder
+from PIL import Image, ImageDraw
+
+# 1. Create builder
+builder = GIFBuilder(width=128, height=128, fps=10)
+
+# 2. Generate frames
+for i in range(12):
+    frame = Image.new('RGB', (128, 128), (240, 248, 255))
+    draw = ImageDraw.Draw(frame)
+
+    # Draw your animation using PIL primitives
+    # (circles, polygons, lines, etc.)
+
+    builder.add_frame(frame)
+
+# 3. Save with optimization
+builder.save('output.gif', num_colors=48, optimize_for_emoji=True)
+```
+
+## Drawing Graphics
+
+### Working with User-Uploaded Images
+If a user uploads an image, consider whether they want to:
+- **Use it directly** (e.g., "animate this", "split this into frames")
+- **Use it as inspiration** (e.g., "make something like this")
+
+Load and work with images using PIL:
+```python
+from PIL import Image
+
+uploaded = Image.open('file.png')
+# Use directly, or just as reference for colors/style
+```
+
+### Drawing from Scratch
+When drawing graphics from scratch, use PIL ImageDraw primitives:
+
+```python
+from PIL import ImageDraw
+
+draw = ImageDraw.Draw(frame)
+
+# Circles/ovals
+draw.ellipse([x1, y1, x2, y2], fill=(r, g, b), outline=(r, g, b), width=3)
+
+# Stars, triangles, any polygon
+points = [(x1, y1), (x2, y2), (x3, y3), ...]
+draw.polygon(points, fill=(r, g, b), outline=(r, g, b), width=3)
+
+# Lines
+draw.line([(x1, y1), (x2, y2)], fill=(r, g, b), width=5)
+
+# Rectangles
+draw.rectangle([x1, y1, x2, y2], fill=(r, g, b), outline=(r, g, b), width=3)
+```
+
+**Don't use:** Emoji fonts (unreliable across platforms) or assume pre-packaged graphics exist in this skill.
+
+### Making Graphics Look Good
+
+Graphics should look polished and creative, not basic. Here's how:
+
+**Use thicker lines** - Always set `width=2` or higher for outlines and lines. Thin lines (width=1) look choppy and amateurish.
+
+**Add visual depth**:
+- Use gradients for backgrounds (`create_gradient_background`)
+- Layer multiple shapes for complexity (e.g., a star with a smaller star inside)
+
+**Make shapes more interesting**:
+- Don't just draw a plain circle - add highlights, rings, or patterns
+- Stars can have glows (draw larger, semi-transparent versions behind)
+- Combine multiple shapes (stars + sparkles, circles + rings)
+
+**Pay attention to colors**:
+- Use vibrant, complementary colors
+- Add contrast (dark outlines on light shapes, light outlines on dark shapes)
+- Consider the overall composition
+
+**For complex shapes** (hearts, snowflakes, etc.):
+- Use combinations of polygons and ellipses
+- Calculate points carefully for symmetry
+- Add details (a heart can have a highlight curve, snowflakes have intricate branches)
+
+Be creative and detailed! A good Slack GIF should look polished, not like placeholder graphics.
+
+## Available Utilities
+
+### GIFBuilder (`core.gif_builder`)
+Assembles frames and optimizes for Slack:
+```python
+builder = GIFBuilder(width=128, height=128, fps=10)
+builder.add_frame(frame)  # Add PIL Image
+builder.add_frames(frames)  # Add list of frames
+builder.save('out.gif', num_colors=48, optimize_for_emoji=True, remove_duplicates=True)
+```
+
+### Validators (`core.validators`)
+Check if GIF meets Slack requirements:
+```python
+from core.validators import validate_gif, is_slack_ready
+
+# Detailed validation
+passes, info = validate_gif('my.gif', is_emoji=True, verbose=True)
+
+# Quick check
+if is_slack_ready('my.gif'):
+    print("Ready!")
+```
+
+### Easing Functions (`core.easing`)
+Smooth motion instead of linear:
+```python
+from core.easing import interpolate
+
+# Progress from 0.0 to 1.0
+t = i / (num_frames - 1)
+
+# Apply easing
+y = interpolate(start=0, end=400, t=t, easing='ease_out')
+
+# Available: linear, ease_in, ease_out, ease_in_out,
+#           bounce_out, elastic_out, back_out
+```
+
+### Frame Helpers (`core.frame_composer`)
+Convenience functions for common needs:
+```python
+from core.frame_composer import (
+    create_blank_frame,         # Solid color background
+    create_gradient_background,  # Vertical gradient
+    draw_circle,                # Helper for circles
+    draw_text,                  # Simple text rendering
+    draw_star                   # 5-pointed star
+)
+```
+
+## Animation Concepts
+
+### Shake/Vibrate
+Offset object position with oscillation:
+- Use `math.sin()` or `math.cos()` with frame index
+- Add small random variations for natural feel
+- Apply to x and/or y position
+
+### Pulse/Heartbeat
+Scale object size rhythmically:
+- Use `math.sin(t * frequency * 2 * math.pi)` for smooth pulse
+- For heartbeat: two quick pulses then pause (adjust sine wave)
+- Scale between 0.8 and 1.2 of base size
+
+### Bounce
+Object falls and bounces:
+- Use `interpolate()` with `easing='bounce_out'` for landing
+- Use `easing='ease_in'` for falling (accelerating)
+- Apply gravity by increasing y velocity each frame
+
+### Spin/Rotate
+Rotate object around center:
+- PIL: `image.rotate(angle, resample=Image.BICUBIC)`
+- For wobble: use sine wave for angle instead of linear
+
+### Fade In/Out
+Gradually appear or disappear:
+- Create RGBA image, adjust alpha channel
+- Or use `Image.blend(image1, image2, alpha)`
+- Fade in: alpha from 0 to 1
+- Fade out: alpha from 1 to 0
+
+### Slide
+Move object from off-screen to position:
+- Start position: outside frame bounds
+- End position: target location
+- Use `interpolate()` with `easing='ease_out'` for smooth stop
+- For overshoot: use `easing='back_out'`
+
+### Zoom
+Scale and position for zoom effect:
+- Zoom in: scale from 0.1 to 2.0, crop center
+- Zoom out: scale from 2.0 to 1.0
+- Can add motion blur for drama (PIL filter)
+
+### Explode/Particle Burst
+Create particles radiating outward:
+- Generate particles with random angles and velocities
+- Update each particle: `x += vx`, `y += vy`
+- Add gravity: `vy += gravity_constant`
+- Fade out particles over time (reduce alpha)
+
+## Optimization Strategies
+
+Only when asked to make the file size smaller, implement a few of the following methods:
+
+1. **Fewer frames** - Lower FPS (10 instead of 20) or shorter duration
+2. **Fewer colors** - `num_colors=48` instead of 128
+3. **Smaller dimensions** - 128x128 instead of 480x480
+4. **Remove duplicates** - `remove_duplicates=True` in save()
+5. **Emoji mode** - `optimize_for_emoji=True` auto-optimizes
+
+```python
+# Maximum optimization for emoji
+builder.save(
+    'emoji.gif',
+    num_colors=48,
+    optimize_for_emoji=True,
+    remove_duplicates=True
+)
+```
+
+## Philosophy
+
+This skill provides:
+- **Knowledge**: Slack's requirements and animation concepts
+- **Utilities**: GIFBuilder, validators, easing functions
+- **Flexibility**: Create the animation logic using PIL primitives
+
+It does NOT provide:
+- Rigid animation templates or pre-made functions
+- Emoji font rendering (unreliable across platforms)
+- A library of pre-packaged graphics built into the skill
+
+**Note on user uploads**: This skill doesn't include pre-built graphics, but if a user uploads an image, use PIL to load and work with it - interpret based on their request whether they want it used directly or just as inspiration.
+
+Be creative! Combine concepts (bouncing + rotating, pulsing + sliding, etc.) and use PIL's full capabilities.
+
+## Dependencies
+
+```bash
+pip install pillow imageio numpy
+```

package/skills/snipgrapher/SKILL.md

@@ -0,0 +1,58 @@
+---
+name: snipgrapher
+description: Configures and uses snipgrapher to generate polished code snippet images, including syntax-highlighted PNGs, SVGs, and WebP exports with custom themes, profiles, and styling options. Use when the user wants to create code screenshots, turn code into shareable images, generate pretty code snippets for docs or social posts, produce syntax-highlighted images from source files, or explicitly mentions snipgrapher. Supports single-file renders, batch jobs, watch mode, and reusable named profiles via the snipgrapher CLI or npx.
+metadata:
+  tags: snipgrapher, snippets, images, svg, png, webp, cli
+---
+
+## When to use
+
+Use this skill when you need to:
+- Generate image snippets from source code
+- Configure reusable snippet rendering defaults
+- Batch-render snippet assets for docs, social posts, or changelogs
+- Use published `snipgrapher` from npm to generate snippet images
+
+## Quick start
+
+Render a single file to a PNG immediately with no config required:
+
+```bash
+npx snipgrapher render file.ts -o output.png
+```
+
+For ongoing use, initialise a project config first, then render:
+
+```bash
+npx snipgrapher init          # creates snipgrapher.config.json
+npx snipgrapher render file.ts --profile default -o output.png
+```
+
+After rendering, verify the output exists and is non-zero in size before treating the job as successful:
+
+```bash
+ls -lh output.png   # confirm file exists and size > 0
+```
+
+## How to use
+
+Read these rule files in order:
+
+- [rules/setup-and-configuration.md](rules/setup-and-configuration.md) - Install, select executable, initialize config, and define profiles
+- [rules/rendering-workflows.md](rules/rendering-workflows.md) - Render single snippets, batch jobs, watch mode, and output practices
+
+## Core principles
+
+- **Configure first**: establish a project config before repeated renders
+- **Reproducible output**: prefer named profiles and explicit output paths
+- **Portable commands**: use command patterns that work with installed binaries and `npx`
+- **Automation-friendly**: rely on CLI flags/config/env precedence intentionally
+
+## Troubleshooting common render failures
+
+If a render fails or produces an unexpected output, check for these common causes:
+
+- **Missing fonts**: ensure any custom font specified in the profile or config is installed on the system
+- **Unsupported syntax**: confirm the language/extension is supported by snipgrapher; fall back to plain text highlighting if not
+- **Empty or corrupt output**: re-run with `--verbose` (if supported) to surface error details, and verify the input file is readable and non-empty
+- **Profile not found**: run `npx snipgrapher init` to regenerate `snipgrapher.config.json` if the config file is missing or malformed