├── .gitignore ├── .gitmodules ├── skills ├── article-writer │ ├── references │ │ ├── writing-guidelines.md │ │ ├── style-guide.md │ │ └── example-article.md │ ├── scripts │ │ └── check_style.py │ └── SKILL.md ├── skill-creator │ ├── scripts │ │ ├── quick_validate.py │ │ ├── package_skill.py │ │ └── init_skill.py │ ├── LICENSE.txt │ └── SKILL.md ├── vim-ai-config │ ├── file-paths.md │ ├── SKILL.md │ ├── documentation-sources.md │ └── quick-reference.md ├── algorithmic-art │ ├── templates │ │ ├── generator_template.js │ │ └── viewer.html │ ├── LICENSE.txt │ ├── SKILL.md │ └── resonant_echoes.html ├── wezterm-config │ └── SKILL.md └── aerospace-config │ └── SKILL.md ├── .claude-plugin └── marketplace.json └── README.md /.gitignore: -------------------------------------------------------------------------------- 1 | # macOS 2 | .DS_Store 3 | 4 | # Python 5 | __pycache__/ 6 | *.py[cod] 7 | *$py.class 8 | .Python 9 | *.so 10 | 11 | # IDE 12 | .idea/ 13 | .vscode/ 14 | *.swp 15 | *.swo 16 | 17 | # Temporary files 18 | *.tmp 19 | *.temp 20 | -------------------------------------------------------------------------------- /.gitmodules: -------------------------------------------------------------------------------- 1 | [submodule "skills/cc-trace"] 2 | path = skills/cc-trace 3 | url = https://github.com/alexfazio/cc-trace.git 4 | [submodule "skills/artificial-analysis-compare"] 5 | path = skills/artificial-analysis-compare 6 | url = https://github.com/alexfazio/artificial-analysis-compare.git 7 | -------------------------------------------------------------------------------- /skills/article-writer/references/writing-guidelines.md: -------------------------------------------------------------------------------- 1 | ## Guideline: Avoid Empty Framing Phrases 2 | 3 | Don’t use phrases like: 4 | • “But here’s the reality:” 5 | • “Here’s the thing:” 6 | • “The point:” 7 | 8 | These are discourse markers / framing phrases. They don’t add real information; they just announce that something important is about to be said. In other words, they’re metadiscourse: language about the structure of what you’re saying, not the substance. 9 | 10 | They tend to: 11 | • Waste space and weaken impact 12 | • Sound conversational or cliched rather than clear and direct 13 | • Delay the actual point 14 | 15 | Preferred approach: 16 | State the point directly and concretely, without a lead-in. For example, instead of: 17 | 18 | “Here’s the thing: our costs are too high.” 19 | 20 | Write: 21 | 22 | “Our costs are too high.”**The point:**` 23 | 24 | ## Guideline: Do Not Use Em Dashes 25 | 26 | Writers should avoid using em dashes (—) in all documents. 27 | 28 | An em dash is a long horizontal mark often used to interrupt a sentence, add an aside, or create dramatic pauses. It is informal, visually noisy, and easy to overuse. The result is writing that feels jumpy and less precise. 29 | -------------------------------------------------------------------------------- /.claude-plugin/marketplace.json: -------------------------------------------------------------------------------- 1 | { 2 | "name": "cc-skills", 3 | "owner": { 4 | "name": "Alex Fazio", 5 | "email": "alex@alexfazio.dev" 6 | }, 7 | "metadata": { 8 | "description": "Custom skills for Claude Code by Alex Fazio", 9 | "version": "1.0.0" 10 | }, 11 | "plugins": [ 12 | { 13 | "name": "dev-tools", 14 | "description": "Development environment configuration skills for AeroSpace, WezTerm, and vim-ai", 15 | "source": "./", 16 | "strict": false, 17 | "skills": [ 18 | "./skills/aerospace-config", 19 | "./skills/wezterm-config", 20 | "./skills/vim-ai-config" 21 | ] 22 | }, 23 | { 24 | "name": "creative-tools", 25 | "description": "Creative and content skills for algorithmic art and technical writing", 26 | "source": "./", 27 | "strict": false, 28 | "skills": [ 29 | "./skills/algorithmic-art", 30 | "./skills/article-writer" 31 | ] 32 | }, 33 | { 34 | "name": "skill-creator", 35 | "description": "Meta-skill for creating new Claude Code skills", 36 | "source": "./", 37 | "strict": false, 38 | "skills": [ 39 | "./skills/skill-creator" 40 | ] 41 | } 42 | ] 43 | } 44 | -------------------------------------------------------------------------------- /skills/skill-creator/scripts/quick_validate.py: -------------------------------------------------------------------------------- 1 | #!/usr/bin/env python3 2 | """ 3 | Quick validation script for skills - minimal version 4 | """ 5 | 6 | import sys 7 | import os 8 | import re 9 | from pathlib import Path 10 | 11 | def validate_skill(skill_path): 12 | """Basic validation of a skill""" 13 | skill_path = Path(skill_path) 14 | 15 | # Check SKILL.md exists 16 | skill_md = skill_path / 'SKILL.md' 17 | if not skill_md.exists(): 18 | return False, "SKILL.md not found" 19 | 20 | # Read and validate frontmatter 21 | content = skill_md.read_text() 22 | if not content.startswith('---'): 23 | return False, "No YAML frontmatter found" 24 | 25 | # Extract frontmatter 26 | match = re.match(r'^---\n(.*?)\n---', content, re.DOTALL) 27 | if not match: 28 | return False, "Invalid frontmatter format" 29 | 30 | frontmatter = match.group(1) 31 | 32 | # Check required fields 33 | if 'name:' not in frontmatter: 34 | return False, "Missing 'name' in frontmatter" 35 | if 'description:' not in frontmatter: 36 | return False, "Missing 'description' in frontmatter" 37 | 38 | # Extract name for validation 39 | name_match = re.search(r'name:\s*(.+)', frontmatter) 40 | if name_match: 41 | name = name_match.group(1).strip() 42 | # Check naming convention (hyphen-case: lowercase with hyphens) 43 | if not re.match(r'^[a-z0-9-]+$', name): 44 | return False, f"Name '{name}' should be hyphen-case (lowercase letters, digits, and hyphens only)" 45 | if name.startswith('-') or name.endswith('-') or '--' in name: 46 | return False, f"Name '{name}' cannot start/end with hyphen or contain consecutive hyphens" 47 | 48 | # Extract and validate description 49 | desc_match = re.search(r'description:\s*(.+)', frontmatter) 50 | if desc_match: 51 | description = desc_match.group(1).strip() 52 | # Check for angle brackets 53 | if '<' in description or '>' in description: 54 | return False, "Description cannot contain angle brackets (< or >)" 55 | 56 | return True, "Skill is valid!" 57 | 58 | if __name__ == "__main__": 59 | if len(sys.argv) != 2: 60 | print("Usage: python quick_validate.py ") 61 | sys.exit(1) 62 | 63 | valid, message = validate_skill(sys.argv[1]) 64 | print(message) 65 | sys.exit(0 if valid else 1) -------------------------------------------------------------------------------- /skills/vim-ai-config/file-paths.md: -------------------------------------------------------------------------------- 1 | # vim-ai Configuration File Paths 2 | 3 | This document lists all file paths for vim-ai configuration. Always verify these paths exist before attempting modifications. 4 | 5 | ## Primary Configuration Files 6 | 7 | ### Vim Configuration 8 | - **Vim**: `~/.vimrc` 9 | - **Neovim**: `~/.config/nvim/init.vim` or `~/.config/nvim/init.lua` 10 | 11 | **Purpose**: Contains vim-ai plugin settings, model configurations, API endpoint settings, keyboard mappings, and UI preferences. 12 | 13 | ### API Key Storage 14 | - **Default location**: `~/.config/openai.token` 15 | - **Custom location**: Defined by `g:vim_ai_token_file_path` in vimrc 16 | 17 | **Purpose**: Stores OpenAI API key (or other provider keys). Should have 600 permissions for security. 18 | 19 | ### Custom Roles Configuration 20 | - **Default location**: `~/.vim/vim-ai-roles.ini` (Vim) or `~/.config/nvim/vim-ai-roles.ini` (Neovim) 21 | - **Custom location**: Defined by `g:vim_ai_roles_config_file` in vimrc 22 | 23 | **Purpose**: Contains custom roles (reusable prompts) for specific tasks like code review, documentation, testing, etc. 24 | 25 | ## Plugin Installation Paths 26 | 27 | ### Vim (using native packages) 28 | - **Installation path**: `~/.vim/pack/plugins/start/vim-ai/` 29 | - **Plugin files**: Contains the vim-ai plugin source code 30 | 31 | ### Neovim (using native packages) 32 | - **Installation path**: `~/.local/share/nvim/site/pack/plugins/start/vim-ai/` 33 | - **Alternative**: `~/.config/nvim/pack/plugins/start/vim-ai/` 34 | 35 | ### Package Manager Paths 36 | - **vim-plug**: Defined by `plug#begin()` call in vimrc (commonly `~/.vim/plugged/vim-ai/`) 37 | - **Packer.nvim**: `~/.local/share/nvim/site/pack/packer/start/vim-ai/` 38 | - **Lazy.nvim**: `~/.local/share/nvim/lazy/vim-ai/` 39 | 40 | ## Configuration File Formats 41 | 42 | ### .vimrc / init.vim Settings 43 | Format: Vimscript with `let g:vim_ai_*` variables 44 | 45 | ### init.lua Settings 46 | Format: Lua configuration with `vim.g.vim_ai_*` variables 47 | 48 | ### Roles Configuration (.ini) 49 | Format: INI file with `[role-name]` sections and `prompt=` keys 50 | 51 | ## How to Determine Current Setup 52 | 53 | 1. **Check which editor**: Ask user if they use Vim or Neovim 54 | 2. **Check config file location**: 55 | - Vim: `test -f ~/.vimrc && echo "exists"` 56 | - Neovim: `test -f ~/.config/nvim/init.vim && echo "exists"` or check for `init.lua` 57 | 3. **Check plugin installation**: Look in the paths above based on installation method 58 | 4. **Check custom paths**: Read vimrc to find `g:vim_ai_token_file_path` and `g:vim_ai_roles_config_file` 59 | 60 | ## User-Specific Paths 61 | 62 | The current user's paths based on installation: 63 | - Vim config: `~/.vimrc` 64 | - Plugin path: `~/.vim/pack/plugins/start/vim-ai/` 65 | - API key: `~/.config/openai.token` 66 | - Custom roles: `~/.vim/vim-ai-roles.ini` 67 | - Homebrew vim: `/opt/homebrew/bin/vim` 68 | 69 | Always verify these paths exist before making changes. 70 | -------------------------------------------------------------------------------- /skills/vim-ai-config/SKILL.md: -------------------------------------------------------------------------------- 1 | --- 2 | name: vim-ai-config 3 | description: Manage vim-ai plugin configuration files including .vimrc settings, custom roles, API keys, and model configurations. Use when user requests help with vim-ai setup, modifying vim-ai behavior, adding custom roles, changing AI models, updating prompts, or troubleshooting vim-ai issues. 4 | --- 5 | 6 | # vim-ai Configuration Management Skill 7 | 8 | This skill helps you manage and configure the vim-ai plugin for Vim/Neovim. 9 | 10 | ## What This Skill Does 11 | 12 | This skill provides guidance and assistance for: 13 | - Modifying vim-ai configuration in `.vimrc` or `init.vim` 14 | - Managing custom roles in the roles configuration file 15 | - Updating API keys and authentication settings 16 | - Configuring AI models, endpoints, and parameters 17 | - Customizing vim-ai UI and behavior 18 | - Creating keyboard shortcuts and mappings 19 | - Troubleshooting vim-ai issues 20 | 21 | ## Key Configuration Files 22 | 23 | All configuration files are located on the user's system. Reference the [file paths documentation](file-paths.md) to locate the exact files to modify based on the user's request. 24 | 25 | ## How to Use This Skill 26 | 27 | 1. **Identify the user's goal** - What aspect of vim-ai do they want to configure? 28 | 2. **Locate the relevant file** - Use [file-paths.md](file-paths.md) to find which file needs to be modified 29 | 3. **Fetch current documentation** - Use [documentation-sources.md](documentation-sources.md) to get the latest vim-ai documentation 30 | 4. **Read the current configuration** - Always read the existing file before making changes 31 | 5. **Make targeted modifications** - Edit only what's necessary, preserving existing settings 32 | 6. **Test and verify** - Confirm changes work as expected 33 | 34 | ## Important Principles 35 | 36 | - **Always read before writing**: Check current configuration before making changes 37 | - **Preserve existing settings**: Don't overwrite unrelated configurations 38 | - **Use official documentation**: Fetch latest docs from sources in [documentation-sources.md](documentation-sources.md) 39 | - **Verify paths**: Confirm files exist at locations specified in [file-paths.md](file-paths.md) 40 | - **Test changes**: Help user verify modifications work correctly 41 | 42 | ## Workflow Steps 43 | 44 | 1. Read [file-paths.md](file-paths.md) to determine which files need modification 45 | 2. Use WebFetch to get current vim-ai documentation from [documentation-sources.md](documentation-sources.md) 46 | 3. Read the existing configuration files using the Read tool 47 | 4. Make precise edits using the Edit tool (never overwrite entire files unnecessarily) 48 | 5. Document what was changed and why 49 | 6. Provide testing instructions 50 | 51 | ## Examples of What You Can Help With 52 | 53 | - "Add a custom role for code review to vim-ai" 54 | - "Change vim-ai to use GPT-4 instead of GPT-3.5" 55 | - "Update my OpenAI API key for vim-ai" 56 | - "Create a keyboard shortcut for AI chat in vim" 57 | - "Configure vim-ai to use a different temperature setting" 58 | - "Set up vim-ai to work with a local AI endpoint" 59 | - "Fix vim-ai not loading in Neovim" 60 | 61 | ## Next Steps 62 | 63 | When helping users, always: 64 | 1. Consult [file-paths.md](file-paths.md) for file locations 65 | 2. Check [documentation-sources.md](documentation-sources.md) for current vim-ai documentation URLs 66 | 3. Read existing files before making changes 67 | 4. Use targeted edits rather than complete rewrites 68 | -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 | # cc-skills 2 | 3 | A collection of custom skills for [Claude Code](https://docs.anthropic.com/en/docs/claude-code), Anthropic's agentic coding tool. 4 | 5 | ## What are Skills? 6 | 7 | Skills are folders of instructions, scripts, and resources that Claude loads dynamically to improve performance on specialized tasks. They teach Claude how to complete specific tasks in a repeatable way. 8 | 9 | For more information, see: 10 | - [What are skills?](https://support.anthropic.com/en/articles/12512176-what-are-skills) 11 | - [Using skills in Claude](https://support.anthropic.com/en/articles/12512180-using-skills-in-claude) 12 | - [Creating custom skills](https://support.anthropic.com/en/articles/12512198-creating-custom-skills) 13 | 14 | ## Installation 15 | 16 | ### Option 1: Install as Plugin Marketplace (Recommended) 17 | 18 | Add this repository as a Claude Code plugin marketplace: 19 | 20 | ```bash 21 | /plugin marketplace add alexfazio/cc-skills 22 | ``` 23 | 24 | Then browse and install individual skills: 25 | 26 | ```bash 27 | /plugin install 28 | ``` 29 | 30 | ### Option 2: Manual Installation 31 | 32 | Copy individual skill folders to your Claude Code skills directory: 33 | 34 | ```bash 35 | cp -R skills/aerospace-config ~/.claude/skills/ 36 | ``` 37 | 38 | ## Available Skills 39 | 40 | | Skill | Description | 41 | |-------|-------------| 42 | | [aerospace-config](skills/aerospace-config/) | Complete AeroSpace tiling window manager configuration assistant for macOS. Handles keybindings, workspace management, window rules, layouts, and debugging. | 43 | | [algorithmic-art](skills/algorithmic-art/) | Create algorithmic art using p5.js with seeded randomness and interactive parameter exploration. Generates original generative art, flow fields, and particle systems. | 44 | | [article-writer](skills/article-writer/) | Edit and refine blog articles and technical posts with a conversational, direct style. Includes automated style checking and strict guidelines. | 45 | | [cc-trace](skills/cc-trace/) | Interactive assistant for intercepting and analyzing Claude Code API requests using mitmproxy. *(Git submodule - see [alexfazio/cc-trace](https://github.com/alexfazio/cc-trace))* | 46 | | [skill-creator](skills/skill-creator/) | Guide for creating effective skills. Use when building new skills or updating existing ones. | 47 | | [vim-ai-config](skills/vim-ai-config/) | Manage vim-ai plugin configuration including .vimrc settings, custom roles, API keys, and model configurations. | 48 | | [wezterm-config](skills/wezterm-config/) | Complete WezTerm terminal emulator configuration assistant. Handles appearance, fonts, keybindings, SSH domains, multiplexing, and Lua scripting. | 49 | 50 | ## Skill Structure 51 | 52 | Each skill follows this structure: 53 | 54 | ``` 55 | skill-name/ 56 | ├── SKILL.md # Required: Instructions and metadata 57 | ├── scripts/ # Optional: Executable code 58 | ├── references/ # Optional: Documentation loaded as needed 59 | └── assets/ # Optional: Templates, images, etc. 60 | ``` 61 | 62 | ## Related Projects 63 | 64 | - **[cc-trace](https://github.com/alexfazio/cc-trace)** - Claude Code API request interception and analysis tool (included as submodule) 65 | 66 | ## Contributing 67 | 68 | Contributions welcome! To add a new skill: 69 | 70 | 1. Create a new folder in `skills/` 71 | 2. Add a `SKILL.md` with proper YAML frontmatter 72 | 3. Include any scripts, references, or assets 73 | 4. Submit a pull request 74 | 75 | ## License 76 | 77 | Individual skills may have their own licenses. See each skill's directory for details. 78 | -------------------------------------------------------------------------------- /skills/skill-creator/scripts/package_skill.py: -------------------------------------------------------------------------------- 1 | #!/usr/bin/env python3 2 | """ 3 | Skill Packager - Creates a distributable zip file of a skill folder 4 | 5 | Usage: 6 | python utils/package_skill.py [output-directory] 7 | 8 | Example: 9 | python utils/package_skill.py skills/public/my-skill 10 | python utils/package_skill.py skills/public/my-skill ./dist 11 | """ 12 | 13 | import sys 14 | import zipfile 15 | from pathlib import Path 16 | from quick_validate import validate_skill 17 | 18 | 19 | def package_skill(skill_path, output_dir=None): 20 | """ 21 | Package a skill folder into a zip file. 22 | 23 | Args: 24 | skill_path: Path to the skill folder 25 | output_dir: Optional output directory for the zip file (defaults to current directory) 26 | 27 | Returns: 28 | Path to the created zip file, or None if error 29 | """ 30 | skill_path = Path(skill_path).resolve() 31 | 32 | # Validate skill folder exists 33 | if not skill_path.exists(): 34 | print(f"❌ Error: Skill folder not found: {skill_path}") 35 | return None 36 | 37 | if not skill_path.is_dir(): 38 | print(f"❌ Error: Path is not a directory: {skill_path}") 39 | return None 40 | 41 | # Validate SKILL.md exists 42 | skill_md = skill_path / "SKILL.md" 43 | if not skill_md.exists(): 44 | print(f"❌ Error: SKILL.md not found in {skill_path}") 45 | return None 46 | 47 | # Run validation before packaging 48 | print("🔍 Validating skill...") 49 | valid, message = validate_skill(skill_path) 50 | if not valid: 51 | print(f"❌ Validation failed: {message}") 52 | print(" Please fix the validation errors before packaging.") 53 | return None 54 | print(f"✅ {message}\n") 55 | 56 | # Determine output location 57 | skill_name = skill_path.name 58 | if output_dir: 59 | output_path = Path(output_dir).resolve() 60 | output_path.mkdir(parents=True, exist_ok=True) 61 | else: 62 | output_path = Path.cwd() 63 | 64 | zip_filename = output_path / f"{skill_name}.zip" 65 | 66 | # Create the zip file 67 | try: 68 | with zipfile.ZipFile(zip_filename, 'w', zipfile.ZIP_DEFLATED) as zipf: 69 | # Walk through the skill directory 70 | for file_path in skill_path.rglob('*'): 71 | if file_path.is_file(): 72 | # Calculate the relative path within the zip 73 | arcname = file_path.relative_to(skill_path.parent) 74 | zipf.write(file_path, arcname) 75 | print(f" Added: {arcname}") 76 | 77 | print(f"\n✅ Successfully packaged skill to: {zip_filename}") 78 | return zip_filename 79 | 80 | except Exception as e: 81 | print(f"❌ Error creating zip file: {e}") 82 | return None 83 | 84 | 85 | def main(): 86 | if len(sys.argv) < 2: 87 | print("Usage: python utils/package_skill.py [output-directory]") 88 | print("\nExample:") 89 | print(" python utils/package_skill.py skills/public/my-skill") 90 | print(" python utils/package_skill.py skills/public/my-skill ./dist") 91 | sys.exit(1) 92 | 93 | skill_path = sys.argv[1] 94 | output_dir = sys.argv[2] if len(sys.argv) > 2 else None 95 | 96 | print(f"📦 Packaging skill: {skill_path}") 97 | if output_dir: 98 | print(f" Output directory: {output_dir}") 99 | print() 100 | 101 | result = package_skill(skill_path, output_dir) 102 | 103 | if result: 104 | sys.exit(0) 105 | else: 106 | sys.exit(1) 107 | 108 | 109 | if __name__ == "__main__": 110 | main() 111 | -------------------------------------------------------------------------------- /skills/vim-ai-config/documentation-sources.md: -------------------------------------------------------------------------------- 1 | # vim-ai Documentation Sources 2 | 3 | This document provides URLs to fetch the latest vim-ai plugin documentation. Always fetch fresh documentation using WebFetch rather than relying on cached or copied content. 4 | 5 | ## Official Documentation 6 | 7 | ### Primary GitHub Repository 8 | - **URL**: `https://github.com/madox2/vim-ai` 9 | - **Contains**: Complete README with installation, configuration, usage examples 10 | - **Use for**: Installation instructions, basic configuration, troubleshooting 11 | 12 | ### README.md 13 | - **URL**: `https://raw.githubusercontent.com/madox2/vim-ai/master/README.md` 14 | - **Contains**: Full documentation in markdown format 15 | - **Use for**: Quick reference, configuration examples, command syntax 16 | 17 | ## Configuration Examples 18 | 19 | ### Default Roles File 20 | - **URL**: `https://raw.githubusercontent.com/madox2/vim-ai/master/roles-default.ini` 21 | - **Contains**: Built-in default roles provided by the plugin 22 | - **Use for**: Understanding role syntax, finding default roles 23 | 24 | ### Example Roles File 25 | - **URL**: `https://raw.githubusercontent.com/madox2/vim-ai/master/roles-example.ini` 26 | - **Contains**: Additional example roles for inspiration 27 | - **Use for**: Creating custom roles, advanced role configurations 28 | 29 | ## Help Documentation 30 | 31 | ### Vim Help Files 32 | - **Location**: `~/.vim/pack/plugins/start/vim-ai/doc/vim-ai.txt` (after installation) 33 | - **Access in Vim**: `:help vim-ai` 34 | - **Contains**: Complete plugin documentation viewable in Vim 35 | - **Use for**: Detailed configuration options, command reference 36 | 37 | ## Source Code References 38 | 39 | ### Python Implementation 40 | - **Directory**: `https://github.com/madox2/vim-ai/tree/master/py` 41 | - **Contains**: Python source code for AI interactions 42 | - **Use for**: Understanding how the plugin works, debugging issues 43 | 44 | ### Plugin Configuration 45 | - **File**: `https://github.com/madox2/vim-ai/blob/master/plugin/vim-ai.vim` 46 | - **Contains**: Plugin initialization and default settings 47 | - **Use for**: Understanding default configurations, available options 48 | 49 | ## How to Fetch Documentation 50 | 51 | ### Using WebFetch 52 | ``` 53 | WebFetch the URL with a specific prompt about what information you need 54 | ``` 55 | 56 | ### Example Queries 57 | - "How to configure custom AI models" → Fetch main README 58 | - "How to create custom roles" → Fetch roles-example.ini 59 | - "What are all available configuration options" → Fetch README and help docs 60 | - "How to change the API endpoint" → Fetch README configuration section 61 | 62 | ## Key Configuration Sections to Reference 63 | 64 | When helping users, fetch the relevant section from the README: 65 | 66 | 1. **Installation**: How to install the plugin 67 | 2. **Configuration**: Available `g:vim_ai_*` options 68 | 3. **Commands**: `:AI`, `:AIEdit`, `:AIChat`, etc. 69 | 4. **Key Mappings**: How to set up keyboard shortcuts 70 | 5. **Custom Roles**: How to define reusable prompts 71 | 6. **API Configuration**: Setting up API keys and endpoints 72 | 7. **Model Configuration**: Changing AI models and parameters 73 | 74 | ## Important Notes 75 | 76 | - Always fetch documentation fresh rather than using cached versions 77 | - The main README is the authoritative source for current features 78 | - Check the GitHub issues page for known problems: `https://github.com/madox2/vim-ai/issues` 79 | - For version-specific features, check the releases page: `https://github.com/madox2/vim-ai/releases` 80 | 81 | ## Alternative AI Providers 82 | 83 | The plugin supports OpenAI-compatible endpoints. Check the README for: 84 | - Azure OpenAI configuration 85 | - Local AI models (like Ollama, LM Studio) 86 | - Other OpenAI-compatible APIs 87 | 88 | Fetch the relevant sections from the README when users ask about these alternatives. 89 | -------------------------------------------------------------------------------- /skills/vim-ai-config/quick-reference.md: -------------------------------------------------------------------------------- 1 | # vim-ai Quick Reference Guide 2 | 3 | This guide provides quick patterns for common vim-ai configuration tasks. 4 | 5 | ## Common Configuration Tasks 6 | 7 | ### 1. Adding a Custom Role 8 | 9 | **File to modify**: `~/.vim/vim-ai-roles.ini` (check [file-paths.md](file-paths.md) for exact location) 10 | 11 | **Pattern**: 12 | ```ini 13 | [role-name] 14 | prompt=Your instruction here 15 | ``` 16 | 17 | **Steps**: 18 | 1. Read the current roles file 19 | 2. Use Edit tool to append new role 20 | 3. Verify role name is unique 21 | 4. Test with `:AI /role-name` 22 | 23 | ### 2. Changing AI Model 24 | 25 | **File to modify**: `~/.vimrc` (check [file-paths.md](file-paths.md)) 26 | 27 | **Configuration section**: Look for `g:vim_ai_chat`, `g:vim_ai_edit`, or `g:vim_ai_complete` 28 | 29 | **Steps**: 30 | 1. Fetch current model options from README 31 | 2. Read existing vimrc 32 | 3. Edit the `"model"` value in the appropriate section 33 | 4. Restart Vim to apply changes 34 | 35 | ### 3. Updating API Key 36 | 37 | **File to modify**: `~/.config/openai.token` (or custom path in vimrc) 38 | 39 | **Steps**: 40 | 1. Check vimrc for `g:vim_ai_token_file_path` (if set) 41 | 2. Write new API key to the token file 42 | 3. Ensure file has 600 permissions: `chmod 600 ~/.config/openai.token` 43 | 4. No Vim restart needed for key updates 44 | 45 | ### 4. Adding Keyboard Shortcuts 46 | 47 | **File to modify**: `~/.vimrc` 48 | 49 | **Pattern for normal mode**: 50 | ```vim 51 | nnoremap x :AICommand 52 | ``` 53 | 54 | **Pattern for visual mode**: 55 | ```vim 56 | xnoremap x :AICommand 57 | ``` 58 | 59 | **Steps**: 60 | 1. Read existing vimrc 61 | 2. Find keybindings section (or create one) 62 | 3. Add new mapping without conflicting with existing keys 63 | 4. Restart Vim or source config: `:source ~/.vimrc` 64 | 65 | ### 5. Configuring Custom Endpoint 66 | 67 | **File to modify**: `~/.vimrc` 68 | 69 | **Section to edit**: `g:vim_ai_chat["options"]["endpoint_url"]` 70 | 71 | **Steps**: 72 | 1. Fetch endpoint documentation for the provider 73 | 2. Read current vimrc configuration 74 | 3. Update `endpoint_url` value 75 | 4. May need to adjust authentication settings 76 | 5. Test connection 77 | 78 | ### 6. Adjusting Temperature/Parameters 79 | 80 | **File to modify**: `~/.vimrc` 81 | 82 | **Common parameters**: 83 | - `temperature`: 0.0-2.0 (creativity level) 84 | - `max_tokens`: Response length limit 85 | - `request_timeout`: Seconds before timeout 86 | 87 | **Steps**: 88 | 1. Read current parameter values 89 | 2. Edit specific parameter in `options` section 90 | 3. Restart Vim to apply 91 | 92 | ## Configuration Sections in .vimrc 93 | 94 | ### Main Configuration Variables 95 | 96 | ```vim 97 | " API Key location 98 | let g:vim_ai_token_file_path = '~/.config/openai.token' 99 | 100 | " Chat configuration 101 | let g:vim_ai_chat = { ... } 102 | 103 | " Edit configuration 104 | let g:vim_ai_edit = { ... } 105 | 106 | " Completion configuration 107 | let g:vim_ai_complete = { ... } 108 | 109 | " Custom roles file 110 | let g:vim_ai_roles_config_file = expand('~/.vim/vim-ai-roles.ini') 111 | ``` 112 | 113 | ### Structure of Configuration Dictionaries 114 | 115 | Each configuration (chat, edit, complete) follows this structure: 116 | ```vim 117 | let g:vim_ai_[type] = { 118 | \ "engine": "chat" or "complete", 119 | \ "options": { 120 | \ "model": "gpt-4-turbo-preview", 121 | \ "endpoint_url": "https://api.openai.com/v1/...", 122 | \ "max_tokens": 0, 123 | \ "temperature": 1, 124 | \ "request_timeout": 20, 125 | \ "enable_auth": 1, 126 | \ }, 127 | \ "ui": { 128 | \ "paste_mode": 1, 129 | \ }, 130 | \} 131 | ``` 132 | 133 | ## Troubleshooting Patterns 134 | 135 | ### Issue: vim-ai commands not found 136 | 1. Check plugin installation path exists 137 | 2. Verify Python 3 support in Vim: `vim --version | grep python3` 138 | 3. Check for error messages: `:messages` 139 | 140 | ### Issue: API authentication errors 141 | 1. Verify token file exists and has correct permissions 142 | 2. Check token file path in vimrc 143 | 3. Ensure API key is valid and not expired 144 | 145 | ### Issue: Role not working 146 | 1. Verify role syntax in .ini file 147 | 2. Check role name doesn't have spaces or special characters 148 | 3. Test with `:AI /role-name` (note the `/` prefix) 149 | 150 | ## Best Practices 151 | 152 | 1. **Always backup before editing**: Copy current config before making changes 153 | 2. **Edit, don't replace**: Use targeted edits rather than rewriting entire sections 154 | 3. **Test incrementally**: Make one change at a time and test 155 | 4. **Check documentation**: Fetch latest docs for new features or changes 156 | 5. **Verify file paths**: Confirm files exist before attempting modifications 157 | 158 | ## Workflow Template 159 | 160 | For any configuration task: 161 | 162 | 1. **Identify** which file needs modification (use [file-paths.md](file-paths.md)) 163 | 2. **Fetch** current documentation (use [documentation-sources.md](documentation-sources.md)) 164 | 3. **Read** existing configuration file 165 | 4. **Edit** specific section using Edit tool 166 | 5. **Verify** syntax is correct 167 | 6. **Test** the change in Vim 168 | 7. **Document** what was changed for user reference 169 | -------------------------------------------------------------------------------- /skills/article-writer/scripts/check_style.py: -------------------------------------------------------------------------------- 1 | #!/usr/bin/env python3 2 | """ 3 | Article Style Checker 4 | 5 | Checks markdown files for violations of the article writing style guidelines. 6 | Detects: 7 | - Em dashes (—) 8 | - Empty framing phrases 9 | - Other style violations 10 | """ 11 | 12 | import re 13 | import sys 14 | from pathlib import Path 15 | from typing import List, Tuple 16 | 17 | # Colors for terminal output 18 | RED = '\033[91m' 19 | YELLOW = '\033[93m' 20 | GREEN = '\033[92m' 21 | BLUE = '\033[94m' 22 | RESET = '\033[0m' 23 | 24 | # Banned empty framing phrases 25 | FRAMING_PHRASES = [ 26 | r"but here's the reality:", 27 | r"here's the thing:", 28 | r"the point:", 29 | r"at the end of the day:", 30 | r"the fact of the matter is:", 31 | r"let me be clear:", 32 | r"the bottom line is:", 33 | r"when it comes down to it:", 34 | r"what it boils down to:", 35 | r"in reality:", 36 | ] 37 | 38 | # Em dash variants to check for 39 | EM_DASHES = ['—', '–'] # em dash and en dash 40 | 41 | class StyleViolation: 42 | def __init__(self, line_num: int, line: str, issue: str, suggestion: str = ""): 43 | self.line_num = line_num 44 | self.line = line.strip() 45 | self.issue = issue 46 | self.suggestion = suggestion 47 | 48 | def check_em_dashes(lines: List[str]) -> List[StyleViolation]: 49 | """Check for em dashes in the text.""" 50 | violations = [] 51 | for i, line in enumerate(lines, 1): 52 | for dash in EM_DASHES: 53 | if dash in line: 54 | suggestion = "Use commas, periods, colons, or parentheses instead" 55 | violations.append( 56 | StyleViolation(i, line, f"Em dash ({dash}) found", suggestion) 57 | ) 58 | break # Only report once per line 59 | return violations 60 | 61 | def check_framing_phrases(lines: List[str]) -> List[StyleViolation]: 62 | """Check for banned empty framing phrases.""" 63 | violations = [] 64 | for i, line in enumerate(lines, 1): 65 | line_lower = line.lower() 66 | for phrase in FRAMING_PHRASES: 67 | if re.search(phrase, line_lower): 68 | # Extract what comes after the phrase 69 | match = re.search(phrase + r'\s*(.+)', line_lower) 70 | if match: 71 | actual_point = match.group(1).strip() 72 | suggestion = f"State directly: {actual_point}" 73 | else: 74 | suggestion = "State the point directly without the framing phrase" 75 | 76 | violations.append( 77 | StyleViolation( 78 | i, line, 79 | f"Empty framing phrase: '{phrase.replace(r'', '')}'", 80 | suggestion 81 | ) 82 | ) 83 | return violations 84 | 85 | def check_excessive_hedging(lines: List[str]) -> List[StyleViolation]: 86 | """Check for excessive use of hedging words.""" 87 | hedging_words = [ 88 | r'\bmight\b', r'\bmaybe\b', r'\bperhaps\b', r'\bpossibly\b', 89 | r'\bprobably\b', r'\bseemingly\b', r'\bapparently\b' 90 | ] 91 | violations = [] 92 | 93 | for i, line in enumerate(lines, 1): 94 | # Count hedging words in the line 95 | hedge_count = sum(1 for word in hedging_words if re.search(word, line.lower())) 96 | if hedge_count >= 2: 97 | violations.append( 98 | StyleViolation( 99 | i, line, 100 | f"Multiple hedging words ({hedge_count}) in one line", 101 | "Be more direct and confident" 102 | ) 103 | ) 104 | return violations 105 | 106 | def check_long_paragraphs(content: str) -> List[StyleViolation]: 107 | """Check for paragraphs that are too long.""" 108 | violations = [] 109 | paragraphs = content.split('\n\n') 110 | line_count = 0 111 | 112 | for para in paragraphs: 113 | para = para.strip() 114 | if not para or para.startswith('#') or para.startswith('```'): 115 | line_count += para.count('\n') + 2 # Skip headers and code blocks 116 | continue 117 | 118 | sentences = [s.strip() for s in re.split(r'[.!?]+', para) if s.strip()] 119 | if len(sentences) > 6: 120 | violations.append( 121 | StyleViolation( 122 | line_count + 1, para[:80] + "...", 123 | f"Long paragraph ({len(sentences)} sentences)", 124 | "Consider breaking into multiple paragraphs (2-5 sentences each)" 125 | ) 126 | ) 127 | 128 | line_count += para.count('\n') + 2 129 | 130 | return violations 131 | 132 | def check_file(file_path: Path) -> Tuple[List[StyleViolation], int]: 133 | """Check a single file for style violations.""" 134 | try: 135 | content = file_path.read_text(encoding='utf-8') 136 | lines = content.splitlines() 137 | except Exception as e: 138 | print(f"{RED}Error reading {file_path}: {e}{RESET}") 139 | return [], 0 140 | 141 | violations = [] 142 | violations.extend(check_em_dashes(lines)) 143 | violations.extend(check_framing_phrases(lines)) 144 | violations.extend(check_excessive_hedging(lines)) 145 | violations.extend(check_long_paragraphs(content)) 146 | 147 | # Sort by line number 148 | violations.sort(key=lambda v: v.line_num) 149 | 150 | return violations, len(lines) 151 | 152 | def print_report(file_path: Path, violations: List[StyleViolation], total_lines: int): 153 | """Print a formatted report of style violations.""" 154 | if not violations: 155 | print(f"{GREEN}✓ {file_path.name}: No style violations found{RESET}") 156 | return 157 | 158 | print(f"\n{BLUE}{'='*80}{RESET}") 159 | print(f"{YELLOW}File: {file_path}{RESET}") 160 | print(f"{YELLOW}Found {len(violations)} style violation(s){RESET}") 161 | print(f"{BLUE}{'='*80}{RESET}\n") 162 | 163 | for v in violations: 164 | print(f"{RED}Line {v.line_num}:{RESET} {v.issue}") 165 | print(f" {v.line}") 166 | if v.suggestion: 167 | print(f" {GREEN}→ {v.suggestion}{RESET}") 168 | print() 169 | 170 | def main(): 171 | """Main entry point.""" 172 | if len(sys.argv) < 2: 173 | print(f"Usage: {sys.argv[0]} [file2.md ...]") 174 | print(f" or: {sys.argv[0]} ") 175 | sys.exit(1) 176 | 177 | paths = [Path(arg) for arg in sys.argv[1:]] 178 | files_to_check = [] 179 | 180 | for path in paths: 181 | if path.is_file() and path.suffix == '.md': 182 | files_to_check.append(path) 183 | elif path.is_dir(): 184 | files_to_check.extend(path.rglob('*.md')) 185 | else: 186 | print(f"{YELLOW}Warning: Skipping {path} (not a .md file or directory){RESET}") 187 | 188 | if not files_to_check: 189 | print(f"{RED}No markdown files found to check{RESET}") 190 | sys.exit(1) 191 | 192 | print(f"{BLUE}Checking {len(files_to_check)} file(s)...{RESET}\n") 193 | 194 | total_violations = 0 195 | for file_path in files_to_check: 196 | violations, total_lines = check_file(file_path) 197 | print_report(file_path, violations, total_lines) 198 | total_violations += len(violations) 199 | 200 | # Summary 201 | print(f"\n{BLUE}{'='*80}{RESET}") 202 | if total_violations == 0: 203 | print(f"{GREEN}✓ All files passed style checks!{RESET}") 204 | sys.exit(0) 205 | else: 206 | print(f"{YELLOW}Found {total_violations} total violation(s) across {len(files_to_check)} file(s){RESET}") 207 | sys.exit(1) 208 | 209 | if __name__ == '__main__': 210 | main() 211 | -------------------------------------------------------------------------------- /skills/algorithmic-art/templates/generator_template.js: -------------------------------------------------------------------------------- 1 | /** 2 | * ═══════════════════════════════════════════════════════════════════════════ 3 | * P5.JS GENERATIVE ART - BEST PRACTICES 4 | * ═══════════════════════════════════════════════════════════════════════════ 5 | * 6 | * This file shows STRUCTURE and PRINCIPLES for p5.js generative art. 7 | * It does NOT prescribe what art you should create. 8 | * 9 | * Your algorithmic philosophy should guide what you build. 10 | * These are just best practices for how to structure your code. 11 | * 12 | * ═══════════════════════════════════════════════════════════════════════════ 13 | */ 14 | 15 | // ============================================================================ 16 | // 1. PARAMETER ORGANIZATION 17 | // ============================================================================ 18 | // Keep all tunable parameters in one object 19 | // This makes it easy to: 20 | // - Connect to UI controls 21 | // - Reset to defaults 22 | // - Serialize/save configurations 23 | 24 | let params = { 25 | // Define parameters that match YOUR algorithm 26 | // Examples (customize for your art): 27 | // - Counts: how many elements (particles, circles, branches, etc.) 28 | // - Scales: size, speed, spacing 29 | // - Probabilities: likelihood of events 30 | // - Angles: rotation, direction 31 | // - Colors: palette arrays 32 | 33 | seed: 12345, 34 | // define colorPalette as an array -- choose whatever colors you'd like ['#d97757', '#6a9bcc', '#788c5d', '#b0aea5'] 35 | // Add YOUR parameters here based on your algorithm 36 | }; 37 | 38 | // ============================================================================ 39 | // 2. SEEDED RANDOMNESS (Critical for reproducibility) 40 | // ============================================================================ 41 | // ALWAYS use seeded random for Art Blocks-style reproducible output 42 | 43 | function initializeSeed(seed) { 44 | randomSeed(seed); 45 | noiseSeed(seed); 46 | // Now all random() and noise() calls will be deterministic 47 | } 48 | 49 | // ============================================================================ 50 | // 3. P5.JS LIFECYCLE 51 | // ============================================================================ 52 | 53 | function setup() { 54 | createCanvas(800, 800); 55 | 56 | // Initialize seed first 57 | initializeSeed(params.seed); 58 | 59 | // Set up your generative system 60 | // This is where you initialize: 61 | // - Arrays of objects 62 | // - Grid structures 63 | // - Initial positions 64 | // - Starting states 65 | 66 | // For static art: call noLoop() at the end of setup 67 | // For animated art: let draw() keep running 68 | } 69 | 70 | function draw() { 71 | // Option 1: Static generation (runs once, then stops) 72 | // - Generate everything in setup() 73 | // - Call noLoop() in setup() 74 | // - draw() doesn't do much or can be empty 75 | 76 | // Option 2: Animated generation (continuous) 77 | // - Update your system each frame 78 | // - Common patterns: particle movement, growth, evolution 79 | // - Can optionally call noLoop() after N frames 80 | 81 | // Option 3: User-triggered regeneration 82 | // - Use noLoop() by default 83 | // - Call redraw() when parameters change 84 | } 85 | 86 | // ============================================================================ 87 | // 4. CLASS STRUCTURE (When you need objects) 88 | // ============================================================================ 89 | // Use classes when your algorithm involves multiple entities 90 | // Examples: particles, agents, cells, nodes, etc. 91 | 92 | class Entity { 93 | constructor() { 94 | // Initialize entity properties 95 | // Use random() here - it will be seeded 96 | } 97 | 98 | update() { 99 | // Update entity state 100 | // This might involve: 101 | // - Physics calculations 102 | // - Behavioral rules 103 | // - Interactions with neighbors 104 | } 105 | 106 | display() { 107 | // Render the entity 108 | // Keep rendering logic separate from update logic 109 | } 110 | } 111 | 112 | // ============================================================================ 113 | // 5. PERFORMANCE CONSIDERATIONS 114 | // ============================================================================ 115 | 116 | // For large numbers of elements: 117 | // - Pre-calculate what you can 118 | // - Use simple collision detection (spatial hashing if needed) 119 | // - Limit expensive operations (sqrt, trig) when possible 120 | // - Consider using p5 vectors efficiently 121 | 122 | // For smooth animation: 123 | // - Aim for 60fps 124 | // - Profile if things are slow 125 | // - Consider reducing particle counts or simplifying calculations 126 | 127 | // ============================================================================ 128 | // 6. UTILITY FUNCTIONS 129 | // ============================================================================ 130 | 131 | // Color utilities 132 | function hexToRgb(hex) { 133 | const result = /^#?([a-f\d]{2})([a-f\d]{2})([a-f\d]{2})$/i.exec(hex); 134 | return result ? { 135 | r: parseInt(result[1], 16), 136 | g: parseInt(result[2], 16), 137 | b: parseInt(result[3], 16) 138 | } : null; 139 | } 140 | 141 | function colorFromPalette(index) { 142 | return params.colorPalette[index % params.colorPalette.length]; 143 | } 144 | 145 | // Mapping and easing 146 | function mapRange(value, inMin, inMax, outMin, outMax) { 147 | return outMin + (outMax - outMin) * ((value - inMin) / (inMax - inMin)); 148 | } 149 | 150 | function easeInOutCubic(t) { 151 | return t < 0.5 ? 4 * t * t * t : 1 - Math.pow(-2 * t + 2, 3) / 2; 152 | } 153 | 154 | // Constrain to bounds 155 | function wrapAround(value, max) { 156 | if (value < 0) return max; 157 | if (value > max) return 0; 158 | return value; 159 | } 160 | 161 | // ============================================================================ 162 | // 7. PARAMETER UPDATES (Connect to UI) 163 | // ============================================================================ 164 | 165 | function updateParameter(paramName, value) { 166 | params[paramName] = value; 167 | // Decide if you need to regenerate or just update 168 | // Some params can update in real-time, others need full regeneration 169 | } 170 | 171 | function regenerate() { 172 | // Reinitialize your generative system 173 | // Useful when parameters change significantly 174 | initializeSeed(params.seed); 175 | // Then regenerate your system 176 | } 177 | 178 | // ============================================================================ 179 | // 8. COMMON P5.JS PATTERNS 180 | // ============================================================================ 181 | 182 | // Drawing with transparency for trails/fading 183 | function fadeBackground(opacity) { 184 | fill(250, 249, 245, opacity); // Anthropic light with alpha 185 | noStroke(); 186 | rect(0, 0, width, height); 187 | } 188 | 189 | // Using noise for organic variation 190 | function getNoiseValue(x, y, scale = 0.01) { 191 | return noise(x * scale, y * scale); 192 | } 193 | 194 | // Creating vectors from angles 195 | function vectorFromAngle(angle, magnitude = 1) { 196 | return createVector(cos(angle), sin(angle)).mult(magnitude); 197 | } 198 | 199 | // ============================================================================ 200 | // 9. EXPORT FUNCTIONS 201 | // ============================================================================ 202 | 203 | function exportImage() { 204 | saveCanvas('generative-art-' + params.seed, 'png'); 205 | } 206 | 207 | // ============================================================================ 208 | // REMEMBER 209 | // ============================================================================ 210 | // 211 | // These are TOOLS and PRINCIPLES, not a recipe. 212 | // Your algorithmic philosophy should guide WHAT you create. 213 | // This structure helps you create it WELL. 214 | // 215 | // Focus on: 216 | // - Clean, readable code 217 | // - Parameterized for exploration 218 | // - Seeded for reproducibility 219 | // - Performant execution 220 | // 221 | // The art itself is entirely up to you! 222 | // 223 | // ============================================================================ -------------------------------------------------------------------------------- /skills/article-writer/references/style-guide.md: -------------------------------------------------------------------------------- 1 | # Article Writing Style Guide 2 | 3 | This document outlines the complete writing style for blog articles and technical posts. 4 | 5 | ## Voice & Tone 6 | 7 | ### Overall Voice 8 | - **Conversational and direct**: Write like you're talking to a peer over coffee, not giving a formal presentation 9 | - **Confident and opinionated**: State your views clearly. No hedging with "I think maybe" or "it might be that" 10 | - **No-BS approach**: Cut to the point. Don't waste the reader's time with unnecessary preamble 11 | - **Strategic profanity**: Use strong language sparingly for emphasis. "This is dogshit" hits harder than "This is suboptimal" 12 | 13 | ### Person and Perspective 14 | - **Second person ("you")**: Address the reader directly. "You need to understand this" not "One should understand this" 15 | - **First person when sharing experience**: "I've seen this play out" or "Here's what I kept running into" 16 | - **Use contractions**: "it's", "you're", "don't", "won't" - keeps the tone conversational 17 | 18 | ### Emotional Tone 19 | - **Assertive, not aggressive**: Be confident in your points without being condescending 20 | - **Empathetic when appropriate**: Acknowledge reader frustrations. "Look, I get it. It sucks." 21 | - **Enthusiasm for solutions**: Show genuine excitement about techniques that work 22 | 23 | ## Structure & Formatting 24 | 25 | ### Headers 26 | - **Use sentence case, mostly lowercase**: "the identity problem" not "The Identity Problem" 27 | - **Exceptions**: Capitalize proper nouns, acronyms (TDD, FFmpeg) 28 | - **Make headers descriptive**: Tell the reader what the section is about, not just a vague label 29 | 30 | ### Paragraphs 31 | - **Keep them short**: 2-5 sentences max in most cases 32 | - **One idea per paragraph**: Don't cram multiple concepts together 33 | - **Vary length**: Mix very short (1 sentence) paragraphs with slightly longer ones for rhythm 34 | - **Break up walls of text**: If a paragraph is getting long, split it 35 | 36 | ### Section Breaks 37 | - **Use horizontal rules** (`---`) to separate major sections 38 | - **Don't overuse them**: Only for significant topic shifts, not between every section 39 | 40 | ### Lists 41 | - **Bullet points for related items**: Use when order doesn't matter 42 | - **Numbered lists for sequences**: Use when steps need to happen in order 43 | - **Keep list items parallel**: Start each with same part of speech 44 | - **Bold key terms** in lists for scannability 45 | 46 | ### Emphasis 47 | - **Bold for key terms and concepts**: First mention of important terms 48 | - **Bold for strong emphasis**: When you really need something to stand out 49 | - **Italics sparingly**: Only for subtle emphasis or technical terms that need distinction 50 | - **Don't overuse**: If everything is emphasized, nothing is 51 | 52 | ### Code and Technical Terms 53 | - **Inline code** with backticks: `variable_name`, `function()`, `file.js` 54 | - **Code blocks** with triple backticks for multi-line code 55 | - **Specify language** in code blocks: ```python, ```javascript 56 | - **Technical terms**: Use proper casing (TypeScript, GitHub, not typescript, github) 57 | 58 | ## Content Patterns 59 | 60 | ### Opening 61 | - **Start with a strong hook**: Lead with an assertion, question, or surprising fact 62 | - **Establish credibility early**: Brief context about your experience (1-2 sentences) 63 | - **Promise value**: Tell readers what they'll learn or gain 64 | 65 | ### Body Structure 66 | - **Problem-Solution format**: Identify problems, then show solutions 67 | - **Use concrete examples**: Real-world scenarios, not just abstract concepts 68 | - **Include data when possible**: "20% improvement" beats "significant improvement" 69 | - **Address counterarguments**: Acknowledge opposing views and explain why you disagree 70 | 71 | ### Transitions 72 | - **Connect sections logically**: Each section should flow to the next 73 | - **Use transitional phrases sparingly**: "Here's the thing" is banned; find better ways to connect 74 | - **Callback to earlier points**: Reference concepts introduced earlier to build coherence 75 | 76 | ### Examples and Evidence 77 | - **Real examples over hypothetical**: "I watched this play out on teams" beats "Imagine if..." 78 | - **Specific over general**: "500 lines of code" beats "lots of code" 79 | - **Personal experience**: Share what you've actually tried and learned 80 | - **Data and research**: Reference studies, papers, or metrics when available 81 | 82 | ### Actionable Advice 83 | - **Be specific**: "Run `npm install`" not "Install the dependencies" 84 | - **Explain the why**: Don't just tell readers what to do, explain why it matters 85 | - **Provide alternatives**: When multiple approaches exist, acknowledge them 86 | - **Realistic trade-offs**: Don't oversell; mention downsides when relevant 87 | 88 | ## Writing Mechanics 89 | 90 | ### Sentence Structure 91 | - **Vary sentence length**: Mix short punchy sentences with longer explanatory ones 92 | - **Start sentences differently**: Don't begin every sentence the same way 93 | - **Active voice preferred**: "AI generates code" not "Code is generated by AI" 94 | - **Passive voice when appropriate**: When the actor is unknown or irrelevant 95 | 96 | ### Word Choice 97 | - **Concrete over abstract**: "3x faster" beats "much faster" 98 | - **Specific over vague**: "TypeScript errors" beats "issues" 99 | - **Simple over complex**: "use" beats "utilize" 100 | - **Technical precision**: Use correct technical terms, but explain jargon 101 | 102 | ### Rhythm and Flow 103 | - **Read it aloud**: If it sounds awkward spoken, rewrite it 104 | - **Punch after setup**: Short sentence after a longer one for emphasis 105 | - **Break up monotony**: Don't let similar sentence structures stack up 106 | 107 | ## Banned Patterns 108 | 109 | ### Empty Framing Phrases 110 | Never use these discourse markers: 111 | - "But here's the reality:" 112 | - "Here's the thing:" 113 | - "The point:" 114 | - "At the end of the day:" 115 | - "The fact of the matter is:" 116 | - "Let me be clear:" 117 | 118 | **Why banned**: They announce something important is coming instead of just saying it. Wastes space, delays the actual point. 119 | 120 | **Fix**: State the point directly. 121 | - ❌ "Here's the thing: your costs are too high" 122 | - ✅ "Your costs are too high" 123 | 124 | ### Em Dashes 125 | Never use em dashes (—) for: 126 | - Interrupting sentences 127 | - Adding asides 128 | - Creating dramatic pauses 129 | 130 | **Why banned**: Informal, visually noisy, easy to overuse. Makes writing feel jumpy and less precise. 131 | 132 | **Alternatives**: 133 | - Use commas for asides: "The feature, which took weeks to build, finally shipped" 134 | - Use periods for separate thoughts: "The feature took weeks. It finally shipped." 135 | - Use parentheses for true asides: "The feature (which took weeks to build) finally shipped" 136 | - Use colons for emphasis: "The result was clear: the feature shipped" 137 | 138 | ### Other Patterns to Avoid 139 | - **Excessive hedging**: "might", "perhaps", "possibly" (use sparingly) 140 | - **Buzzword soup**: Don't stack trendy terms without substance 141 | - **Passive constructions**: Minimize "is being", "was done", "were created" 142 | - **Unnecessary adverbs**: "very", "really", "actually" (use strategically or cut) 143 | 144 | ## Technical Article Specifics 145 | 146 | ### Code Examples 147 | - **Show, don't just tell**: Include actual code snippets 148 | - **Explain non-obvious parts**: Don't assume all readers know the syntax 149 | - **Keep examples focused**: Don't include irrelevant boilerplate 150 | - **Show before and after**: For refactoring or improvements 151 | 152 | ### Technical Depth 153 | - **Match audience knowledge**: For experienced developers, skip basic concepts 154 | - **Define specialized terms**: Even for technical audiences, clarify domain-specific jargon 155 | - **Link to documentation**: When referencing tools or libraries 156 | - **Provide context**: Why this matters, where it fits in the larger picture 157 | 158 | ### Practical Application 159 | - **Prioritize real-world utility**: Focus on what actually works, not just what's theoretically interesting 160 | - **Include setup/prerequisites**: Don't skip the boring but necessary setup steps 161 | - **Mention trade-offs**: Be honest about limitations and downsides 162 | - **Update dates and versions**: Specify when something applies to specific versions 163 | 164 | ## Final Checklist 165 | 166 | Before publishing, verify: 167 | - [ ] No em dashes (—) anywhere 168 | - [ ] No empty framing phrases 169 | - [ ] Headers are descriptive and mostly lowercase 170 | - [ ] Paragraphs are short (2-5 sentences) 171 | - [ ] Mix of sentence lengths for rhythm 172 | - [ ] Technical terms are accurate and properly capitalized 173 | - [ ] Code examples are tested and work 174 | - [ ] Bold/italics used for emphasis, not decoration 175 | - [ ] Strong opening hook 176 | - [ ] Clear value proposition 177 | - [ ] Concrete examples throughout 178 | - [ ] Actionable takeaways 179 | - [ ] Conversational but authoritative tone 180 | -------------------------------------------------------------------------------- /skills/article-writer/SKILL.md: -------------------------------------------------------------------------------- 1 | --- 2 | name: article-writer 3 | description: Edit and refine blog articles and technical posts to match a specific writing style. Use when editing markdown articles, blog posts, or technical writing. Applies conversational, direct, no-BS style with strict guidelines (no em dashes, no empty framing phrases). Best for technical content aimed at experienced developers. 4 | --- 5 | 6 | # Article Writer 7 | 8 | ## Overview 9 | 10 | Edit blog articles and technical posts to match a specific writing style: conversational, direct, opinionated, and technically precise. Apply strict style guidelines including banned patterns (em dashes, empty framing phrases) and enforce consistent voice, structure, and formatting. 11 | 12 | ## When to Use This Skill 13 | 14 | Activate this skill when: 15 | - Editing markdown articles or blog posts 16 | - Refining technical writing for publication 17 | - Reviewing drafts for style consistency 18 | - Converting formal writing to conversational style 19 | - Checking articles for guideline violations 20 | 21 | ## Editing Workflow 22 | 23 | Follow this workflow when editing articles: 24 | 25 | ### 1. Initial Assessment 26 | 27 | Read the article draft completely to understand: 28 | - Main topic and key points 29 | - Target audience and technical level 30 | - Current writing style and tone 31 | - Overall structure and flow 32 | 33 | ### 2. Run Automated Style Check 34 | 35 | Before manual editing, run the style checker to identify violations: 36 | 37 | ```bash 38 | python3 scripts/check_style.py 39 | ``` 40 | 41 | The checker identifies: 42 | - Em dashes (— or –) 43 | - Empty framing phrases ("Here's the thing:", "But here's the reality:", etc.) 44 | - Excessive hedging words 45 | - Overly long paragraphs (>6 sentences) 46 | 47 | Review the automated findings and keep them in mind during editing. 48 | 49 | ### 3. Apply Core Guidelines 50 | 51 | Reference `references/writing-guidelines.md` for banned patterns: 52 | 53 | **Eliminate em dashes entirely:** 54 | - Replace with commas, periods, colons, or parentheses 55 | - Example: "The feature—which took weeks—finally shipped" → "The feature, which took weeks, finally shipped" 56 | 57 | **Remove empty framing phrases:** 58 | - Cut discourse markers that announce rather than state 59 | - Example: "Here's the thing: your costs are too high" → "Your costs are too high" 60 | - Common culprits: "Here's the reality:", "The point:", "At the end of the day:" 61 | 62 | ### 4. Match the Style Guide 63 | 64 | Reference `references/style-guide.md` for comprehensive style patterns. Focus on these key areas: 65 | 66 | **Voice & Tone:** 67 | - Conversational and direct (like talking to a peer) 68 | - Confident and opinionated (no hedging) 69 | - Second person ("you") for direct address 70 | - Strategic profanity for emphasis (use sparingly) 71 | - Contractions throughout (it's, you're, don't) 72 | 73 | **Structure:** 74 | - Short paragraphs (2-5 sentences typically) 75 | - One idea per paragraph 76 | - Headers in sentence case, mostly lowercase 77 | - Horizontal rules (---) for major section breaks only 78 | - Frequent bullet points and numbered lists 79 | 80 | **Emphasis:** 81 | - Bold for key terms and strong emphasis 82 | - Italics sparingly 83 | - Inline code with backticks for technical terms 84 | - Code blocks with language specification 85 | 86 | **Content Patterns:** 87 | - Strong opening hook (assertion, question, surprising fact) 88 | - Concrete examples over abstract concepts 89 | - Specific numbers and data ("20% improvement" not "significant") 90 | - Address counterarguments directly 91 | - Actionable advice with clear explanations 92 | 93 | **Sentence Structure:** 94 | - Vary sentence length for rhythm 95 | - Mix short punchy sentences with longer explanatory ones 96 | - Active voice preferred 97 | - Specific over vague word choice 98 | 99 | ### 5. Check Against Example Article 100 | 101 | Reference `references/example-article.md` to see the style in practice. Use it to: 102 | - Verify tone matches (direct, confident, conversational) 103 | - Check section structure (headers, paragraphs, lists) 104 | - Confirm opening and closing patterns 105 | - Validate technical depth and accessibility balance 106 | 107 | ### 6. Final Review Checklist 108 | 109 | Before completing edits, verify: 110 | - [ ] No em dashes anywhere 111 | - [ ] No empty framing phrases 112 | - [ ] Paragraphs are 2-5 sentences (with intentional exceptions) 113 | - [ ] Headers are descriptive and sentence case 114 | - [ ] Mix of sentence lengths creates good rhythm 115 | - [ ] Technical terms accurate and properly formatted 116 | - [ ] Strong opening hook present 117 | - [ ] Concrete examples throughout 118 | - [ ] Conversational but authoritative tone 119 | - [ ] Bold/italics used for emphasis, not decoration 120 | 121 | ### 7. Provide Edit Summary 122 | 123 | After editing, summarize changes made: 124 | - List major structural changes 125 | - Note pattern fixes (em dashes removed, framing phrases cut, etc.) 126 | - Highlight tone adjustments 127 | - Mention any sections that needed significant rewriting 128 | - Flag any areas where style guide couldn't be fully applied (explain why) 129 | 130 | ## Editing Principles 131 | 132 | ### Progressive Enhancement 133 | 134 | Edit in passes rather than trying to fix everything at once: 135 | 1. First pass: Structure and flow 136 | 2. Second pass: Voice and tone 137 | 3. Third pass: Guidelines compliance (em dashes, framing phrases) 138 | 4. Fourth pass: Polish and rhythm 139 | 140 | ### Preserve Author's Voice 141 | 142 | While enforcing style guidelines: 143 | - Maintain the author's key points and arguments 144 | - Keep technical accuracy intact 145 | - Preserve intentional emphasis 146 | - Don't over-homogenize; some variation is natural 147 | 148 | ### Explain Significant Changes 149 | 150 | When making major edits: 151 | - Note why the change improves the piece 152 | - Reference specific guideline violations 153 | - Suggest alternatives if the change is debatable 154 | - Explain trade-offs when style conflicts with clarity 155 | 156 | ### Balance Rules with Readability 157 | 158 | Guidelines are strong defaults, not absolute laws: 159 | - Occasionally break rules for clarity or impact 160 | - Use judgment on sentence and paragraph length 161 | - Allow strategic rule-breaking when it serves the writing 162 | - Explain intentional guideline deviations 163 | 164 | ## Common Editing Patterns 165 | 166 | ### Removing Framing Phrases 167 | 168 | ❌ "Here's the thing: AI is changing development" 169 | ✅ "AI is changing development" 170 | 171 | ❌ "The point is that you need to adapt" 172 | ✅ "You need to adapt" 173 | 174 | ### Replacing Em Dashes 175 | 176 | ❌ "The feature—despite taking weeks—finally shipped" 177 | ✅ "The feature, despite taking weeks, finally shipped" 178 | ✅ "The feature (despite taking weeks) finally shipped" 179 | ✅ "The feature finally shipped. It took weeks." 180 | 181 | ### Shortening Paragraphs 182 | 183 | When a paragraph exceeds 5-6 sentences, split it: 184 | - Find natural break points (topic shifts) 185 | - Create two focused paragraphs 186 | - Ensure each has one main idea 187 | - Add transitions if needed 188 | 189 | ### Strengthening Voice 190 | 191 | Weak: "It might be possible that this approach could work" 192 | Strong: "This approach works" 193 | 194 | Weak: "One should consider using tests" 195 | Strong: "Use tests" 196 | 197 | Weak: "There are many benefits to AI coding" 198 | Strong: "AI coding speeds up development, catches bugs earlier, and lets you ship faster" 199 | 200 | ### Adding Concreteness 201 | 202 | Vague: "The performance improved significantly" 203 | Concrete: "Latency dropped from 500ms to 50ms" 204 | 205 | Vague: "Many developers are adopting AI tools" 206 | Concrete: "GitHub's data shows 92% of developers now use AI coding tools" 207 | 208 | ## Resources 209 | 210 | ### references/ 211 | 212 | **writing-guidelines.md** - Core banned patterns and why they're problematic: 213 | - Empty framing phrases (comprehensive list) 214 | - Em dashes and alternatives 215 | - Concise explanations of each rule 216 | 217 | **style-guide.md** - Complete style specification covering: 218 | - Voice & tone (conversational, direct, opinionated) 219 | - Structure & formatting (paragraphs, headers, lists) 220 | - Content patterns (openings, examples, actionable advice) 221 | - Writing mechanics (sentence structure, word choice, rhythm) 222 | - Final checklist for publishing 223 | 224 | **example-article.md** - Full-length article demonstrating the style: 225 | - Technical depth (AI coding guide) 226 | - Target audience (experienced developers) 227 | - Proper use of all style elements 228 | - Real-world example of the guidelines in practice 229 | 230 | Load these references when editing to ensure consistency with established patterns. 231 | 232 | ### scripts/ 233 | 234 | **check_style.py** - Automated style violation detector: 235 | - Scans markdown files for em dashes and framing phrases 236 | - Identifies excessive hedging and long paragraphs 237 | - Provides specific suggestions for fixes 238 | - Colored terminal output for easy scanning 239 | 240 | Run before manual editing to catch mechanical violations quickly. Use the output to guide editing priorities. 241 | 242 | Usage: 243 | ```bash 244 | # Single file 245 | python3 scripts/check_style.py article.md 246 | 247 | # Multiple files 248 | python3 scripts/check_style.py article1.md article2.md 249 | 250 | # Entire directory 251 | python3 scripts/check_style.py ./articles/ 252 | ``` 253 | 254 | ## Tips for Best Results 255 | 256 | ### When Editing Lightly 257 | 258 | For minor edits (article mostly matches style): 259 | 1. Run check_style.py first 260 | 2. Fix flagged violations 261 | 3. Quick read for tone and flow 262 | 4. Verify checklist items 263 | 264 | ### When Editing Heavily 265 | 266 | For major rewrites (article needs significant work): 267 | 1. Read full article to understand intent 268 | 2. Outline key points to preserve 269 | 3. Rewrite section by section 270 | 4. Reference style-guide.md frequently 271 | 5. Compare against example-article.md for tone 272 | 6. Run check_style.py at end 273 | 7. Final polish pass 274 | 275 | ### When Unsure 276 | 277 | If style application is ambiguous: 278 | - Prioritize clarity over strict adherence 279 | - Explain the reasoning for the choice 280 | - Offer alternative phrasings 281 | - Ask the user which approach they prefer 282 | 283 | ### Continuous Improvement 284 | 285 | After editing multiple articles: 286 | - Note recurring issues or patterns 287 | - Suggest additions to style guide if needed 288 | - Identify areas where guidelines conflict 289 | - Recommend script enhancements for new patterns 290 | -------------------------------------------------------------------------------- /skills/wezterm-config/SKILL.md: -------------------------------------------------------------------------------- 1 | --- 2 | name: wezterm-config 3 | description: Complete WezTerm terminal emulator configuration assistant. Use for any WezTerm configuration task including appearance, fonts, colors, keybindings, mouse bindings, tabs, panes, SSH domains, multiplexing, serial ports, plugins, events, window management, performance, platform-specific settings, Lua scripting, or any terminal customization. 4 | --- 5 | 6 | # WezTerm Configuration Assistant 7 | 8 | This skill provides comprehensive assistance for configuring WezTerm terminal emulator. WezTerm uses Lua 5.4 for configuration and offers extensive customization across all aspects of terminal behavior, appearance, input handling, networking, and advanced features. 9 | 10 | ## Configuration Location 11 | 12 | **Config Directory:** `/Users/alex/.config/wezterm` 13 | **Main Config File:** `/Users/alex/.config/wezterm/wezterm.lua` 14 | 15 | Alternative locations: `~/.wezterm.lua` or paths specified via `$WEZTERM_CONFIG_FILE` 16 | 17 | ## Core Principles 18 | 19 | ### ALWAYS Follow This Workflow 20 | 21 | 1. **Read Current Config**: Use Read tool to examine existing configuration 22 | 2. **Fetch Documentation**: Use WebFetch to get current documentation for the specific feature 23 | 3. **Research Thoroughly**: Check multiple doc pages if needed for complex features 24 | 4. **Implement Carefully**: Preserve existing config, validate Lua syntax 25 | 5. **Explain Clearly**: Document what changed and why 26 | 6. **Guide Testing**: Explain how to reload config (Ctrl+Shift+R or restart) 27 | 28 | ### Documentation Strategy 29 | 30 | **Never embed documentation text.** Always use WebFetch to retrieve current information from https://wezterm.org/ 31 | 32 | WezTerm documentation is comprehensive and continuously updated. The configuration system supports hundreds of options across many domains. 33 | 34 | ## Full Configuration Capabilities 35 | 36 | WezTerm supports configuration across these comprehensive areas. For each request, fetch the relevant documentation: 37 | 38 | ### 1. Visual Appearance & Display 39 | - **Colors & Schemes**: Color schemes, palette customization, dynamic colors 40 | - https://wezterm.org/config/appearance.html 41 | - https://wezterm.org/colorschemes/ 42 | - https://wezterm.org/config/lua/wezterm.color/ 43 | - **Fonts**: Font families, size, weight, fallback, shaping, ligatures, harfbuzz 44 | - https://wezterm.org/config/fonts.html 45 | - https://wezterm.org/config/lua/wezterm/font.html 46 | - **Cursor**: Style, blinking, colors, thickness 47 | - **Window**: Decorations, opacity, blur, padding, dimensions, background 48 | - **Tab Bar**: Styling, position, colors, custom rendering 49 | - https://wezterm.org/config/lua/config/tab_bar_style.html 50 | - **Rendering**: GPU settings, WebGPU, FreeType options, anti-aliasing 51 | - https://wezterm.org/config/lua/config/front_end.html 52 | 53 | ### 2. Input & Interaction 54 | - **Keyboard Bindings**: Key assignments, key tables, leader keys 55 | - https://wezterm.org/config/keyboard-concepts.html 56 | - https://wezterm.org/config/keys.html 57 | - https://wezterm.org/config/lua/keyassignment/ 58 | - **Mouse Bindings**: Click actions, drag behavior, scrolling 59 | - https://wezterm.org/config/mouse.html 60 | - **Copy Mode**: Quick select patterns, search mode, selection patterns 61 | - https://wezterm.org/copymode.html 62 | - **IME**: Input method editor settings for international input 63 | 64 | ### 3. Window & Pane Management 65 | - **Panes**: Splitting, navigation, focus, sizing 66 | - https://wezterm.org/config/lua/pane/ 67 | - **Tabs**: Creation, navigation, renaming, styling 68 | - https://wezterm.org/config/lua/MuxTab/ 69 | - **Windows**: Multiple windows, positioning, fullscreen 70 | - https://wezterm.org/config/lua/window/ 71 | - https://wezterm.org/config/lua/gui-events/ 72 | - **Workspaces**: Workspace management and switching 73 | - https://wezterm.org/config/lua/wezterm.mux/ 74 | 75 | ### 4. Terminal Behavior 76 | - **Scrollback**: Buffer size, history management 77 | - **Bell**: Visual and audible notifications 78 | - **Exit Behavior**: Close confirmation, hold on exit 79 | - **Text Processing**: Blink animation, semantic zones 80 | - **Clipboard**: Paste behavior, bracketed paste 81 | - **Shell Integration**: OSC sequences, semantic prompts 82 | - https://wezterm.org/shell-integration.html 83 | 84 | ### 5. Advanced Connectivity 85 | - **SSH Client**: Native SSH integration, SSH domains, connection management 86 | - https://wezterm.org/config/lua/SshDomain.html 87 | - https://wezterm.org/ssh.html 88 | - **Multiplexing**: Unix domain sockets, TCP connections, TLS 89 | - https://wezterm.org/multiplexing.html 90 | - https://wezterm.org/config/lua/mux-events/ 91 | - **Serial Ports**: Serial device connections 92 | - https://wezterm.org/config/lua/SerialDomain.html 93 | - **WSL Integration**: Windows Subsystem for Linux domains 94 | - https://wezterm.org/config/lua/WslDomain.html 95 | - **TLS**: Certificate management, client/server TLS settings 96 | 97 | ### 6. Events & Scripting 98 | - **Event Handlers**: GUI events, mux events, window events 99 | - https://wezterm.org/config/lua/window-events/ 100 | - https://wezterm.org/config/lua/gui-events/ 101 | - https://wezterm.org/config/lua/mux-events/ 102 | - **Custom Actions**: wezterm.action, emit events, custom logic 103 | - **Status Bar**: Custom status line rendering 104 | - https://wezterm.org/config/lua/window-events/update-status.html 105 | - **Tab Formatting**: Custom tab title and appearance 106 | - **Lua Modules**: wezterm.color, wezterm.gui, wezterm.mux, wezterm.time, wezterm.serde 107 | - https://wezterm.org/config/lua/general.html 108 | 109 | ### 7. Platform-Specific Features 110 | - **macOS**: Native fullscreen, window blur, decorations 111 | - https://wezterm.org/config/lua/config/macos_window_background_blur.html 112 | - **Windows**: Acrylic effects, backdrop blur, WSL 113 | - **Linux**: Wayland support, desktop environment detection 114 | - **FreeBSD/NetBSD**: Platform-specific optimizations 115 | 116 | ### 8. Graphics & Media 117 | - **Image Protocol**: iTerm2 image protocol, imgcat 118 | - https://wezterm.org/imgcat.html 119 | - **Kitty Graphics**: Kitty graphics protocol support 120 | - **Sixel**: Sixel graphics rendering 121 | 122 | ### 9. Launcher & Command Palette 123 | - **Launcher Menu**: Custom launcher items, domain launching 124 | - https://wezterm.org/config/launch.html 125 | - **Command Palette**: Custom palette commands 126 | - https://wezterm.org/config/lua/keyassignment/ActivateCommandPalette.html 127 | 128 | ### 10. Plugin System 129 | - **Plugin Loading**: Plugin management and configuration 130 | - https://wezterm.org/config/lua/wezterm.plugin/ 131 | 132 | ### 11. Performance & Optimization 133 | - **Frame Rate**: Animation FPS, performance tuning 134 | - **Scrollback Limits**: Memory management 135 | - **GPU Selection**: Renderer preferences, hardware acceleration 136 | 137 | ### 12. Advanced Configuration Patterns 138 | - **Config Builder**: Using wezterm.config_builder() 139 | - https://wezterm.org/config/files.html 140 | - **Modular Configs**: Splitting config across multiple Lua files 141 | - **Per-Window Overrides**: window:set_config_overrides() 142 | - **CLI Overrides**: Command-line configuration parameters 143 | - **Conditional Logic**: Platform detection, environment-based config 144 | - **Hot Reloading**: Automatic config reload on file change 145 | 146 | ## Configuration File Structure 147 | 148 | Modern WezTerm configs use the config_builder pattern: 149 | 150 | ```lua 151 | local wezterm = require 'wezterm' 152 | local config = wezterm.config_builder() 153 | 154 | -- All configuration options 155 | config.option_name = value 156 | 157 | return config 158 | ``` 159 | 160 | Legacy pattern (still valid): 161 | ```lua 162 | local wezterm = require 'wezterm' 163 | return { 164 | option_name = value, 165 | } 166 | ``` 167 | 168 | ## Finding Documentation 169 | 170 | For ANY configuration request: 171 | 172 | 1. **Main Documentation Hub**: https://wezterm.org/ 173 | 2. **Full Config Reference**: https://wezterm.org/config/lua/config/index.html 174 | 3. **Lua API Reference**: https://wezterm.org/config/lua/general.html 175 | 4. **Search Strategy**: Use WebFetch to retrieve specific pages for: 176 | - The main feature category 177 | - Specific config options 178 | - Related examples or patterns 179 | - Event handlers if dynamic behavior needed 180 | 181 | ## Research Process for Each Request 182 | 183 | When user requests any configuration change: 184 | 185 | 1. **Identify Category**: Determine which configuration area(s) are involved 186 | 2. **Fetch Core Docs**: Get main documentation page for that category 187 | 3. **Fetch Specifics**: If needed, get specific API reference or examples 188 | 4. **Check Events**: If dynamic behavior needed, fetch event documentation 189 | 5. **Verify Syntax**: Check Lua API docs for correct object/method usage 190 | 6. **Cross-Reference**: Look at related features that might enhance the solution 191 | 192 | ## Implementation Guidelines 193 | 194 | ### Code Quality 195 | - Use clear variable names and comments 196 | - Follow Lua best practices 197 | - Validate syntax before suggesting 198 | - Use wezterm.config_builder() for new configs 199 | 200 | ### Config Organization 201 | - Group related settings together 202 | - Add section comments for clarity 203 | - Consider suggesting modular organization for complex configs 204 | - Preserve user's existing organizational structure 205 | 206 | ### Error Prevention 207 | - Avoid side effects in config (no unconditional process launches) 208 | - Check for config file existence before editing 209 | - Validate that Lua syntax is correct 210 | - Test edge cases in suggestions 211 | 212 | ### User Guidance 213 | - Explain what each change does 214 | - Link to relevant documentation pages 215 | - Suggest how to test changes (Ctrl+Shift+R) 216 | - Offer related enhancements when appropriate 217 | - Mention platform-specific considerations if relevant 218 | 219 | ## Advanced Scenarios 220 | 221 | ### Creating Helper Modules 222 | For complex configs, suggest creating helper modules in the config directory that can be required and reused. 223 | 224 | ### Event-Driven Configuration 225 | When dynamic behavior is needed, use event handlers rather than static config. 226 | 227 | ### Conditional Configuration 228 | Use Lua conditionals for platform-specific or environment-based settings. 229 | 230 | ### Performance Optimization 231 | Consider performance implications of suggestions (e.g., scrollback size, animation settings). 232 | 233 | ## Troubleshooting Support 234 | 235 | When issues arise: 236 | - Check the changelog for version-specific features 237 | - Verify config syntax with wezterm.config_builder() 238 | - Look for deprecation warnings in docs 239 | - Suggest using wezterm CLI tools for debugging 240 | - Reference https://wezterm.org/troubleshooting.html 241 | 242 | ## Remember 243 | 244 | - **Never paste documentation** - always use WebFetch 245 | - **Always read config first** - understand existing setup 246 | - **Research thoroughly** - fetch multiple doc pages if needed 247 | - **Explain clearly** - user should understand the changes 248 | - **Link resources** - provide documentation URLs for reference 249 | - **Test guidance** - explain how to verify changes work 250 | 251 | WezTerm is feature-rich and constantly evolving. When in doubt, fetch the documentation. 252 | -------------------------------------------------------------------------------- /skills/skill-creator/LICENSE.txt: -------------------------------------------------------------------------------- 1 | 2 | Apache License 3 | Version 2.0, January 2004 4 | http://www.apache.org/licenses/ 5 | 6 | TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION 7 | 8 | 1. Definitions. 9 | 10 | "License" shall mean the terms and conditions for use, reproduction, 11 | and distribution as defined by Sections 1 through 9 of this document. 12 | 13 | "Licensor" shall mean the copyright owner or entity authorized by 14 | the copyright owner that is granting the License. 15 | 16 | "Legal Entity" shall mean the union of the acting entity and all 17 | other entities that control, are controlled by, or are under common 18 | control with that entity. For the purposes of this definition, 19 | "control" means (i) the power, direct or indirect, to cause the 20 | direction or management of such entity, whether by contract or 21 | otherwise, or (ii) ownership of fifty percent (50%) or more of the 22 | outstanding shares, or (iii) beneficial ownership of such entity. 23 | 24 | "You" (or "Your") shall mean an individual or Legal Entity 25 | exercising permissions granted by this License. 26 | 27 | "Source" form shall mean the preferred form for making modifications, 28 | including but not limited to software source code, documentation 29 | source, and configuration files. 30 | 31 | "Object" form shall mean any form resulting from mechanical 32 | transformation or translation of a Source form, including but 33 | not limited to compiled object code, generated documentation, 34 | and conversions to other media types. 35 | 36 | "Work" shall mean the work of authorship, whether in Source or 37 | Object form, made available under the License, as indicated by a 38 | copyright notice that is included in or attached to the work 39 | (an example is provided in the Appendix below). 40 | 41 | "Derivative Works" shall mean any work, whether in Source or Object 42 | form, that is based on (or derived from) the Work and for which the 43 | editorial revisions, annotations, elaborations, or other modifications 44 | represent, as a whole, an original work of authorship. For the purposes 45 | of this License, Derivative Works shall not include works that remain 46 | separable from, or merely link (or bind by name) to the interfaces of, 47 | the Work and Derivative Works thereof. 48 | 49 | "Contribution" shall mean any work of authorship, including 50 | the original version of the Work and any modifications or additions 51 | to that Work or Derivative Works thereof, that is intentionally 52 | submitted to Licensor for inclusion in the Work by the copyright owner 53 | or by an individual or Legal Entity authorized to submit on behalf of 54 | the copyright owner. For the purposes of this definition, "submitted" 55 | means any form of electronic, verbal, or written communication sent 56 | to the Licensor or its representatives, including but not limited to 57 | communication on electronic mailing lists, source code control systems, 58 | and issue tracking systems that are managed by, or on behalf of, the 59 | Licensor for the purpose of discussing and improving the Work, but 60 | excluding communication that is conspicuously marked or otherwise 61 | designated in writing by the copyright owner as "Not a Contribution." 62 | 63 | "Contributor" shall mean Licensor and any individual or Legal Entity 64 | on behalf of whom a Contribution has been received by Licensor and 65 | subsequently incorporated within the Work. 66 | 67 | 2. Grant of Copyright License. Subject to the terms and conditions of 68 | this License, each Contributor hereby grants to You a perpetual, 69 | worldwide, non-exclusive, no-charge, royalty-free, irrevocable 70 | copyright license to reproduce, prepare Derivative Works of, 71 | publicly display, publicly perform, sublicense, and distribute the 72 | Work and such Derivative Works in Source or Object form. 73 | 74 | 3. Grant of Patent License. Subject to the terms and conditions of 75 | this License, each Contributor hereby grants to You a perpetual, 76 | worldwide, non-exclusive, no-charge, royalty-free, irrevocable 77 | (except as stated in this section) patent license to make, have made, 78 | use, offer to sell, sell, import, and otherwise transfer the Work, 79 | where such license applies only to those patent claims licensable 80 | by such Contributor that are necessarily infringed by their 81 | Contribution(s) alone or by combination of their Contribution(s) 82 | with the Work to which such Contribution(s) was submitted. If You 83 | institute patent litigation against any entity (including a 84 | cross-claim or counterclaim in a lawsuit) alleging that the Work 85 | or a Contribution incorporated within the Work constitutes direct 86 | or contributory patent infringement, then any patent licenses 87 | granted to You under this License for that Work shall terminate 88 | as of the date such litigation is filed. 89 | 90 | 4. Redistribution. You may reproduce and distribute copies of the 91 | Work or Derivative Works thereof in any medium, with or without 92 | modifications, and in Source or Object form, provided that You 93 | meet the following conditions: 94 | 95 | (a) You must give any other recipients of the Work or 96 | Derivative Works a copy of this License; and 97 | 98 | (b) You must cause any modified files to carry prominent notices 99 | stating that You changed the files; and 100 | 101 | (c) You must retain, in the Source form of any Derivative Works 102 | that You distribute, all copyright, patent, trademark, and 103 | attribution notices from the Source form of the Work, 104 | excluding those notices that do not pertain to any part of 105 | the Derivative Works; and 106 | 107 | (d) If the Work includes a "NOTICE" text file as part of its 108 | distribution, then any Derivative Works that You distribute must 109 | include a readable copy of the attribution notices contained 110 | within such NOTICE file, excluding those notices that do not 111 | pertain to any part of the Derivative Works, in at least one 112 | of the following places: within a NOTICE text file distributed 113 | as part of the Derivative Works; within the Source form or 114 | documentation, if provided along with the Derivative Works; or, 115 | within a display generated by the Derivative Works, if and 116 | wherever such third-party notices normally appear. The contents 117 | of the NOTICE file are for informational purposes only and 118 | do not modify the License. You may add Your own attribution 119 | notices within Derivative Works that You distribute, alongside 120 | or as an addendum to the NOTICE text from the Work, provided 121 | that such additional attribution notices cannot be construed 122 | as modifying the License. 123 | 124 | You may add Your own copyright statement to Your modifications and 125 | may provide additional or different license terms and conditions 126 | for use, reproduction, or distribution of Your modifications, or 127 | for any such Derivative Works as a whole, provided Your use, 128 | reproduction, and distribution of the Work otherwise complies with 129 | the conditions stated in this License. 130 | 131 | 5. Submission of Contributions. Unless You explicitly state otherwise, 132 | any Contribution intentionally submitted for inclusion in the Work 133 | by You to the Licensor shall be under the terms and conditions of 134 | this License, without any additional terms or conditions. 135 | Notwithstanding the above, nothing herein shall supersede or modify 136 | the terms of any separate license agreement you may have executed 137 | with Licensor regarding such Contributions. 138 | 139 | 6. Trademarks. This License does not grant permission to use the trade 140 | names, trademarks, service marks, or product names of the Licensor, 141 | except as required for reasonable and customary use in describing the 142 | origin of the Work and reproducing the content of the NOTICE file. 143 | 144 | 7. Disclaimer of Warranty. Unless required by applicable law or 145 | agreed to in writing, Licensor provides the Work (and each 146 | Contributor provides its Contributions) on an "AS IS" BASIS, 147 | WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or 148 | implied, including, without limitation, any warranties or conditions 149 | of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A 150 | PARTICULAR PURPOSE. You are solely responsible for determining the 151 | appropriateness of using or redistributing the Work and assume any 152 | risks associated with Your exercise of permissions under this License. 153 | 154 | 8. Limitation of Liability. In no event and under no legal theory, 155 | whether in tort (including negligence), contract, or otherwise, 156 | unless required by applicable law (such as deliberate and grossly 157 | negligent acts) or agreed to in writing, shall any Contributor be 158 | liable to You for damages, including any direct, indirect, special, 159 | incidental, or consequential damages of any character arising as a 160 | result of this License or out of the use or inability to use the 161 | Work (including but not limited to damages for loss of goodwill, 162 | work stoppage, computer failure or malfunction, or any and all 163 | other commercial damages or losses), even if such Contributor 164 | has been advised of the possibility of such damages. 165 | 166 | 9. Accepting Warranty or Additional Liability. While redistributing 167 | the Work or Derivative Works thereof, You may choose to offer, 168 | and charge a fee for, acceptance of support, warranty, indemnity, 169 | or other liability obligations and/or rights consistent with this 170 | License. However, in accepting such obligations, You may act only 171 | on Your own behalf and on Your sole responsibility, not on behalf 172 | of any other Contributor, and only if You agree to indemnify, 173 | defend, and hold each Contributor harmless for any liability 174 | incurred by, or claims asserted against, such Contributor by reason 175 | of your accepting any such warranty or additional liability. 176 | 177 | END OF TERMS AND CONDITIONS 178 | 179 | APPENDIX: How to apply the Apache License to your work. 180 | 181 | To apply the Apache License to your work, attach the following 182 | boilerplate notice, with the fields enclosed by brackets "[]" 183 | replaced with your own identifying information. (Don't include 184 | the brackets!) The text should be enclosed in the appropriate 185 | comment syntax for the file format. We also recommend that a 186 | file or class name and description of purpose be included on the 187 | same "printed page" as the copyright notice for easier 188 | identification within third-party archives. 189 | 190 | Copyright [yyyy] [name of copyright owner] 191 | 192 | Licensed under the Apache License, Version 2.0 (the "License"); 193 | you may not use this file except in compliance with the License. 194 | You may obtain a copy of the License at 195 | 196 | http://www.apache.org/licenses/LICENSE-2.0 197 | 198 | Unless required by applicable law or agreed to in writing, software 199 | distributed under the License is distributed on an "AS IS" BASIS, 200 | WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 201 | See the License for the specific language governing permissions and 202 | limitations under the License. -------------------------------------------------------------------------------- /skills/algorithmic-art/LICENSE.txt: -------------------------------------------------------------------------------- 1 | 2 | Apache License 3 | Version 2.0, January 2004 4 | http://www.apache.org/licenses/ 5 | 6 | TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION 7 | 8 | 1. Definitions. 9 | 10 | "License" shall mean the terms and conditions for use, reproduction, 11 | and distribution as defined by Sections 1 through 9 of this document. 12 | 13 | "Licensor" shall mean the copyright owner or entity authorized by 14 | the copyright owner that is granting the License. 15 | 16 | "Legal Entity" shall mean the union of the acting entity and all 17 | other entities that control, are controlled by, or are under common 18 | control with that entity. For the purposes of this definition, 19 | "control" means (i) the power, direct or indirect, to cause the 20 | direction or management of such entity, whether by contract or 21 | otherwise, or (ii) ownership of fifty percent (50%) or more of the 22 | outstanding shares, or (iii) beneficial ownership of such entity. 23 | 24 | "You" (or "Your") shall mean an individual or Legal Entity 25 | exercising permissions granted by this License. 26 | 27 | "Source" form shall mean the preferred form for making modifications, 28 | including but not limited to software source code, documentation 29 | source, and configuration files. 30 | 31 | "Object" form shall mean any form resulting from mechanical 32 | transformation or translation of a Source form, including but 33 | not limited to compiled object code, generated documentation, 34 | and conversions to other media types. 35 | 36 | "Work" shall mean the work of authorship, whether in Source or 37 | Object form, made available under the License, as indicated by a 38 | copyright notice that is included in or attached to the work 39 | (an example is provided in the Appendix below). 40 | 41 | "Derivative Works" shall mean any work, whether in Source or Object 42 | form, that is based on (or derived from) the Work and for which the 43 | editorial revisions, annotations, elaborations, or other modifications 44 | represent, as a whole, an original work of authorship. For the purposes 45 | of this License, Derivative Works shall not include works that remain 46 | separable from, or merely link (or bind by name) to the interfaces of, 47 | the Work and Derivative Works thereof. 48 | 49 | "Contribution" shall mean any work of authorship, including 50 | the original version of the Work and any modifications or additions 51 | to that Work or Derivative Works thereof, that is intentionally 52 | submitted to Licensor for inclusion in the Work by the copyright owner 53 | or by an individual or Legal Entity authorized to submit on behalf of 54 | the copyright owner. For the purposes of this definition, "submitted" 55 | means any form of electronic, verbal, or written communication sent 56 | to the Licensor or its representatives, including but not limited to 57 | communication on electronic mailing lists, source code control systems, 58 | and issue tracking systems that are managed by, or on behalf of, the 59 | Licensor for the purpose of discussing and improving the Work, but 60 | excluding communication that is conspicuously marked or otherwise 61 | designated in writing by the copyright owner as "Not a Contribution." 62 | 63 | "Contributor" shall mean Licensor and any individual or Legal Entity 64 | on behalf of whom a Contribution has been received by Licensor and 65 | subsequently incorporated within the Work. 66 | 67 | 2. Grant of Copyright License. Subject to the terms and conditions of 68 | this License, each Contributor hereby grants to You a perpetual, 69 | worldwide, non-exclusive, no-charge, royalty-free, irrevocable 70 | copyright license to reproduce, prepare Derivative Works of, 71 | publicly display, publicly perform, sublicense, and distribute the 72 | Work and such Derivative Works in Source or Object form. 73 | 74 | 3. Grant of Patent License. Subject to the terms and conditions of 75 | this License, each Contributor hereby grants to You a perpetual, 76 | worldwide, non-exclusive, no-charge, royalty-free, irrevocable 77 | (except as stated in this section) patent license to make, have made, 78 | use, offer to sell, sell, import, and otherwise transfer the Work, 79 | where such license applies only to those patent claims licensable 80 | by such Contributor that are necessarily infringed by their 81 | Contribution(s) alone or by combination of their Contribution(s) 82 | with the Work to which such Contribution(s) was submitted. If You 83 | institute patent litigation against any entity (including a 84 | cross-claim or counterclaim in a lawsuit) alleging that the Work 85 | or a Contribution incorporated within the Work constitutes direct 86 | or contributory patent infringement, then any patent licenses 87 | granted to You under this License for that Work shall terminate 88 | as of the date such litigation is filed. 89 | 90 | 4. Redistribution. You may reproduce and distribute copies of the 91 | Work or Derivative Works thereof in any medium, with or without 92 | modifications, and in Source or Object form, provided that You 93 | meet the following conditions: 94 | 95 | (a) You must give any other recipients of the Work or 96 | Derivative Works a copy of this License; and 97 | 98 | (b) You must cause any modified files to carry prominent notices 99 | stating that You changed the files; and 100 | 101 | (c) You must retain, in the Source form of any Derivative Works 102 | that You distribute, all copyright, patent, trademark, and 103 | attribution notices from the Source form of the Work, 104 | excluding those notices that do not pertain to any part of 105 | the Derivative Works; and 106 | 107 | (d) If the Work includes a "NOTICE" text file as part of its 108 | distribution, then any Derivative Works that You distribute must 109 | include a readable copy of the attribution notices contained 110 | within such NOTICE file, excluding those notices that do not 111 | pertain to any part of the Derivative Works, in at least one 112 | of the following places: within a NOTICE text file distributed 113 | as part of the Derivative Works; within the Source form or 114 | documentation, if provided along with the Derivative Works; or, 115 | within a display generated by the Derivative Works, if and 116 | wherever such third-party notices normally appear. The contents 117 | of the NOTICE file are for informational purposes only and 118 | do not modify the License. You may add Your own attribution 119 | notices within Derivative Works that You distribute, alongside 120 | or as an addendum to the NOTICE text from the Work, provided 121 | that such additional attribution notices cannot be construed 122 | as modifying the License. 123 | 124 | You may add Your own copyright statement to Your modifications and 125 | may provide additional or different license terms and conditions 126 | for use, reproduction, or distribution of Your modifications, or 127 | for any such Derivative Works as a whole, provided Your use, 128 | reproduction, and distribution of the Work otherwise complies with 129 | the conditions stated in this License. 130 | 131 | 5. Submission of Contributions. Unless You explicitly state otherwise, 132 | any Contribution intentionally submitted for inclusion in the Work 133 | by You to the Licensor shall be under the terms and conditions of 134 | this License, without any additional terms or conditions. 135 | Notwithstanding the above, nothing herein shall supersede or modify 136 | the terms of any separate license agreement you may have executed 137 | with Licensor regarding such Contributions. 138 | 139 | 6. Trademarks. This License does not grant permission to use the trade 140 | names, trademarks, service marks, or product names of the Licensor, 141 | except as required for reasonable and customary use in describing the 142 | origin of the Work and reproducing the content of the NOTICE file. 143 | 144 | 7. Disclaimer of Warranty. Unless required by applicable law or 145 | agreed to in writing, Licensor provides the Work (and each 146 | Contributor provides its Contributions) on an "AS IS" BASIS, 147 | WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or 148 | implied, including, without limitation, any warranties or conditions 149 | of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A 150 | PARTICULAR PURPOSE. You are solely responsible for determining the 151 | appropriateness of using or redistributing the Work and assume any 152 | risks associated with Your exercise of permissions under this License. 153 | 154 | 8. Limitation of Liability. In no event and under no legal theory, 155 | whether in tort (including negligence), contract, or otherwise, 156 | unless required by applicable law (such as deliberate and grossly 157 | negligent acts) or agreed to in writing, shall any Contributor be 158 | liable to You for damages, including any direct, indirect, special, 159 | incidental, or consequential damages of any character arising as a 160 | result of this License or out of the use or inability to use the 161 | Work (including but not limited to damages for loss of goodwill, 162 | work stoppage, computer failure or malfunction, or any and all 163 | other commercial damages or losses), even if such Contributor 164 | has been advised of the possibility of such damages. 165 | 166 | 9. Accepting Warranty or Additional Liability. While redistributing 167 | the Work or Derivative Works thereof, You may choose to offer, 168 | and charge a fee for, acceptance of support, warranty, indemnity, 169 | or other liability obligations and/or rights consistent with this 170 | License. However, in accepting such obligations, You may act only 171 | on Your own behalf and on Your sole responsibility, not on behalf 172 | of any other Contributor, and only if You agree to indemnify, 173 | defend, and hold each Contributor harmless for any liability 174 | incurred by, or claims asserted against, such Contributor by reason 175 | of your accepting any such warranty or additional liability. 176 | 177 | END OF TERMS AND CONDITIONS 178 | 179 | APPENDIX: How to apply the Apache License to your work. 180 | 181 | To apply the Apache License to your work, attach the following 182 | boilerplate notice, with the fields enclosed by brackets "[]" 183 | replaced with your own identifying information. (Don't include 184 | the brackets!) The text should be enclosed in the appropriate 185 | comment syntax for the file format. We also recommend that a 186 | file or class name and description of purpose be included on the 187 | same "printed page" as the copyright notice for easier 188 | identification within third-party archives. 189 | 190 | Copyright [yyyy] [name of copyright owner] 191 | 192 | Licensed under the Apache License, Version 2.0 (the "License"); 193 | you may not use this file except in compliance with the License. 194 | You may obtain a copy of the License at 195 | 196 | http://www.apache.org/licenses/LICENSE-2.0 197 | 198 | Unless required by applicable law or agreed to in writing, software 199 | distributed under the License is distributed on an "AS IS" BASIS, 200 | WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 201 | See the License for the specific language governing permissions and 202 | limitations under the License. -------------------------------------------------------------------------------- /skills/skill-creator/scripts/init_skill.py: -------------------------------------------------------------------------------- 1 | #!/usr/bin/env python3 2 | """ 3 | Skill Initializer - Creates a new skill from template 4 | 5 | Usage: 6 | init_skill.py --path 7 | 8 | Examples: 9 | init_skill.py my-new-skill --path skills/public 10 | init_skill.py my-api-helper --path skills/private 11 | init_skill.py custom-skill --path /custom/location 12 | """ 13 | 14 | import sys 15 | from pathlib import Path 16 | 17 | 18 | SKILL_TEMPLATE = """--- 19 | name: {skill_name} 20 | description: [TODO: Complete and informative explanation of what the skill does and when to use it. Include WHEN to use this skill - specific scenarios, file types, or tasks that trigger it.] 21 | --- 22 | 23 | # {skill_title} 24 | 25 | ## Overview 26 | 27 | [TODO: 1-2 sentences explaining what this skill enables] 28 | 29 | ## Structuring This Skill 30 | 31 | [TODO: Choose the structure that best fits this skill's purpose. Common patterns: 32 | 33 | **1. Workflow-Based** (best for sequential processes) 34 | - Works well when there are clear step-by-step procedures 35 | - Example: DOCX skill with "Workflow Decision Tree" → "Reading" → "Creating" → "Editing" 36 | - Structure: ## Overview → ## Workflow Decision Tree → ## Step 1 → ## Step 2... 37 | 38 | **2. Task-Based** (best for tool collections) 39 | - Works well when the skill offers different operations/capabilities 40 | - Example: PDF skill with "Quick Start" → "Merge PDFs" → "Split PDFs" → "Extract Text" 41 | - Structure: ## Overview → ## Quick Start → ## Task Category 1 → ## Task Category 2... 42 | 43 | **3. Reference/Guidelines** (best for standards or specifications) 44 | - Works well for brand guidelines, coding standards, or requirements 45 | - Example: Brand styling with "Brand Guidelines" → "Colors" → "Typography" → "Features" 46 | - Structure: ## Overview → ## Guidelines → ## Specifications → ## Usage... 47 | 48 | **4. Capabilities-Based** (best for integrated systems) 49 | - Works well when the skill provides multiple interrelated features 50 | - Example: Product Management with "Core Capabilities" → numbered capability list 51 | - Structure: ## Overview → ## Core Capabilities → ### 1. Feature → ### 2. Feature... 52 | 53 | Patterns can be mixed and matched as needed. Most skills combine patterns (e.g., start with task-based, add workflow for complex operations). 54 | 55 | Delete this entire "Structuring This Skill" section when done - it's just guidance.] 56 | 57 | ## [TODO: Replace with the first main section based on chosen structure] 58 | 59 | [TODO: Add content here. See examples in existing skills: 60 | - Code samples for technical skills 61 | - Decision trees for complex workflows 62 | - Concrete examples with realistic user requests 63 | - References to scripts/templates/references as needed] 64 | 65 | ## Resources 66 | 67 | This skill includes example resource directories that demonstrate how to organize different types of bundled resources: 68 | 69 | ### scripts/ 70 | Executable code (Python/Bash/etc.) that can be run directly to perform specific operations. 71 | 72 | **Examples from other skills:** 73 | - PDF skill: `fill_fillable_fields.py`, `extract_form_field_info.py` - utilities for PDF manipulation 74 | - DOCX skill: `document.py`, `utilities.py` - Python modules for document processing 75 | 76 | **Appropriate for:** Python scripts, shell scripts, or any executable code that performs automation, data processing, or specific operations. 77 | 78 | **Note:** Scripts may be executed without loading into context, but can still be read by Claude for patching or environment adjustments. 79 | 80 | ### references/ 81 | Documentation and reference material intended to be loaded into context to inform Claude's process and thinking. 82 | 83 | **Examples from other skills:** 84 | - Product management: `communication.md`, `context_building.md` - detailed workflow guides 85 | - BigQuery: API reference documentation and query examples 86 | - Finance: Schema documentation, company policies 87 | 88 | **Appropriate for:** In-depth documentation, API references, database schemas, comprehensive guides, or any detailed information that Claude should reference while working. 89 | 90 | ### assets/ 91 | Files not intended to be loaded into context, but rather used within the output Claude produces. 92 | 93 | **Examples from other skills:** 94 | - Brand styling: PowerPoint template files (.pptx), logo files 95 | - Frontend builder: HTML/React boilerplate project directories 96 | - Typography: Font files (.ttf, .woff2) 97 | 98 | **Appropriate for:** Templates, boilerplate code, document templates, images, icons, fonts, or any files meant to be copied or used in the final output. 99 | 100 | --- 101 | 102 | **Any unneeded directories can be deleted.** Not every skill requires all three types of resources. 103 | """ 104 | 105 | EXAMPLE_SCRIPT = '''#!/usr/bin/env python3 106 | """ 107 | Example helper script for {skill_name} 108 | 109 | This is a placeholder script that can be executed directly. 110 | Replace with actual implementation or delete if not needed. 111 | 112 | Example real scripts from other skills: 113 | - pdf/scripts/fill_fillable_fields.py - Fills PDF form fields 114 | - pdf/scripts/convert_pdf_to_images.py - Converts PDF pages to images 115 | """ 116 | 117 | def main(): 118 | print("This is an example script for {skill_name}") 119 | # TODO: Add actual script logic here 120 | # This could be data processing, file conversion, API calls, etc. 121 | 122 | if __name__ == "__main__": 123 | main() 124 | ''' 125 | 126 | EXAMPLE_REFERENCE = """# Reference Documentation for {skill_title} 127 | 128 | This is a placeholder for detailed reference documentation. 129 | Replace with actual reference content or delete if not needed. 130 | 131 | Example real reference docs from other skills: 132 | - product-management/references/communication.md - Comprehensive guide for status updates 133 | - product-management/references/context_building.md - Deep-dive on gathering context 134 | - bigquery/references/ - API references and query examples 135 | 136 | ## When Reference Docs Are Useful 137 | 138 | Reference docs are ideal for: 139 | - Comprehensive API documentation 140 | - Detailed workflow guides 141 | - Complex multi-step processes 142 | - Information too lengthy for main SKILL.md 143 | - Content that's only needed for specific use cases 144 | 145 | ## Structure Suggestions 146 | 147 | ### API Reference Example 148 | - Overview 149 | - Authentication 150 | - Endpoints with examples 151 | - Error codes 152 | - Rate limits 153 | 154 | ### Workflow Guide Example 155 | - Prerequisites 156 | - Step-by-step instructions 157 | - Common patterns 158 | - Troubleshooting 159 | - Best practices 160 | """ 161 | 162 | EXAMPLE_ASSET = """# Example Asset File 163 | 164 | This placeholder represents where asset files would be stored. 165 | Replace with actual asset files (templates, images, fonts, etc.) or delete if not needed. 166 | 167 | Asset files are NOT intended to be loaded into context, but rather used within 168 | the output Claude produces. 169 | 170 | Example asset files from other skills: 171 | - Brand guidelines: logo.png, slides_template.pptx 172 | - Frontend builder: hello-world/ directory with HTML/React boilerplate 173 | - Typography: custom-font.ttf, font-family.woff2 174 | - Data: sample_data.csv, test_dataset.json 175 | 176 | ## Common Asset Types 177 | 178 | - Templates: .pptx, .docx, boilerplate directories 179 | - Images: .png, .jpg, .svg, .gif 180 | - Fonts: .ttf, .otf, .woff, .woff2 181 | - Boilerplate code: Project directories, starter files 182 | - Icons: .ico, .svg 183 | - Data files: .csv, .json, .xml, .yaml 184 | 185 | Note: This is a text placeholder. Actual assets can be any file type. 186 | """ 187 | 188 | 189 | def title_case_skill_name(skill_name): 190 | """Convert hyphenated skill name to Title Case for display.""" 191 | return ' '.join(word.capitalize() for word in skill_name.split('-')) 192 | 193 | 194 | def init_skill(skill_name, path): 195 | """ 196 | Initialize a new skill directory with template SKILL.md. 197 | 198 | Args: 199 | skill_name: Name of the skill 200 | path: Path where the skill directory should be created 201 | 202 | Returns: 203 | Path to created skill directory, or None if error 204 | """ 205 | # Determine skill directory path 206 | skill_dir = Path(path).resolve() / skill_name 207 | 208 | # Check if directory already exists 209 | if skill_dir.exists(): 210 | print(f"❌ Error: Skill directory already exists: {skill_dir}") 211 | return None 212 | 213 | # Create skill directory 214 | try: 215 | skill_dir.mkdir(parents=True, exist_ok=False) 216 | print(f"✅ Created skill directory: {skill_dir}") 217 | except Exception as e: 218 | print(f"❌ Error creating directory: {e}") 219 | return None 220 | 221 | # Create SKILL.md from template 222 | skill_title = title_case_skill_name(skill_name) 223 | skill_content = SKILL_TEMPLATE.format( 224 | skill_name=skill_name, 225 | skill_title=skill_title 226 | ) 227 | 228 | skill_md_path = skill_dir / 'SKILL.md' 229 | try: 230 | skill_md_path.write_text(skill_content) 231 | print("✅ Created SKILL.md") 232 | except Exception as e: 233 | print(f"❌ Error creating SKILL.md: {e}") 234 | return None 235 | 236 | # Create resource directories with example files 237 | try: 238 | # Create scripts/ directory with example script 239 | scripts_dir = skill_dir / 'scripts' 240 | scripts_dir.mkdir(exist_ok=True) 241 | example_script = scripts_dir / 'example.py' 242 | example_script.write_text(EXAMPLE_SCRIPT.format(skill_name=skill_name)) 243 | example_script.chmod(0o755) 244 | print("✅ Created scripts/example.py") 245 | 246 | # Create references/ directory with example reference doc 247 | references_dir = skill_dir / 'references' 248 | references_dir.mkdir(exist_ok=True) 249 | example_reference = references_dir / 'api_reference.md' 250 | example_reference.write_text(EXAMPLE_REFERENCE.format(skill_title=skill_title)) 251 | print("✅ Created references/api_reference.md") 252 | 253 | # Create assets/ directory with example asset placeholder 254 | assets_dir = skill_dir / 'assets' 255 | assets_dir.mkdir(exist_ok=True) 256 | example_asset = assets_dir / 'example_asset.txt' 257 | example_asset.write_text(EXAMPLE_ASSET) 258 | print("✅ Created assets/example_asset.txt") 259 | except Exception as e: 260 | print(f"❌ Error creating resource directories: {e}") 261 | return None 262 | 263 | # Print next steps 264 | print(f"\n✅ Skill '{skill_name}' initialized successfully at {skill_dir}") 265 | print("\nNext steps:") 266 | print("1. Edit SKILL.md to complete the TODO items and update the description") 267 | print("2. Customize or delete the example files in scripts/, references/, and assets/") 268 | print("3. Run the validator when ready to check the skill structure") 269 | 270 | return skill_dir 271 | 272 | 273 | def main(): 274 | if len(sys.argv) < 4 or sys.argv[2] != '--path': 275 | print("Usage: init_skill.py --path ") 276 | print("\nSkill name requirements:") 277 | print(" - Hyphen-case identifier (e.g., 'data-analyzer')") 278 | print(" - Lowercase letters, digits, and hyphens only") 279 | print(" - Max 40 characters") 280 | print(" - Must match directory name exactly") 281 | print("\nExamples:") 282 | print(" init_skill.py my-new-skill --path skills/public") 283 | print(" init_skill.py my-api-helper --path skills/private") 284 | print(" init_skill.py custom-skill --path /custom/location") 285 | sys.exit(1) 286 | 287 | skill_name = sys.argv[1] 288 | path = sys.argv[3] 289 | 290 | print(f"🚀 Initializing skill: {skill_name}") 291 | print(f" Location: {path}") 292 | print() 293 | 294 | result = init_skill(skill_name, path) 295 | 296 | if result: 297 | sys.exit(0) 298 | else: 299 | sys.exit(1) 300 | 301 | 302 | if __name__ == "__main__": 303 | main() 304 | -------------------------------------------------------------------------------- /skills/skill-creator/SKILL.md: -------------------------------------------------------------------------------- 1 | --- 2 | name: skill-creator 3 | description: Guide for creating effective skills. This skill should be used when users want to create a new skill (or update an existing skill) that extends Claude's capabilities with specialized knowledge, workflows, or tool integrations. 4 | license: Complete terms in LICENSE.txt 5 | --- 6 | 7 | # Skill Creator 8 | 9 | This skill provides guidance for creating effective skills. 10 | 11 | ## About Skills 12 | 13 | Skills are modular, self-contained packages that extend Claude's capabilities by providing 14 | specialized knowledge, workflows, and tools. Think of them as "onboarding guides" for specific 15 | domains or tasks—they transform Claude from a general-purpose agent into a specialized agent 16 | equipped with procedural knowledge that no model can fully possess. 17 | 18 | ### What Skills Provide 19 | 20 | 1. Specialized workflows - Multi-step procedures for specific domains 21 | 2. Tool integrations - Instructions for working with specific file formats or APIs 22 | 3. Domain expertise - Company-specific knowledge, schemas, business logic 23 | 4. Bundled resources - Scripts, references, and assets for complex and repetitive tasks 24 | 25 | ### Anatomy of a Skill 26 | 27 | Every skill consists of a required SKILL.md file and optional bundled resources: 28 | 29 | ``` 30 | skill-name/ 31 | ├── SKILL.md (required) 32 | │ ├── YAML frontmatter metadata (required) 33 | │ │ ├── name: (required) 34 | │ │ └── description: (required) 35 | │ └── Markdown instructions (required) 36 | └── Bundled Resources (optional) 37 | ├── scripts/ - Executable code (Python/Bash/etc.) 38 | ├── references/ - Documentation intended to be loaded into context as needed 39 | └── assets/ - Files used in output (templates, icons, fonts, etc.) 40 | ``` 41 | 42 | #### SKILL.md (required) 43 | 44 | **Metadata Quality:** The `name` and `description` in YAML frontmatter determine when Claude will use the skill. Be specific about what the skill does and when to use it. Use the third-person (e.g. "This skill should be used when..." instead of "Use this skill when..."). 45 | 46 | #### Bundled Resources (optional) 47 | 48 | ##### Scripts (`scripts/`) 49 | 50 | Executable code (Python/Bash/etc.) for tasks that require deterministic reliability or are repeatedly rewritten. 51 | 52 | - **When to include**: When the same code is being rewritten repeatedly or deterministic reliability is needed 53 | - **Example**: `scripts/rotate_pdf.py` for PDF rotation tasks 54 | - **Benefits**: Token efficient, deterministic, may be executed without loading into context 55 | - **Note**: Scripts may still need to be read by Claude for patching or environment-specific adjustments 56 | 57 | ##### References (`references/`) 58 | 59 | Documentation and reference material intended to be loaded as needed into context to inform Claude's process and thinking. 60 | 61 | - **When to include**: For documentation that Claude should reference while working 62 | - **Examples**: `references/finance.md` for financial schemas, `references/mnda.md` for company NDA template, `references/policies.md` for company policies, `references/api_docs.md` for API specifications 63 | - **Use cases**: Database schemas, API documentation, domain knowledge, company policies, detailed workflow guides 64 | - **Benefits**: Keeps SKILL.md lean, loaded only when Claude determines it's needed 65 | - **Best practice**: If files are large (>10k words), include grep search patterns in SKILL.md 66 | - **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. 67 | 68 | ##### Assets (`assets/`) 69 | 70 | Files not intended to be loaded into context, but rather used within the output Claude produces. 71 | 72 | - **When to include**: When the skill needs files that will be used in the final output 73 | - **Examples**: `assets/logo.png` for brand assets, `assets/slides.pptx` for PowerPoint templates, `assets/frontend-template/` for HTML/React boilerplate, `assets/font.ttf` for typography 74 | - **Use cases**: Templates, images, icons, boilerplate code, fonts, sample documents that get copied or modified 75 | - **Benefits**: Separates output resources from documentation, enables Claude to use files without loading them into context 76 | 77 | ### Progressive Disclosure Design Principle 78 | 79 | Skills use a three-level loading system to manage context efficiently: 80 | 81 | 1. **Metadata (name + description)** - Always in context (~100 words) 82 | 2. **SKILL.md body** - When skill triggers (<5k words) 83 | 3. **Bundled resources** - As needed by Claude (Unlimited*) 84 | 85 | *Unlimited because scripts can be executed without reading into context window. 86 | 87 | ## Skill Creation Process 88 | 89 | To create a skill, follow the "Skill Creation Process" in order, skipping steps only if there is a clear reason why they are not applicable. 90 | 91 | ### Step 1: Understanding the Skill with Concrete Examples 92 | 93 | Skip this step only when the skill's usage patterns are already clearly understood. It remains valuable even when working with an existing skill. 94 | 95 | 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. 96 | 97 | For example, when building an image-editor skill, relevant questions include: 98 | 99 | - "What functionality should the image-editor skill support? Editing, rotating, anything else?" 100 | - "Can you give some examples of how this skill would be used?" 101 | - "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?" 102 | - "What would a user say that should trigger this skill?" 103 | 104 | 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. 105 | 106 | Conclude this step when there is a clear sense of the functionality the skill should support. 107 | 108 | ### Step 2: Planning the Reusable Skill Contents 109 | 110 | To turn concrete examples into an effective skill, analyze each example by: 111 | 112 | 1. Considering how to execute on the example from scratch 113 | 2. Identifying what scripts, references, and assets would be helpful when executing these workflows repeatedly 114 | 115 | Example: When building a `pdf-editor` skill to handle queries like "Help me rotate this PDF," the analysis shows: 116 | 117 | 1. Rotating a PDF requires re-writing the same code each time 118 | 2. A `scripts/rotate_pdf.py` script would be helpful to store in the skill 119 | 120 | 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: 121 | 122 | 1. Writing a frontend webapp requires the same boilerplate HTML/React each time 123 | 2. An `assets/hello-world/` template containing the boilerplate HTML/React project files would be helpful to store in the skill 124 | 125 | Example: When building a `big-query` skill to handle queries like "How many users have logged in today?" the analysis shows: 126 | 127 | 1. Querying BigQuery requires re-discovering the table schemas and relationships each time 128 | 2. A `references/schema.md` file documenting the table schemas would be helpful to store in the skill 129 | 130 | To establish the skill's contents, analyze each concrete example to create a list of the reusable resources to include: scripts, references, and assets. 131 | 132 | ### Step 3: Initializing the Skill 133 | 134 | At this point, it is time to actually create the skill. 135 | 136 | Skip this step only if the skill being developed already exists, and iteration or packaging is needed. In this case, continue to the next step. 137 | 138 | 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. 139 | 140 | Usage: 141 | 142 | ```bash 143 | scripts/init_skill.py --path 144 | ``` 145 | 146 | The script: 147 | 148 | - Creates the skill directory at the specified path 149 | - Generates a SKILL.md template with proper frontmatter and TODO placeholders 150 | - Creates example resource directories: `scripts/`, `references/`, and `assets/` 151 | - Adds example files in each directory that can be customized or deleted 152 | 153 | After initialization, customize or remove the generated SKILL.md and example files as needed. 154 | 155 | ### Step 4: Edit the Skill 156 | 157 | When editing the (newly-generated or existing) skill, remember that the skill is being created for another instance of Claude to use. Focus on including 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. 158 | 159 | #### Start with Reusable Skill Contents 160 | 161 | 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/`. 162 | 163 | Also, delete any example files and directories not needed for the skill. The initialization script creates example files in `scripts/`, `references/`, and `assets/` to demonstrate structure, but most skills won't need all of them. 164 | 165 | #### Update SKILL.md 166 | 167 | **Writing Style:** Write the entire skill using **imperative/infinitive form** (verb-first instructions), not second person. Use objective, instructional language (e.g., "To accomplish X, do Y" rather than "You should do X" or "If you need to do X"). This maintains consistency and clarity for AI consumption. 168 | 169 | To complete SKILL.md, answer the following questions: 170 | 171 | 1. What is the purpose of the skill, in a few sentences? 172 | 2. When should the skill be used? 173 | 3. In practice, how should Claude use the skill? All reusable skill contents developed above should be referenced so that Claude knows how to use them. 174 | 175 | ### Step 5: Packaging a Skill 176 | 177 | Once the skill is ready, it should be packaged into a distributable zip file that gets shared with the user. The packaging process automatically validates the skill first to ensure it meets all requirements: 178 | 179 | ```bash 180 | scripts/package_skill.py 181 | ``` 182 | 183 | Optional output directory specification: 184 | 185 | ```bash 186 | scripts/package_skill.py ./dist 187 | ``` 188 | 189 | The packaging script will: 190 | 191 | 1. **Validate** the skill automatically, checking: 192 | - YAML frontmatter format and required fields 193 | - Skill naming conventions and directory structure 194 | - Description completeness and quality 195 | - File organization and resource references 196 | 197 | 2. **Package** the skill if validation passes, creating a zip file named after the skill (e.g., `my-skill.zip`) that includes all files and maintains the proper directory structure for distribution. 198 | 199 | If validation fails, the script will report the errors and exit without creating a package. Fix any validation errors and run the packaging command again. 200 | 201 | ### Step 6: Iterate 202 | 203 | After testing the skill, users may request improvements. Often this happens right after using the skill, with fresh context of how the skill performed. 204 | 205 | **Iteration workflow:** 206 | 1. Use the skill on real tasks 207 | 2. Notice struggles or inefficiencies 208 | 3. Identify how SKILL.md or bundled resources should be updated 209 | 4. Implement changes and test again 210 | -------------------------------------------------------------------------------- /skills/aerospace-config/SKILL.md: -------------------------------------------------------------------------------- 1 | --- 2 | name: aerospace-config 3 | description: Complete AeroSpace tiling window manager configuration assistant for macOS. Use for any AeroSpace configuration task including keybindings, workspace management, window rules, layouts (BSP, columns, rows, accordion), focus behavior, gaps, floating windows, app-specific settings, exec commands, or any window management customization. Also use for debugging and troubleshooting AeroSpace issues including log inspection, window state analysis, and diagnosing layout problems. This skill fetches fresh documentation for each request to ensure accurate, up-to-date guidance. 4 | --- 5 | 6 | # AeroSpace Configuration Assistant 7 | 8 | This skill provides comprehensive assistance for configuring AeroSpace, a tiling window manager for macOS. AeroSpace uses TOML for configuration and offers extensive customization for keyboard-driven window management, workspaces, layouts, and window behavior. 9 | 10 | ## Configuration Location 11 | 12 | **Config File:** `/Users/alex/.config/aerospace/aerospace.toml` 13 | 14 | Alternative locations: `~/.aerospace.toml` 15 | 16 | ## Core Principles 17 | 18 | ### ALWAYS Follow This Workflow 19 | 20 | 1. **Read Current Config**: Use Read tool to examine existing configuration 21 | 2. **Fetch Documentation**: Use WebFetch to get current documentation for the specific feature 22 | 3. **Research Thoroughly**: Check multiple doc pages if needed for complex features 23 | 4. **Implement Carefully**: Preserve existing config, validate TOML syntax 24 | 5. **Explain Clearly**: Document what changed and why 25 | 6. **Guide Testing**: Explain how to reload config (`aerospace reload-config`) 26 | 27 | ### Documentation Strategy 28 | 29 | **Never embed documentation text.** Always use WebFetch to retrieve current information from the AeroSpace documentation. 30 | 31 | AeroSpace documentation is comprehensive and continuously updated. The configuration system supports many options across window management, keybindings, and layouts. 32 | 33 | ## Full Configuration Capabilities 34 | 35 | AeroSpace supports configuration across these comprehensive areas. For each request, fetch the relevant documentation: 36 | 37 | ### 1. Getting Started & Overview 38 | - **Installation & Setup**: Initial configuration, first-time setup 39 | - https://nikitabobko.github.io/AeroSpace/guide 40 | - **Default Config**: Understanding the default configuration 41 | - https://nikitabobko.github.io/AeroSpace/goodness#default-config 42 | 43 | ### 2. Keybindings & Modes 44 | - **Key Bindings**: Main mode, custom modes, key syntax 45 | - https://nikitabobko.github.io/AeroSpace/guide#key-bindings 46 | - https://nikitabobko.github.io/AeroSpace/guide#binding-modes 47 | - **Key Syntax**: Modifier keys, key names, key combinations 48 | - https://nikitabobko.github.io/AeroSpace/guide#key-syntax 49 | 50 | ### 3. Window Management 51 | - **Tree Structure**: Understanding the window tree paradigm 52 | - https://nikitabobko.github.io/AeroSpace/guide#tree 53 | - **Layouts**: BSP (Binary Space Partitioning), columns, rows, accordion, tiles 54 | - https://nikitabobko.github.io/AeroSpace/guide#layouts 55 | - **Floating Windows**: Float rules, floating toggle 56 | - https://nikitabobko.github.io/AeroSpace/guide#floating-windows 57 | 58 | ### 4. Workspaces & Monitors 59 | - **Workspaces**: Workspace configuration, assignment, switching 60 | - https://nikitabobko.github.io/AeroSpace/guide#workspaces 61 | - **Multiple Monitors**: Monitor assignment, workspace-to-monitor mapping 62 | - https://nikitabobko.github.io/AeroSpace/guide#multiple-monitors 63 | 64 | ### 5. Application-Specific Rules 65 | - **Window Detection Callbacks**: on-window-detected, app-specific behavior 66 | - https://nikitabobko.github.io/AeroSpace/guide#on-window-detected-callback 67 | - **App Identifiers**: Bundle IDs, window titles for rules 68 | 69 | ### 6. Visual Appearance 70 | - **Gaps**: Inner gaps, outer gaps, per-workspace gaps 71 | - https://nikitabobko.github.io/AeroSpace/guide#gaps 72 | 73 | ### 7. Commands Reference 74 | - **All Commands**: Complete command reference for keybindings and exec 75 | - https://nikitabobko.github.io/AeroSpace/commands 76 | - **Individual Commands**: (fetch specific command pages as needed) 77 | - https://nikitabobko.github.io/AeroSpace/commands#focus 78 | - https://nikitabobko.github.io/AeroSpace/commands#move 79 | - https://nikitabobko.github.io/AeroSpace/commands#resize 80 | - https://nikitabobko.github.io/AeroSpace/commands#workspace 81 | - https://nikitabobko.github.io/AeroSpace/commands#move-node-to-workspace 82 | - https://nikitabobko.github.io/AeroSpace/commands#layout 83 | - https://nikitabobko.github.io/AeroSpace/commands#split 84 | - https://nikitabobko.github.io/AeroSpace/commands#join-with 85 | - https://nikitabobko.github.io/AeroSpace/commands#flatten-workspace-tree 86 | - https://nikitabobko.github.io/AeroSpace/commands#exec-and-forget 87 | - https://nikitabobko.github.io/AeroSpace/commands#mode 88 | - https://nikitabobko.github.io/AeroSpace/commands#reload-config 89 | 90 | ### 8. Configuration Options 91 | - **TOML Configuration**: Full config reference 92 | - https://nikitabobko.github.io/AeroSpace/guide#config-syntax 93 | - **Config Options Reference**: All available configuration options 94 | - https://nikitabobko.github.io/AeroSpace/config-reference 95 | 96 | ### 9. Advanced Features 97 | - **Exec Commands**: Running shell commands, exec-and-forget 98 | - https://nikitabobko.github.io/AeroSpace/commands#exec-and-forget 99 | - **Focus Behavior**: Focus follows window, mouse handling 100 | - **Normalization**: Container normalization options 101 | 102 | ### 10. Troubleshooting & Debugging 103 | - **Troubleshooting Guide**: Common issues, debugging 104 | - https://nikitabobko.github.io/AeroSpace/guide#troubleshooting 105 | - **Config Validation**: Checking config syntax 106 | - **Logs & Debugging**: Finding logs, debug information 107 | 108 | ## Configuration File Structure 109 | 110 | AeroSpace configs use TOML format: 111 | 112 | ```toml 113 | # Start AeroSpace at login 114 | start-at-login = true 115 | 116 | # Gaps between windows 117 | [gaps] 118 | inner.horizontal = 10 119 | inner.vertical = 10 120 | outer.left = 10 121 | outer.bottom = 10 122 | outer.top = 10 123 | outer.right = 10 124 | 125 | # Main mode keybindings 126 | [mode.main.binding] 127 | alt-h = 'focus left' 128 | alt-j = 'focus down' 129 | alt-k = 'focus up' 130 | alt-l = 'focus right' 131 | 132 | # Workspace keybindings 133 | alt-1 = 'workspace 1' 134 | alt-2 = 'workspace 2' 135 | 136 | # Move windows to workspaces 137 | alt-shift-1 = 'move-node-to-workspace 1' 138 | alt-shift-2 = 'move-node-to-workspace 2' 139 | 140 | # Layout commands 141 | alt-slash = 'layout tiles horizontal vertical' 142 | alt-comma = 'layout accordion horizontal vertical' 143 | 144 | # Window detection callbacks 145 | [[on-window-detected]] 146 | if.app-id = 'com.apple.finder' 147 | run = 'layout floating' 148 | ``` 149 | 150 | ## Research Process for Each Request 151 | 152 | When user requests any configuration change: 153 | 154 | 1. **Identify Category**: Determine which configuration area(s) are involved 155 | 2. **Fetch Core Docs**: Get main documentation page for that category 156 | 3. **Fetch Specifics**: If needed, get specific command reference or examples 157 | 4. **Check Commands**: If keybinding involves commands, fetch command documentation 158 | 5. **Verify Syntax**: Check TOML syntax and available options 159 | 6. **Cross-Reference**: Look at related features that might enhance the solution 160 | 161 | ## Implementation Guidelines 162 | 163 | ### Code Quality 164 | - Use clear section organization and comments 165 | - Follow TOML best practices 166 | - Validate syntax before suggesting 167 | - Use consistent indentation 168 | 169 | ### Config Organization 170 | - Group related settings together (gaps, keybindings, rules) 171 | - Add section comments for clarity 172 | - Preserve user's existing organizational structure 173 | - Keep keybindings logically grouped by function 174 | 175 | ### Error Prevention 176 | - Check for config file existence before editing 177 | - Validate that TOML syntax is correct 178 | - Ensure keybinding commands exist 179 | - Verify app bundle IDs for window rules 180 | 181 | ### User Guidance 182 | - Explain what each change does 183 | - Link to relevant documentation pages 184 | - Suggest how to test changes (`aerospace reload-config`) 185 | - Offer related enhancements when appropriate 186 | - Mention keyboard shortcuts in clear format (alt-shift-1) 187 | 188 | ## Common Tasks Quick Reference 189 | 190 | ### Testing Changes 191 | ```bash 192 | aerospace reload-config 193 | ``` 194 | 195 | ### Finding App Bundle IDs 196 | 197 | **Method 1: Using osascript (preferred for known app names)** 198 | ```bash 199 | osascript -e 'id of app "AppName"' 200 | ``` 201 | Example: 202 | ```bash 203 | osascript -e 'id of app "Finder"' 204 | # Returns: com.apple.finder 205 | ``` 206 | 207 | **Method 2: List all running apps** 208 | ```bash 209 | aerospace list-apps 210 | ``` 211 | 212 | **Method 3: Using mdls on the app bundle** 213 | ```bash 214 | mdls -name kMDItemCFBundleIdentifier /Applications/AppName.app 215 | ``` 216 | 217 | ### Listing Windows 218 | 219 | **List all windows:** 220 | ```bash 221 | aerospace list-windows --all 222 | ``` 223 | 224 | **List windows in specific workspace:** 225 | ```bash 226 | aerospace list-windows --workspace TER 227 | ``` 228 | 229 | **List windows as JSON (for detailed analysis):** 230 | ```bash 231 | aerospace list-windows --all --json 232 | ``` 233 | 234 | **Filter windows by app (example for Ghostty):** 235 | ```bash 236 | aerospace list-windows --all --json | python3 -c "import json,sys; data=json.load(sys.stdin); filtered=[w for w in data if 'AppName' in w.get('app-name','')]; print(json.dumps(filtered, indent=2))" 237 | ``` 238 | 239 | **List active workspaces:** 240 | ```bash 241 | aerospace list-workspaces --monitor all --empty no 242 | ``` 243 | 244 | ## Debugging & Log Inspection 245 | 246 | When troubleshooting issues (window resizing, layout problems, unexpected behavior), use these debugging techniques: 247 | 248 | ### Check if AeroSpace is Running 249 | ```bash 250 | pgrep -l AeroSpace && echo "AeroSpace is running" || echo "AeroSpace is NOT running" 251 | ``` 252 | 253 | ### View System Logs 254 | 255 | AeroSpace logs to the macOS unified logging system. Use the `log` command to retrieve logs: 256 | 257 | **Get recent AeroSpace logs (last 30 minutes):** 258 | ```bash 259 | /usr/bin/log show --predicate 'processImagePath CONTAINS "AeroSpace"' --last 30m --info --debug | tail -200 260 | ``` 261 | 262 | **Get logs for specific time period:** 263 | ```bash 264 | /usr/bin/log show --predicate 'processImagePath CONTAINS "AeroSpace"' --last 10m --style compact 265 | ``` 266 | 267 | **Stream live logs (useful during testing):** 268 | ```bash 269 | /usr/bin/log stream --predicate 'processImagePath CONTAINS "AeroSpace"' --style compact 270 | ``` 271 | 272 | Note: Use `/usr/bin/log` with full path to avoid shell interpretation issues. 273 | 274 | ### Debug Windows Session 275 | 276 | To debug a specific problematic window: 277 | 278 | 1. Start debug session: 279 | ```bash 280 | aerospace debug-windows 281 | ``` 282 | 283 | 2. Focus the problematic window 284 | 285 | 3. Run the command again to get results: 286 | ```bash 287 | aerospace debug-windows 288 | ``` 289 | 290 | ### Common Debugging Scenarios 291 | 292 | **Window not floating/tiling as expected:** 293 | 1. List windows to see current state: `aerospace list-windows --workspace WORKSPACE_NAME --json` 294 | 2. Check if on-window-detected rule is correct 295 | 3. Note: Rules only apply to NEW windows - existing windows keep their state 296 | 297 | **Layout issues after config change:** 298 | 1. Reload config: `aerospace reload-config` 299 | 2. Close and reopen the problematic app for new rules to apply 300 | 3. Check logs for any errors 301 | 302 | **App windows behaving unexpectedly:** 303 | 1. Verify app bundle ID: `osascript -e 'id of app "AppName"'` 304 | 2. List all windows from that app to see how AeroSpace perceives them 305 | 3. Some apps (like Ghostty) report tabs as separate windows - this is a known macOS limitation 306 | 307 | ### Debug Mode 308 | ```bash 309 | aerospace enable-debug-mode 310 | ``` 311 | 312 | ## Remember 313 | 314 | - **Never paste documentation** - always use WebFetch 315 | - **Always read config first** - understand existing setup 316 | - **Research thoroughly** - fetch multiple doc pages if needed 317 | - **Explain clearly** - user should understand the changes 318 | - **Link resources** - provide documentation URLs for reference 319 | - **Test guidance** - explain how to verify changes work 320 | 321 | AeroSpace is actively developed. When in doubt, fetch the documentation. 322 | -------------------------------------------------------------------------------- /skills/article-writer/references/example-article.md: -------------------------------------------------------------------------------- 1 | mistakes i made in pricing dev projects 2 | 3 | I’ve been pricing dev projects for years, and early on, I got absolutely destroyed. You can build an API in a week, sure, but if you’re charging peanuts and working yourself into the ground, you’re just a glorified volunteer. I’ve undercharged, over-delivered, and felt like a chump more times than I can count. This isn’t some guru manifesto; it’s what I learned the hard way. If you’re freelancing dev work, maybe my mistakes can save you some pain. 4 | 5 | > You ever quote a project thinking it’ll take a month, and four months later you’re giving discounts just to end the nightmare? 6 | 7 | The fast, explainable pricing template I use now: 8 | 9 | [![Image](https://pbs.twimg.com/media/G3tlZjVW0AEX_qq?format=jpg&name=medium)](https://x.com/alxfazio/article/1980292397616484862/media/1980287950815416321) 10 | 11 | FE = Front-End 12 | 13 | BE = Back-End 14 | 15 | That’s the formula that finally unf-cked my pricing. Took me years of bleeding money to figure it out, but here’s the kicker: it’s not just good for you, clients actually get it. When you break it down like this, they stop seeing you as some random number they’re negotiating and start seeing the logic. They understand why it costs what it costs. Transparency and explainability kill the back-and-forth haggling, and suddenly fixed pricing that made no sense for either of you becomes a real conversation with real numbers. 16 | 17 | Now I’m gonna walk you through exactly how I got there and why each piece matters. Buckle up. 18 | 19 | 20 | 1\. Going Pure Project-Based Without a Clue on Time 21 | 22 | Biggest L of my career: I hated hourly billing like it was the plague. “Nah, I’m results-oriented,” I’d say. Sounds badass, right? Wrong. I’d slap a fixed price on a gig, say 20–30k for what I thought was a quick API build, and then life happens. My schedule’s not full-time on this one client, sh\*t gets random, and boom, it’s dragging on forever. I felt underpaid because I was. Clients love fixed prices ’cause they know the cap, but if you underestimate (and you will, every time as a noob), you’re eating hours for free. Even worse, when a project “could be a week or a month,” I’d just wing it without buffering for the worst case. 23 | 24 | Here’s the thing: You can still pitch fixed pricing if that’s what makes sense for the deal, but do the internal math first. That hourly calculation I showed you? It’s your backbone. It tells you exactly how much to charge so you’re not guessing. And when the client gets squirrely and starts asking “why so much?” or looks unconvinced, you’ve got the breakdown ready to go. You can peel back the curtain and show them: “Here’s my rate, here’s the estimated hours because of X and Y, here’s the multipliers for your company size and project risk.” Suddenly they’re not haggling with a random number, they’re seeing the logic. 25 | 26 | Do the math in your head or on a spreadsheet. Hourly rate times estimated hours, with a range for uncertainty. Price the high end or tier it, and set clear rules like “if we hit this trigger, we re-estimate.” I didn’t, and it bit me hard. 27 | 28 | 29 | 2\. Not Baking in Multipliers or Company Size 30 | 31 | Early days, I’d quote the same for a bootstrapped startup as I would for some enterprise corp with serious funding. Stupid move. Why? ’Cause I didn’t factor in their ability to pay or the project’s real value. Start with your baseline: your hourly rate times how long you think it'll take, then adjust for the actual project factors. Bigger companies usually mean bigger scope, more stakeholders to manage, longer approval chains, stricter compliance requirements. That's not price discrimination, that's pricing the real complexity and risk. I learned this the hard way after getting burned on several deals where I charged a scrappy rate to enterprises who could’ve easily paid triple. 32 | 33 | Eventually I figured out to look at market rates for full-stack devs, calculate the hours, then slap on multipliers for urgency, risk, and project complexity. Enterprise clients bring more complexity: legal reviews, security audits, integration with legacy systems, multiple approval layers. 34 | 35 | Now, finding out a company’s valuation or real budget? That’s the tricky part. Sometimes it’s public info you can dig up in ten minutes: Series B funding, revenue reports, LinkedIn employee count. Other times you’re playing detective, making educated guesses based on their office, their team size, how they talk about money. 36 | 37 | Here's the key though: you're not charging more just because they have money. You're charging more because larger organizations genuinely create more work. More stakeholders to align, longer approval processes, stricter security and compliance requirements, integration with complex existing systems, formal documentation needs, legal reviews. A startup might give you direct access to the founder who makes decisions in a day. An enterprise? You're dealing with procurement, multiple departments, change management processes. That extra cost is real work you're pricing for. 38 | 39 | Here’s a move that changed the game for me: Send a proposal before you send a quote. Not the pricing, just the work. Outline why this project matters to them, what the ROI looks like, what problems it solves. Get them to respond and confirm the value in their own words. Once they’ve told you “yeah, this could save us $500k a year” or “this’ll help us close enterprise deals,” you’ve got gold. Now when you send the quote, it’s anchored to value they already admitted to. They can’t turn around and pretend your number’s too high when they just said the project’s worth ten times that to them. You’re pricing based on a conversation about impact, not pulling numbers out of thin air. Me? I’d lowball to close the deal, then resent it when they nitpicked every line of code. And if you’re pulling in a team (like a front-end collaborator to handle that React mess), don’t forget their costs. Calc each role: their hourly times their hours, roll it into the total. I skipped that once and ate the collab fees myself. 40 | 41 | Now? If it's an enterprise client, I price for the reality of working with them: longer sales cycles, more documentation, security reviews, compliance requirements. Benchmark your rate (front-end, back-end, full-stack: check market rates), multiply by hours, add multipliers for scope, complexity, and organizational overhead. 42 | 43 | This is your Multipliers layer: Company Size/Valuation × Urgency × Risk. Plus accounting for (Other Roles) in your Internal math when you need collaborators. Without this, you’re charging startup rates to enterprise clients. 44 | 45 | 46 | 3\. Giving Discounts for My Own Bad Estimates 47 | 48 | This one still stings. Project goes long, maybe ‘cause the client drags their feet on feedback or life’s randomness hits, and I’d feel guilty. “Eh, it took longer than I thought, here’s a discount.” That’s just me paying to work. Happened on a four-month gig where I was already feeling cheap. Everyone I asked said 20–30k was the going rate, but I undercut myself. Clients who’d been screwed by other devs before? They’d take it, but it left me burnt. Here’s what actually causes delays 99% of the time: the client’s gotta provide sh\*t like context on their business logic, domain knowledge you can’t possibly have, specs from their existing dev team, and feedback on your work as you build. Every single time, they drag their feet on this stuff. So now I map it out upfront: What feedback do you need? What materials? What domain expertise? List every dependency they’re responsible for, discuss it with them so they know it’s real, then bake it into the contract with deadlines. “Client provides API documentation by Day 5. Client reviews milestone 1 within 3 business days.” Make it their obligation with timelines attached. That way, when the project goes long because they ghosted you for two weeks on a critical review, it’s not you eating the cost, it’s them paying for the delay they caused. 49 | 50 | Lesson: Build in buffers for delays. If it overruns ’cause of them, charge more. Transparency kills the guilt. Tell ’em, “This was scoped for X hours, but your delays added Y, so add Z bucks.” Define it upfront in the proposal: if their dependencies slip (feedback, assets, access), we flip to time-and-materials or a change order. No more letting projects run indefinitely on fixed fee. Slap a time window on it, and beyond that, paid retainer or hourly kicks in ’til they get their act together. 51 | 52 | This is your explicit delay/overage clause in the Commercials part of the formula. Define client obligations with deadlines so you’re protected when they cause delays. 53 | 54 | 55 | 4\. Targeting the Wrong Clients 56 | 57 | Half my early gigs were from folks who’d been ghosted or ripped off by some other dev. Sounds like easy wins, right? Not even close. They’re traumatized and cheap. They’d haggle every penny, and I’d cave ’cause I needed the work. Wrong move. Low-paying clients bring drama, endless revisions, scope creep without extra pay. Better to have fewer high-payers who value you. Filter ’em out with solid pricing logic. If they balk at your transparent breakdown (hourly baseline, hours estimate, multipliers), let them walk. Peace of mind beats volume every time. That whole system I showed you? It’s designed to weed out the garbage clients. Few clients paying well beats a ton of clients paying badly every single time. Why? ’Cause low-payers don’t just pay badly, they try to lowball you more over time, never the other way around. They pile on work, expect miracles for pennies, and suddenly you’re juggling five nightmare projects instead of two solid ones. More clients means more chaos, harder to manage, and you’re stretched too thin. Meanwhile, a handful of high-payers who respect your rates? Easier to manage, better relationships, and you actually have bandwidth. 58 | 59 | Here’s the thing about finding trustworthy clients: it’s not some secret handshake or magic network. The main filtering mechanism is price itself. Clients who pay well are trustworthy clients, that’s the pattern I’ve seen over and over. If they’re paying badly, they’re not trustworthy, period. They’ll nickel-and-dime you, ghost on payments, argue over every line item. But when they’re paying premium rates, they respect the work, they respect timelines, they don’t mess around. It’s a long-run game. You build that roster of high-payers one solid project at a time, and each one makes the next easier to land. And be upfront about your availability. If you’re not full-time on their gig, say it in the proposal and align dates and pricing to that. I was vague once, the client assumed 40 hours a week, and it blew up. 60 | 61 | 62 | 5\. No Milestones, Just Upfront and Pray 63 | 64 | My old system: 50% upfront, 50% on delivery. Simple? Sure. Stupid? Absolutely. Projects stretch, clients ghost on feedback, and you’re chasing that last payment while the clock ticks. Scope creep was my nightmare. New features sneak in like “oh, can we add this little thing?” and I’d roll with it to keep ’em happy, turning a quick win into a black hole. I switched to milestones: 50% down, then pay per checkpoint tied to concrete deliverables. Lets you pause if they’re slacking, and cash flows better. Define scope crisply upfront: list what’s in, assumptions (like “you provide API keys by day 3”), and flat-out say new features mean a new estimate or billable hours before I touch ’em. If you’re fast on “easy” stuff that feels complex to them, charge for the value, not your speed. No more letting my intuition lowball the price. Price their perception and impact. 65 | 66 | This is your Commercials structure: 50% upfront + Milestones, clear scope & assumptions, and re-estimate triggers. Milestone payments protect your cash flow, clear scope prevents creep, and re-estimate triggers keep new work from becoming free work. 67 | 68 | 69 | 6\. Ignoring the Hourly Calc Even for Fixed Quotes 70 | 71 | Yeah, I already hit this earlier, but I’m circling back ’cause this one mistake cost me more than all the others combined. I used to dismiss hourly billing ’cause it felt like wage-slaving. Took me way too long to realize: The hourly calc isn’t about billing hourly, it’s your internal compass. Benchmark your rate (front-end, back-end, full-stack, check market rates), multiply by hours, add multipliers for scope or company scale. You don’t always show them the breakdown; most of the time you just pitch the final number. But when they get squirrely and start pushing back or looking unconvinced, that’s when you peel back the curtain: “Here’s my rate, estimated hours ’cause of X/Y, plus multipliers for your situation.” Progressive disclosure. The math protects you from getting screwed. When projects blow up and clients start pointing fingers, you’ve got the receipts: “We went over ’cause of your team’s delays, so that’s extra.” I didn’t do this for years, and my effective rate got diluted to practically minimum wage on some gigs. Now? It’s my secret weapon, always calculated, revealed only when necessary. No more believing slogans like “just charge more” without a system; those catchphrases don’t work without the underlying math. Replace vague advice with first-principles: baseline × hours × multipliers + buffers + milestone plan. This is the bedrock. Everything else is window dressing. 72 | 73 | This ties the whole formula together: (Hourly Rate_FE × Hours_FE) + (Hourly Rate_BE × Hours_BE) + (Other Roles) is your Internal math foundation. Calculate it always, disclose it strategically. Without this backbone, you're just guessing. 74 | 75 | 76 | The Turnaround 77 | 78 | I’m not claiming I’ve got pricing figured out perfectly, but I’ve stopped making these mistakes. Here’s what actually works: 79 | 80 | Do the math, every time. Calculate your hourly rate times estimated hours, add multipliers for project complexity, organizational overhead, and risk. Keep it in your back pocket. Pitch the final number, but reveal the breakdown when clients push back. 81 | 82 | Send proposals before quotes. Get them to tell you the ROI in their own words. Once they’ve admitted the project’s worth half a mil to them, your quote is anchored to real value. 83 | 84 | Map out client dependencies upfront. What feedback do you need? What materials? Put deadlines on their obligations in the contract. When they ghost you for two weeks, it’s their delay, their extra cost. 85 | 86 | Milestone payments over pray-and-hope. 50% down, then payments tied to concrete deliverables. Scope creep gets a new estimate or billable hours before you touch it. 87 | 88 | Filter ruthlessly. Few high-paying clients who respect you beat a swarm of cheapskates every time. The system weeds them out. If they balk at transparent pricing, let them walk. 89 | 90 | It’s not about fearing big numbers. I’ve never had trouble charging premium rates when the system backs it up. But without that system, you’re guessing. Catchphrases like “just charge more” sound good, but they’re useless without the underlying math. 91 | 92 | This approach works. I’m not undercharging anymore, my clients respect the process, and I actually have peace of mind. You can get there too. 93 | 94 | Questions? Drop them below. Need help implementing this? Book a call. My time isn’t free, but it’ll save you from repeating my mistakes. 95 | 96 | Thanks for reading, you degenerates. Stay grinding, but smart this time. 97 | -------------------------------------------------------------------------------- /skills/algorithmic-art/SKILL.md: -------------------------------------------------------------------------------- 1 | --- 2 | name: algorithmic-art 3 | description: Creating algorithmic art using p5.js with seeded randomness and interactive parameter exploration. Use this when users request creating art using code, generative art, algorithmic art, flow fields, or particle systems. Create original algorithmic art rather than copying existing artists' work to avoid copyright violations. 4 | license: Complete terms in LICENSE.txt 5 | --- 6 | 7 | Algorithmic philosophies are computational aesthetic movements that are then expressed through code. Output .md files (philosophy), .html files (interactive viewer), and .js files (generative algorithms). 8 | 9 | This happens in two steps: 10 | 1. Algorithmic Philosophy Creation (.md file) 11 | 2. Express by creating p5.js generative art (.html + .js files) 12 | 13 | First, undertake this task: 14 | 15 | ## ALGORITHMIC PHILOSOPHY CREATION 16 | 17 | To begin, create an ALGORITHMIC PHILOSOPHY (not static images or templates) that will be interpreted through: 18 | - Computational processes, emergent behavior, mathematical beauty 19 | - Seeded randomness, noise fields, organic systems 20 | - Particles, flows, fields, forces 21 | - Parametric variation and controlled chaos 22 | 23 | ### THE CRITICAL UNDERSTANDING 24 | - What is received: Some subtle input or instructions by the user to take into account, but use as a foundation; it should not constrain creative freedom. 25 | - What is created: An algorithmic philosophy/generative aesthetic movement. 26 | - What happens next: The same version receives the philosophy and EXPRESSES IT IN CODE - creating p5.js sketches that are 90% algorithmic generation, 10% essential parameters. 27 | 28 | Consider this approach: 29 | - Write a manifesto for a generative art movement 30 | - The next phase involves writing the algorithm that brings it to life 31 | 32 | The philosophy must emphasize: Algorithmic expression. Emergent behavior. Computational beauty. Seeded variation. 33 | 34 | ### HOW TO GENERATE AN ALGORITHMIC PHILOSOPHY 35 | 36 | **Name the movement** (1-2 words): "Organic Turbulence" / "Quantum Harmonics" / "Emergent Stillness" 37 | 38 | **Articulate the philosophy** (4-6 paragraphs - concise but complete): 39 | 40 | To capture the ALGORITHMIC essence, express how this philosophy manifests through: 41 | - Computational processes and mathematical relationships? 42 | - Noise functions and randomness patterns? 43 | - Particle behaviors and field dynamics? 44 | - Temporal evolution and system states? 45 | - Parametric variation and emergent complexity? 46 | 47 | **CRITICAL GUIDELINES:** 48 | - **Avoid redundancy**: Each algorithmic aspect should be mentioned once. Avoid repeating concepts about noise theory, particle dynamics, or mathematical principles unless adding new depth. 49 | - **Emphasize craftsmanship REPEATEDLY**: The philosophy MUST stress multiple times that the final algorithm should appear as though it took countless hours to develop, was refined with care, and comes from someone at the absolute top of their field. This framing is essential - repeat phrases like "meticulously crafted algorithm," "the product of deep computational expertise," "painstaking optimization," "master-level implementation." 50 | - **Leave creative space**: Be specific about the algorithmic direction, but concise enough that the next Claude has room to make interpretive implementation choices at an extremely high level of craftsmanship. 51 | 52 | The philosophy must guide the next version to express ideas ALGORITHMICALLY, not through static images. Beauty lives in the process, not the final frame. 53 | 54 | ### PHILOSOPHY EXAMPLES 55 | 56 | **"Organic Turbulence"** 57 | Philosophy: Chaos constrained by natural law, order emerging from disorder. 58 | Algorithmic expression: Flow fields driven by layered Perlin noise. Thousands of particles following vector forces, their trails accumulating into organic density maps. Multiple noise octaves create turbulent regions and calm zones. Color emerges from velocity and density - fast particles burn bright, slow ones fade to shadow. The algorithm runs until equilibrium - a meticulously tuned balance where every parameter was refined through countless iterations by a master of computational aesthetics. 59 | 60 | **"Quantum Harmonics"** 61 | Philosophy: Discrete entities exhibiting wave-like interference patterns. 62 | Algorithmic expression: Particles initialized on a grid, each carrying a phase value that evolves through sine waves. When particles are near, their phases interfere - constructive interference creates bright nodes, destructive creates voids. Simple harmonic motion generates complex emergent mandalas. The result of painstaking frequency calibration where every ratio was carefully chosen to produce resonant beauty. 63 | 64 | **"Recursive Whispers"** 65 | Philosophy: Self-similarity across scales, infinite depth in finite space. 66 | Algorithmic expression: Branching structures that subdivide recursively. Each branch slightly randomized but constrained by golden ratios. L-systems or recursive subdivision generate tree-like forms that feel both mathematical and organic. Subtle noise perturbations break perfect symmetry. Line weights diminish with each recursion level. Every branching angle the product of deep mathematical exploration. 67 | 68 | **"Field Dynamics"** 69 | Philosophy: Invisible forces made visible through their effects on matter. 70 | Algorithmic expression: Vector fields constructed from mathematical functions or noise. Particles born at edges, flowing along field lines, dying when they reach equilibrium or boundaries. Multiple fields can attract, repel, or rotate particles. The visualization shows only the traces - ghost-like evidence of invisible forces. A computational dance meticulously choreographed through force balance. 71 | 72 | **"Stochastic Crystallization"** 73 | Philosophy: Random processes crystallizing into ordered structures. 74 | Algorithmic expression: Randomized circle packing or Voronoi tessellation. Start with random points, let them evolve through relaxation algorithms. Cells push apart until equilibrium. Color based on cell size, neighbor count, or distance from center. The organic tiling that emerges feels both random and inevitable. Every seed produces unique crystalline beauty - the mark of a master-level generative algorithm. 75 | 76 | *These are condensed examples. The actual algorithmic philosophy should be 4-6 substantial paragraphs.* 77 | 78 | ### ESSENTIAL PRINCIPLES 79 | - **ALGORITHMIC PHILOSOPHY**: Creating a computational worldview to be expressed through code 80 | - **PROCESS OVER PRODUCT**: Always emphasize that beauty emerges from the algorithm's execution - each run is unique 81 | - **PARAMETRIC EXPRESSION**: Ideas communicate through mathematical relationships, forces, behaviors - not static composition 82 | - **ARTISTIC FREEDOM**: The next Claude interprets the philosophy algorithmically - provide creative implementation room 83 | - **PURE GENERATIVE ART**: This is about making LIVING ALGORITHMS, not static images with randomness 84 | - **EXPERT CRAFTSMANSHIP**: Repeatedly emphasize the final algorithm must feel meticulously crafted, refined through countless iterations, the product of deep expertise by someone at the absolute top of their field in computational aesthetics 85 | 86 | **The algorithmic philosophy should be 4-6 paragraphs long.** Fill it with poetic computational philosophy that brings together the intended vision. Avoid repeating the same points. Output this algorithmic philosophy as a .md file. 87 | 88 | --- 89 | 90 | ## DEDUCING THE CONCEPTUAL SEED 91 | 92 | **CRITICAL STEP**: Before implementing the algorithm, identify the subtle conceptual thread from the original request. 93 | 94 | **THE ESSENTIAL PRINCIPLE**: 95 | The concept is a **subtle, niche reference embedded within the algorithm itself** - not always literal, always sophisticated. Someone familiar with the subject should feel it intuitively, while others simply experience a masterful generative composition. The algorithmic philosophy provides the computational language. The deduced concept provides the soul - the quiet conceptual DNA woven invisibly into parameters, behaviors, and emergence patterns. 96 | 97 | This is **VERY IMPORTANT**: The reference must be so refined that it enhances the work's depth without announcing itself. Think like a jazz musician quoting another song through algorithmic harmony - only those who know will catch it, but everyone appreciates the generative beauty. 98 | 99 | --- 100 | 101 | ## P5.JS IMPLEMENTATION 102 | 103 | With the philosophy AND conceptual framework established, express it through code. Pause to gather thoughts before proceeding. Use only the algorithmic philosophy created and the instructions below. 104 | 105 | ### ⚠️ STEP 0: READ THE TEMPLATE FIRST ⚠️ 106 | 107 | **CRITICAL: BEFORE writing any HTML:** 108 | 109 | 1. **Read** `templates/viewer.html` using the Read tool 110 | 2. **Study** the exact structure, styling, and Anthropic branding 111 | 3. **Use that file as the LITERAL STARTING POINT** - not just inspiration 112 | 4. **Keep all FIXED sections exactly as shown** (header, sidebar structure, Anthropic colors/fonts, seed controls, action buttons) 113 | 5. **Replace only the VARIABLE sections** marked in the file's comments (algorithm, parameters, UI controls for parameters) 114 | 115 | **Avoid:** 116 | - ❌ Creating HTML from scratch 117 | - ❌ Inventing custom styling or color schemes 118 | - ❌ Using system fonts or dark themes 119 | - ❌ Changing the sidebar structure 120 | 121 | **Follow these practices:** 122 | - ✅ Copy the template's exact HTML structure 123 | - ✅ Keep Anthropic branding (Poppins/Lora fonts, light colors, gradient backdrop) 124 | - ✅ Maintain the sidebar layout (Seed → Parameters → Colors? → Actions) 125 | - ✅ Replace only the p5.js algorithm and parameter controls 126 | 127 | The template is the foundation. Build on it, don't rebuild it. 128 | 129 | --- 130 | 131 | To create gallery-quality computational art that lives and breathes, use the algorithmic philosophy as the foundation. 132 | 133 | ### TECHNICAL REQUIREMENTS 134 | 135 | **Seeded Randomness (Art Blocks Pattern)**: 136 | ```javascript 137 | // ALWAYS use a seed for reproducibility 138 | let seed = 12345; // or hash from user input 139 | randomSeed(seed); 140 | noiseSeed(seed); 141 | ``` 142 | 143 | **Parameter Structure - FOLLOW THE PHILOSOPHY**: 144 | 145 | To establish parameters that emerge naturally from the algorithmic philosophy, consider: "What qualities of this system can be adjusted?" 146 | 147 | ```javascript 148 | let params = { 149 | seed: 12345, // Always include seed for reproducibility 150 | // colors 151 | // Add parameters that control YOUR algorithm: 152 | // - Quantities (how many?) 153 | // - Scales (how big? how fast?) 154 | // - Probabilities (how likely?) 155 | // - Ratios (what proportions?) 156 | // - Angles (what direction?) 157 | // - Thresholds (when does behavior change?) 158 | }; 159 | ``` 160 | 161 | **To design effective parameters, focus on the properties the system needs to be tunable rather than thinking in terms of "pattern types".** 162 | 163 | **Core Algorithm - EXPRESS THE PHILOSOPHY**: 164 | 165 | **CRITICAL**: The algorithmic philosophy should dictate what to build. 166 | 167 | To express the philosophy through code, avoid thinking "which pattern should I use?" and instead think "how to express this philosophy through code?" 168 | 169 | If the philosophy is about **organic emergence**, consider using: 170 | - Elements that accumulate or grow over time 171 | - Random processes constrained by natural rules 172 | - Feedback loops and interactions 173 | 174 | If the philosophy is about **mathematical beauty**, consider using: 175 | - Geometric relationships and ratios 176 | - Trigonometric functions and harmonics 177 | - Precise calculations creating unexpected patterns 178 | 179 | If the philosophy is about **controlled chaos**, consider using: 180 | - Random variation within strict boundaries 181 | - Bifurcation and phase transitions 182 | - Order emerging from disorder 183 | 184 | **The algorithm flows from the philosophy, not from a menu of options.** 185 | 186 | To guide the implementation, let the conceptual essence inform creative and original choices. Build something that expresses the vision for this particular request. 187 | 188 | **Canvas Setup**: Standard p5.js structure: 189 | ```javascript 190 | function setup() { 191 | createCanvas(1200, 1200); 192 | // Initialize your system 193 | } 194 | 195 | function draw() { 196 | // Your generative algorithm 197 | // Can be static (noLoop) or animated 198 | } 199 | ``` 200 | 201 | ### CRAFTSMANSHIP REQUIREMENTS 202 | 203 | **CRITICAL**: To achieve mastery, create algorithms that feel like they emerged through countless iterations by a master generative artist. Tune every parameter carefully. Ensure every pattern emerges with purpose. This is NOT random noise - this is CONTROLLED CHAOS refined through deep expertise. 204 | 205 | - **Balance**: Complexity without visual noise, order without rigidity 206 | - **Color Harmony**: Thoughtful palettes, not random RGB values 207 | - **Composition**: Even in randomness, maintain visual hierarchy and flow 208 | - **Performance**: Smooth execution, optimized for real-time if animated 209 | - **Reproducibility**: Same seed ALWAYS produces identical output 210 | 211 | ### OUTPUT FORMAT 212 | 213 | Output: 214 | 1. **Algorithmic Philosophy** - As markdown or text explaining the generative aesthetic 215 | 2. **Single HTML Artifact** - Self-contained interactive generative art built from `templates/viewer.html` (see STEP 0 and next section) 216 | 217 | The HTML artifact contains everything: p5.js (from CDN), the algorithm, parameter controls, and UI - all in one file that works immediately in claude.ai artifacts or any browser. Start from the template file, not from scratch. 218 | 219 | --- 220 | 221 | ## INTERACTIVE ARTIFACT CREATION 222 | 223 | **REMINDER: `templates/viewer.html` should have already been read (see STEP 0). Use that file as the starting point.** 224 | 225 | To allow exploration of the generative art, create a single, self-contained HTML artifact. Ensure this artifact works immediately in claude.ai or any browser - no setup required. Embed everything inline. 226 | 227 | ### CRITICAL: WHAT'S FIXED VS VARIABLE 228 | 229 | The `templates/viewer.html` file is the foundation. It contains the exact structure and styling needed. 230 | 231 | **FIXED (always include exactly as shown):** 232 | - Layout structure (header, sidebar, main canvas area) 233 | - Anthropic branding (UI colors, fonts, gradients) 234 | - Seed section in sidebar: 235 | - Seed display 236 | - Previous/Next buttons 237 | - Random button 238 | - Jump to seed input + Go button 239 | - Actions section in sidebar: 240 | - Regenerate button 241 | - Reset button 242 | 243 | **VARIABLE (customize for each artwork):** 244 | - The entire p5.js algorithm (setup/draw/classes) 245 | - The parameters object (define what the art needs) 246 | - The Parameters section in sidebar: 247 | - Number of parameter controls 248 | - Parameter names 249 | - Min/max/step values for sliders 250 | - Control types (sliders, inputs, etc.) 251 | - Colors section (optional): 252 | - Some art needs color pickers 253 | - Some art might use fixed colors 254 | - Some art might be monochrome (no color controls needed) 255 | - Decide based on the art's needs 256 | 257 | **Every artwork should have unique parameters and algorithm!** The fixed parts provide consistent UX - everything else expresses the unique vision. 258 | 259 | ### REQUIRED FEATURES 260 | 261 | **1. Parameter Controls** 262 | - Sliders for numeric parameters (particle count, noise scale, speed, etc.) 263 | - Color pickers for palette colors 264 | - Real-time updates when parameters change 265 | - Reset button to restore defaults 266 | 267 | **2. Seed Navigation** 268 | - Display current seed number 269 | - "Previous" and "Next" buttons to cycle through seeds 270 | - "Random" button for random seed 271 | - Input field to jump to specific seed 272 | - Generate 100 variations when requested (seeds 1-100) 273 | 274 | **3. Single Artifact Structure** 275 | ```html 276 | 277 | 278 | 279 | 280 | 281 | 285 | 286 | 287 |
288 |
289 | 290 |
291 | 298 | 299 | 300 | ``` 301 | 302 | **CRITICAL**: This is a single artifact. No external files, no imports (except p5.js CDN). Everything inline. 303 | 304 | **4. Implementation Details - BUILD THE SIDEBAR** 305 | 306 | The sidebar structure: 307 | 308 | **1. Seed (FIXED)** - Always include exactly as shown: 309 | - Seed display 310 | - Prev/Next/Random/Jump buttons 311 | 312 | **2. Parameters (VARIABLE)** - Create controls for the art: 313 | ```html 314 |
315 | 316 | 317 | ... 318 |
319 | ``` 320 | Add as many control-group divs as there are parameters. 321 | 322 | **3. Colors (OPTIONAL/VARIABLE)** - Include if the art needs adjustable colors: 323 | - Add color pickers if users should control palette 324 | - Skip this section if the art uses fixed colors 325 | - Skip if the art is monochrome 326 | 327 | **4. Actions (FIXED)** - Always include exactly as shown: 328 | - Regenerate button 329 | - Reset button 330 | - Download PNG button 331 | 332 | **Requirements**: 333 | - Seed controls must work (prev/next/random/jump/display) 334 | - All parameters must have UI controls 335 | - Regenerate, Reset, Download buttons must work 336 | - Keep Anthropic branding (UI styling, not art colors) 337 | 338 | ### USING THE ARTIFACT 339 | 340 | The HTML artifact works immediately: 341 | 1. **In claude.ai**: Displayed as an interactive artifact - runs instantly 342 | 2. **As a file**: Save and open in any browser - no server needed 343 | 3. **Sharing**: Send the HTML file - it's completely self-contained 344 | 345 | --- 346 | 347 | ## VARIATIONS & EXPLORATION 348 | 349 | The artifact includes seed navigation by default (prev/next/random buttons), allowing users to explore variations without creating multiple files. If the user wants specific variations highlighted: 350 | 351 | - Include seed presets (buttons for "Variation 1: Seed 42", "Variation 2: Seed 127", etc.) 352 | - Add a "Gallery Mode" that shows thumbnails of multiple seeds side-by-side 353 | - All within the same single artifact 354 | 355 | This is like creating a series of prints from the same plate - the algorithm is consistent, but each seed reveals different facets of its potential. The interactive nature means users discover their own favorites by exploring the seed space. 356 | 357 | --- 358 | 359 | ## THE CREATIVE PROCESS 360 | 361 | **User request** → **Algorithmic philosophy** → **Implementation** 362 | 363 | Each request is unique. The process involves: 364 | 365 | 1. **Interpret the user's intent** - What aesthetic is being sought? 366 | 2. **Create an algorithmic philosophy** (4-6 paragraphs) describing the computational approach 367 | 3. **Implement it in code** - Build the algorithm that expresses this philosophy 368 | 4. **Design appropriate parameters** - What should be tunable? 369 | 5. **Build matching UI controls** - Sliders/inputs for those parameters 370 | 371 | **The constants**: 372 | - Anthropic branding (colors, fonts, layout) 373 | - Seed navigation (always present) 374 | - Self-contained HTML artifact 375 | 376 | **Everything else is variable**: 377 | - The algorithm itself 378 | - The parameters 379 | - The UI controls 380 | - The visual outcome 381 | 382 | To achieve the best results, trust creativity and let the philosophy guide the implementation. 383 | 384 | --- 385 | 386 | ## RESOURCES 387 | 388 | This skill includes helpful templates and documentation: 389 | 390 | - **templates/viewer.html**: REQUIRED STARTING POINT for all HTML artifacts. 391 | - This is the foundation - contains the exact structure and Anthropic branding 392 | - **Keep unchanged**: Layout structure, sidebar organization, Anthropic colors/fonts, seed controls, action buttons 393 | - **Replace**: The p5.js algorithm, parameter definitions, and UI controls in Parameters section 394 | - The extensive comments in the file mark exactly what to keep vs replace 395 | 396 | - **templates/generator_template.js**: Reference for p5.js best practices and code structure principles. 397 | - Shows how to organize parameters, use seeded randomness, structure classes 398 | - NOT a pattern menu - use these principles to build unique algorithms 399 | - Embed algorithms inline in the HTML artifact (don't create separate .js files) 400 | 401 | **Critical reminder**: 402 | - The **template is the STARTING POINT**, not inspiration 403 | - The **algorithm is where to create** something unique 404 | - Don't copy the flow field example - build what the philosophy demands 405 | - But DO keep the exact UI structure and Anthropic branding from the template -------------------------------------------------------------------------------- /skills/algorithmic-art/templates/viewer.html: -------------------------------------------------------------------------------- 1 | 2 | 18 | 19 | 20 | 21 | 22 | Generative Art Viewer 23 | 24 | 25 | 26 | 27 | 330 | 331 | 332 |
333 | 334 |
335 | 336 |

TITLE - EDIT

337 |
SUBHEADER - EDIT
338 | 339 | 340 |
341 |

Seed

342 | 343 |
344 | 345 | 346 |
347 | 348 |
349 | 350 | 351 |
352 |

Parameters

353 | 354 | 355 |
356 | 357 |
358 | 359 | 5000 360 |
361 |
362 | 363 | 364 |
365 | 366 |
367 | 368 | 0.5 369 |
370 |
371 | 372 | 373 |
374 | 375 |
376 | 377 | 0.005 378 |
379 |
380 | 381 | 382 |
383 | 384 |
385 | 386 | 8 387 |
388 |
389 |
390 | 391 | 392 |
393 |

Colors

394 | 395 | 396 |
397 | 398 |
399 | 400 | #d97757 401 |
402 |
403 | 404 | 405 |
406 | 407 |
408 | 409 | #6a9bcc 410 |
411 |
412 | 413 | 414 |
415 | 416 |
417 | 418 | #788c5d 419 |
420 |
421 |
422 | 423 | 424 |
425 |

Actions

426 |
427 | 428 |
429 |
430 |
431 | 432 | 433 |
434 |
435 |
Initializing generative art...
436 |
437 |
438 |
439 | 440 | 598 | 599 | -------------------------------------------------------------------------------- /skills/algorithmic-art/resonant_echoes.html: -------------------------------------------------------------------------------- 1 | 2 | 6 | 7 | 8 | 9 | 10 | Resonant Echoes - Generative Art 11 | 12 | 13 | 14 | 15 | 284 | 285 | 286 |
287 | 288 |
289 | 290 |

Resonant Echoes

291 |
Wave interference patterns emerging from oscillating sources
292 | 293 | 294 |
295 |

Seed

296 | 297 |
298 | 299 | 300 |
301 | 302 |
303 | 304 | 305 |
306 |

Parameters

307 | 308 | 309 |
310 | 311 |
312 | 313 | 6 314 |
315 |
316 | 317 | 318 |
319 | 320 |
321 | 322 | 25 323 |
324 |
325 | 326 | 327 |
328 | 329 |
330 | 331 | 1.5 332 |
333 |
334 | 335 | 336 |
337 | 338 |
339 | 340 | 0.0015 341 |
342 |
343 | 344 | 345 |
346 | 347 |
348 | 349 | 0.02 350 |
351 |
352 | 353 | 354 |
355 | 356 |
357 | 358 | 3 359 |
360 |
361 |
362 | 363 | 364 |
365 |

Actions

366 |
367 | 368 |
369 |
370 |
371 | 372 | 373 |
374 |
375 |
Initializing wave simulation...
376 |
377 |
378 |
379 | 380 | 629 | 630 | 631 | --------------------------------------------------------------------------------