@rfxlamia/skillkit 1.1.0 → 1.2.0

package/skills/skills/humanize-docs/references/examples-gallery.md

@@ -0,0 +1,374 @@
+# Examples Gallery
+
+Before/after transformations across different document types. Use these to calibrate your transformation intensity.
+
+## Table of Contents
+
+- [Example 1: Technical Guide (Flutter Documentation)](#example-1-technical-guide-flutter-documentation)
+- [Example 2: API Documentation](#example-2-api-documentation)
+- [Example 3: README.md (Open Source Project)](#example-3-readmemd-open-source-project)
+- [Example 4: Tutorial/Onboarding](#example-4-tutorialonboarding-high-personality-ok)
+- [Example 5: Error Message Documentation](#example-5-error-message-documentation)
+- [Intensity Calibration Guide](#intensity-calibration-guide)
+- [Common Transformation Mistakes](#common-transformation-mistakes-anti-patterns)
+
+---
+
+## Example 1: Technical Guide (Flutter Documentation)
+
+### Before (AI-generated):
+
+```markdown
+## Task 2: Setup folder structure (AC: #2)
+
+**CRITICAL**: The following directory structure MUST be created exactly as specified.
+
+- [x] Create all directories as specified in "Complete Folder Structure" section
+- [x] Add `.gitkeep` files to empty directories
+- [x] Create barrel files (`auth.dart`, `home.dart`, `weather.dart`) for each feature
+
+It is important to note that failure to create the complete directory structure will result 
+in import errors and build failures in subsequent tasks.
+```
+
+### After (Humanized):
+
+```markdown
+## Setting Up the Folder Structure
+
+You need the full directory tree set up before you start coding. I know, boring, but it 
+saves headaches later.
+
+Create all the directories from the "Complete Folder Structure" section. Drop `.gitkeep` 
+files in the empty ones so Git actually tracks them. Create barrel files for each feature 
+(auth.dart, home.dart, weather.dart).
+
+Skip this and your imports will break. Not "might break" - *will* break. Don't skip this.
+```
+
+**Changes applied:**
+- ✅ Checkbox death
+- ✅ CAPS LOCK → emphasis via italics
+- ✅ "I know, boring" - acknowledge the tedium
+- ✅ Burstiness: 14 words → 16 words → 26 words → 9 words
+- ✅ "Not 'might break' - *will* break" - human emphasis pattern
+
+---
+
+## Example 2: API Documentation
+
+### Before (AI-generated):
+
+```markdown
+## Authentication Endpoint
+
+**Endpoint**: POST /api/v1/auth/login
+
+**Description**: This endpoint facilitates user authentication by validating credentials 
+and returning an access token.
+
+**Request Parameters**:
+- email (string, required): User email address
+- password (string, required): User password
+
+**Response**:
+- Success (200): Returns authentication token
+- Failure (401): Invalid credentials
+- Failure (500): Server error
+
+It is important to ensure that all requests utilize HTTPS to maintain security.
+```
+
+### After (Humanized):
+
+```markdown
+## Login Endpoint
+
+**POST** `/api/v1/auth/login`
+
+Send email + password, get back an access token. Standard stuff.
+
+**Request:**
+```json
+{
+  "email": "user@example.com",
+  "password": "your-password"
+}
+```
+
+**Response:**
+- `200` → You get a token
+- `401` → Wrong email/password
+- `500` → Something broke on our end
+
+**Important:** Use HTTPS. Please. Don't send passwords over plain HTTP, that's just asking 
+for trouble.
+```
+
+**Changes applied:**
+- ✅ "Standard stuff" - acknowledges simplicity
+- ✅ Showed actual JSON instead of describing fields
+- ✅ Vocabulary: "facilitate" → removed, "utilize" → "use"
+- ✅ Arrows instead of verbose labels
+- ✅ "that's just asking for trouble" - conversational warning
+
+---
+
+## Example 3: README.md (Open Source Project)
+
+### Before (AI-generated):
+
+```markdown
+# Project Name
+
+## Overview
+
+This project provides a comprehensive solution for X. It leverages modern technologies 
+to facilitate Y and ensure optimal Z performance.
+
+## Features
+
+The following features are currently implemented:
+
+- Feature A: Provides capability for X
+- Feature B: Enables users to perform Y
+- Feature C: Facilitates integration with Z
+
+## Installation
+
+To install this package, utilize the following command:
+
+```bash
+npm install package-name
+```
+
+Subsequently, import the package into your project:
+
+```javascript
+import { Component } from 'package-name';
+```
+
+It is important to note that this package requires Node.js version 16 or higher.
+```
+
+### After (Humanized):
+
+```markdown
+# Project Name
+
+Does X, basically. Uses Y to accomplish Z without being slow.
+
+## What it does
+
+- Feature A: Does the X thing
+- Feature B: Lets you Y
+- Feature C: Connects to Z APIs
+
+Honestly those three cover 95% of use cases.
+
+## Installation
+
+```bash
+npm install package-name
+```
+
+Then in your code:
+
+```javascript
+import { Component } from 'package-name';
+```
+
+**Requires Node 16+** (because we use modern JS features that older versions don't support)
+```
+
+**Changes applied:**
+- ✅ Killed verbose overview
+- ✅ "basically" - casual marker
+- ✅ Direct feature descriptions (no "facilitates")
+- ✅ "Honestly those three cover 95%" - adds perspective
+- ✅ Parenthetical explanation for Node requirement
+- ✅ "Then in your code:" instead of "Subsequently, import"
+
+---
+
+## Example 4: Tutorial/Onboarding (High Personality OK)
+
+### Before (AI-generated):
+
+```markdown
+## Step 3: Configure Database Connection
+
+In this step, you will configure the database connection parameters.
+
+Navigate to the configuration file and locate the database section. Modify the following 
+values according to your setup:
+
+- host: Database server address
+- port: Database server port  
+- username: Database user credentials
+- password: Database password
+
+After completing these modifications, save the file and proceed to the next step.
+```
+
+### After (Humanized):
+
+```markdown
+## Step 3: Hook Up The Database
+
+Open your config file and find the database section. Should look something like this:
+
+```yaml
+database:
+  host: localhost
+  port: 5432
+  username: ???
+  password: ???
+```
+
+Fill in your actual database info. The `???` is us being cheeky - obviously use real values.
+
+If you're running PostgreSQL locally, `localhost:5432` is probably right. If you're using 
+something else or a remote database, update accordingly.
+
+Save it. Next step.
+```
+
+**Changes applied:**
+- ✅ "Hook Up" instead of "Configure Connection"
+- ✅ "Should look something like this" - shows example immediately
+- ✅ "us being cheeky" - acknowledges the placeholder format
+- ✅ "obviously use real values" - sarcastic aside
+- ✅ Much shorter conclusion (not "save file and proceed to next step")
+
+---
+
+## Example 5: Error Message Documentation
+
+### Before (AI-generated):
+
+```markdown
+## Error Code: AUTH_001
+
+**Description**: This error indicates that authentication has failed due to invalid credentials.
+
+**Cause**: The provided username or password does not match the records in the database.
+
+**Resolution**: 
+1. Verify that the username is correct
+2. Ensure the password is entered accurately
+3. Check for case sensitivity issues
+4. Confirm account is not locked
+
+If the problem persists, contact system administrator.
+```
+
+### After (Humanized - GENTLE touch, this is error docs):
+
+```markdown
+## AUTH_001: Login Failed
+
+**What happened:** Wrong username or password.
+
+**How to fix:**
+1. Double-check your email and password (typos happen)
+2. Remember passwords are case-sensitive
+3. If you've been locked out after too many attempts, wait 15 minutes
+
+Still broken? Your account might be locked. Contact support at support@example.com
+```
+
+**Changes applied:**
+- ✅ Plain language error name
+- ✅ "What happened" instead of "Description"
+- ✅ "(typos happen)" - empathy
+- ✅ Specific timeframe for lockout (15 minutes vs vague "wait")
+- ✅ Direct contact instead of "system administrator"
+- ⚠️ Kept it relatively formal - errors need clarity
+
+---
+
+## Intensity Calibration Guide
+
+Use these examples to match transformation intensity to context:
+
+| Document Type | Intensity | Example From |
+|---------------|-----------|--------------|
+| Open source README | High | Example 3 |
+| Tutorial/Onboarding | High | Example 4 |
+| Technical guide | Medium-High | Example 1 |
+| API documentation | Medium | Example 2 |
+| Error messages | Low-Medium | Example 5 |
+| Legal/Compliance | Very Low | [Don't transform] |
+
+**Rule of thumb:**
+- Teaching/explaining → More personality OK
+- Reference/lookup → Keep it professional  
+- Safety/legal → Minimal transformation
+
+---
+
+## Common Transformation Mistakes (Anti-Patterns)
+
+### Mistake 1: Too Much Personality
+
+**Over-transformed:**
+```markdown
+OMG so you're gonna love this next part!!! 🎉 We're setting up the database and honestly 
+it's super easy, like SO easy you won't believe it!!! Just follow these steps and boom 💥 
+you're done! #blessed
+```
+
+**Right amount:**
+```markdown
+Setting up the database is pretty straightforward. Follow these steps:
+```
+
+**Problem:** Emojis, excessive enthusiasm, trying too hard.
+
+### Mistake 2: Not Enough Transformation
+
+**Under-transformed:**
+```markdown
+## Database Configuration
+
+To configure the database connection, you must update the configuration file with the 
+appropriate parameters. Please ensure all required fields are populated with correct values.
+```
+
+**Problem:** Still sounds like AI. "you must", "appropriate parameters", "please ensure"
+
+**Actually transformed:**
+```markdown
+## Database Setup
+
+Update your config file with your database connection details. All fields are required.
+```
+
+### Mistake 3: Losing Technical Precision
+
+**Wrong:**
+```markdown
+## API Rate Limits
+
+Don't call the API too much or it'll get mad at you lol. Like maybe 100 times per hour? 
+Or was it per minute? Anyway just don't spam it.
+```
+
+**Problem:** Lost actual rate limit numbers, unclear specification
+
+**Right:**
+```markdown
+## API Rate Limits
+
+**100 requests per minute, 5000 per hour.** Exceed this and you'll get 429 errors.
+
+If you need higher limits, email api@example.com with your use case.
+```
+
+**Fixed:** Kept precise numbers, added concrete error code, clear escalation path.
+
+---
+
+Use these examples as templates, not scripts. Every document is different - trust your 
+instinct on how much personality fits the context.

package/skills/skills/imagine/SKILL.md

@@ -0,0 +1,190 @@
+---
+name: imagine
+description: Prepare detailed, professional prompts for Google Imagen 3/4 image generation. Supports character, environment, and object prompts using natural language with technical photography specifications. Extensible support for multiple art styles via reference files.
+category: creative
+---
+
+# Imagine: Imagen Prompt Architect
+
+Generate detailed, professional prompts for Google Imagen 3/4 that leverage its natural language processing strengths and technical parameter understanding.
+
+## Core Prompt Structure
+
+Imagen uses a **Subject-Context-Style framework** powered by T5-XXL language models. Build prompts in three layers:
+
+1. **Subject**: Primary focus (person, object, animal, scenery)
+2. **Context**: Environment, placement, background, setting
+3. **Style**: Aesthetic approach (photographic, artistic, specific technique)
+
+### Photography Prompts Pattern
+
+Start with explicit photography signals: `"A photo of [detailed subject description], [context/placement], [technical specifications]"`
+
+**Technical specifications include:**
+- Lens type: 24-85mm (portraits), 60-105mm macro (products), 10-24mm wide-angle (landscapes)
+- Lighting: natural light, studio lighting, golden hour, dramatic lighting
+- Quality modifiers: sharp focus, high detail, professional photography, 8K resolution
+- Camera/equipment: shot on ARRI Alexa, 35mm film, DSLR
+
+**Example**: `"A photo of an elderly woman with weathered hands holding a steaming cup of tea, soft sunlight highlighting her wrinkles and smile, 35mm lens, warm and intimate mood, natural outdoor setting, sharp focus, professional portrait photography"`
+
+### Artistic/Stylized Prompts Pattern
+
+For non-photographic styles, read the relevant artstyle reference file first, then layer:
+
+**Foundation**: `"[Art style name] aesthetic, [medium/technique], [key visual characteristics]"`
+
+**Character/Subject**: Specific features, proportions, design elements
+
+**Environment**: Scene composition, spatial elements, atmospheric details  
+
+**Atmosphere**: Mood, color palette, lighting approach
+
+**Technical**: Rendering specifics, texture, quality markers
+
+## Using Artstyle References
+
+### Step 1: List Available Artstyles
+
+**Before creating any artistic/stylized prompts, ALWAYS list available artstyle files:**
+
+Use bash to check: `ls /mnt/skills/user/imagine/references/artstyle-*.md`
+
+This returns all available artstyle reference files. Present the list to the user so they can choose, or intelligently select based on their request.
+
+### Step 2: Read the Selected Artstyle Reference
+
+**Once an artstyle is selected (either by user or inferred from request):**
+
+1. Read the complete `references/artstyle-[name].md` file to understand the visual language
+2. Apply the layered prompting strategy from the reference
+3. Use the technical descriptors provided for style-specific characteristics
+4. Follow the style-specific guidelines and vocabulary from the reference
+
+### Artstyle File Naming Convention
+
+All artstyle references follow the pattern: `artstyle-[name].md`
+
+Examples:
+- `artstyle-sciencesaru.md` - Science SARU animation style
+- `artstyle-corporate-memphis.md` - Corporate Memphis/Alegria style
+- `artstyle-crewdson-hyperrealism.md` - Gregory Crewdson cinematic hyperrealism
+- `artstyle-iphone-social-media.md` - Modern iPhone social media aesthetic
+
+### When No Artstyle is Specified
+
+If the user doesn't specify an artstyle and their request seems to need one:
+1. List available artstyles
+2. Ask which style they prefer, or suggest the most appropriate based on context
+3. Never assume a default artstyle
+
+For pure photography requests without artistic styling, proceed without reading artstyle references.
+
+## Best Practices from Imagen Architecture
+
+### Natural Language Advantage
+- Write detailed descriptive sentences, not keyword lists
+- Imagen rewards verbose descriptions over brevity
+- Use professional creative brief language
+- Default enhancePrompt=true automatically optimizes your prose
+
+### Iterative Refinement
+Start simple, layer details progressively:
+1. Base: `"A cat"`
+2. Add specifics: `"A fluffy Persian cat with bright blue eyes"`
+3. Add context: `"...sitting on a velvet cushion in a sunlit room"`
+4. Add technical: `"A photo of a fluffy Persian cat with bright blue eyes, sitting on a velvet cushion in a sunlit room, 50mm lens, natural soft lighting, warm colors, professional pet photography"`
+
+### Critical Constraints
+- **Text-in-image**: Maximum 25 characters per phrase, 3 phrases total
+- **Negative prompts**: Use plain descriptive terms ("wall, frame") not instructive language ("no walls, without frame")
+- **Token limit**: 480 tokens for prompt text
+
+### Technical Parameters
+**Aspect ratios** (match use case):
+- 1:1 - Square social media
+- 3:4 - Portrait ads, vertical social
+- 4:3 - Traditional photography, TV
+- 16:9 - Widescreen landscape, modern displays
+- 9:16 - Vertical video, tall subjects
+
+**Safety/person controls**: Adjust personGeneration (allow_adult, allow_all, dont_allow) and safetySetting (block_low_and_above, block_medium_and_above, block_only_high, block_none) as needed
+
+## Practical Use Case Patterns
+
+### Character/Portrait
+`"Portrait of [character description with age, features, clothing, emotion], [lens specification 24-85mm], [lighting type], [mood descriptors], [setting], [quality modifiers]"`
+
+**For styled characters**: Read appropriate artstyle reference for character design specifics (proportions, features, design language)
+
+### Environment/Landscape  
+`"[Environment type], [weather/time/season], [lens specification 10-24mm wide-angle], [atmospheric conditions], [quality modifiers]"`
+
+**For styled environments**: Read appropriate artstyle reference for environment treatment (composition, color theory, architectural approach)
+
+### Product/Object
+`"[Product] on [surface], [lens specification 60-105mm macro], [lighting type], [background type], [material/texture details], [quality modifiers]"`
+
+### Cinematic/Stylized
+`"[Animation/art style], [scene description], [color grading approach], [cinematography terms], [atmospheric effects]"`
+
+**For cinematic styles**: Read appropriate artstyle reference for cinematic specifics (camera work, lighting philosophy, emotional coding)
+
+## Workflow for Creating Prompts
+
+1. **Determine type**: Photography, artistic style, or hybrid?
+2. **If using art style**: 
+   - List available artstyles: `ls /mnt/skills/user/imagine/references/artstyle-*.md`
+   - Select appropriate style (by user choice or inference)
+   - Read complete `references/artstyle-[name].md` file
+3. **Build foundation**: Establish subject clearly and early
+4. **Layer context**: Add environment, placement, spatial relationships
+5. **Specify style**: Include aesthetic approach with technical vocabulary from reference (if using artstyle)
+6. **Add technical specs**: Lens type, lighting, quality modifiers appropriate to subject
+7. **Refine iteratively**: Start simple, add detail progressively until satisfied
+8. **Validate constraints**: Check text-in-image limits, negative prompt format, token count
+
+## Example Complete Prompts
+
+### Photography Example
+`"A photo of a plate of traditional Indonesian nasi goreng with fried egg on top, colorful vegetables visible, served on rustic ceramic plate on wooden table, 100mm macro lens, natural window lighting from side, warm atmosphere, steam rising from rice, glistening sauce, high detail, professional food photography, appetizing composition"`
+
+### Artistic Style Example (Generic Template)
+`"[Artstyle name] aesthetic, [medium/technique]. [Character description following style's design principles], [character-specific features from artstyle reference]. [Environment description following style's composition approach], [environmental specifics from artstyle reference]. [Atmospheric qualities from style guide], [color and lighting approach from reference]. [Technical rendering specs from style guide], [texture and quality markers from reference]"`
+
+**Note**: The actual artistic prompt should be built by reading the specific artstyle reference file and applying its guidelines. See individual artstyle-*.md files for complete examples.
+
+### Hybrid Example (Styled character, photographic background)
+`"A photo of [character description in chosen art style], standing on actual [real environment], 35mm lens, golden hour natural lighting, real background with stylized character overlay, professional photography with [art style] integration, warm atmospheric lighting, high detail background with stylized character"`
+
+## Tips for Quality Output
+
+- **Be specific with materials and textures**: "glistening sauce," "rough ceramic," "polished wood" guide fine detail
+- **Use cinematography vocabulary**: "shot on ARRI Alexa," "Summilux lens," "volumetric lighting" elevate professional quality  
+- **Time of day matters**: Golden hour, overcast, midday sun, twilight each create distinct lighting and mood
+- **Color grading terms**: "muted cold tones," "warm sepia," "desaturated," "high contrast" specify aesthetic precisely
+- **Atmospheric effects**: "misty," "foggy," "heat haze," "rain-soaked" add environmental depth
+
+## Extensibility
+
+This skill is designed to grow with your needs:
+- Add new `artstyle-[name].md` files to `references/` for different visual styles
+- Follow consistent documentation structure from existing artstyle files
+- Always list available artstyles at the start of artistic prompt workflows
+- Each artstyle reference should provide:
+  - Visual DNA and core characteristics
+  - Technical prompting vocabulary
+  - Layered prompting strategy
+  - Complete example prompts
+  - Style-specific guidelines for characters, environments, lighting, composition
+
+## Adding New Artstyles
+
+To add a new artstyle:
+1. Create `references/artstyle-[name].md`
+2. Document the style's visual characteristics comprehensively
+3. Provide AI prompting vocabulary and technical descriptors
+4. Include layered prompting strategy and complete examples
+5. The skill will automatically detect and list it when checking available artstyles
+
+No code changes needed - the skill dynamically discovers all artstyle-*.md files in the references directory.