ilia/dotfiles
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Sync live zsh + Cursor pack for family Macs #3

Merged
ilia merged 1 commits from feat/sync-zsh-cursor-ira into master 2026-07-26 15:02:59 -05:00
Conversation 0 Commits 1 Files Changed 15 +3200 -132
15 changed files with 3200 additions and 132 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

7
.gitignore vendored Normal file
View File

@ -0,0 +1,7 @@
.DS_Store
*.swp
*~
.zshrc.local
.env
.env.*
!.env*.example

1719
.p10k.zsh Normal file
View File

File diff suppressed because it is too large Load Diff

245
.zshrc
View File

@ -1,177 +1,158 @@
typeset -g POWERLEVEL9K_INSTANT_PROMPT=quiet
# Enable Powerlevel10k instant prompt. Should stay close to the top of ~/.zshrc. # Enable Powerlevel10k instant prompt. Should stay close to the top of ~/.zshrc.
# Initialization code that may require console input (password prompts, [y/n] typeset -g POWERLEVEL9K_INSTANT_PROMPT=quiet
# confirmations, etc.) must go above this block; everything else may go below.
if [[ -r "${XDG_CACHE_HOME:-$HOME/.cache}/p10k-instant-prompt-${(%):-%n}.zsh" ]]; then if [[ -r "${XDG_CACHE_HOME:-$HOME/.cache}/p10k-instant-prompt-${(%):-%n}.zsh" ]]; then
source "${XDG_CACHE_HOME:-$HOME/.cache}/p10k-instant-prompt-${(%):-%n}.zsh" source "${XDG_CACHE_HOME:-$HOME/.cache}/p10k-instant-prompt-${(%):-%n}.zsh"
fi fi
# If you come from bash you might have to change your $PATH.
# export PATH=$HOME/bin:$HOME/.local/bin:/usr/local/bin:$PATH
# Path to your Oh My Zsh installation. # Path to your Oh My Zsh installation.
export ZSH="$HOME/.oh-my-zsh" export ZSH="${ZSH:-$HOME/.oh-my-zsh}"
# Optional Node via nvm (Homebrew or ~/.nvm)
export NVM_DIR="${NVM_DIR:-$HOME/.nvm}"
if [[ -s "$NVM_DIR/nvm.sh" ]]; then
source "$NVM_DIR/nvm.sh"
elif command -v brew >/dev/null 2>&1; then
_nvm_prefix="$(brew --prefix nvm 2>/dev/null)" || true
[[ -n "$_nvm_prefix" && -s "$_nvm_prefix/nvm.sh" ]] && source "$_nvm_prefix/nvm.sh"
unset _nvm_prefix
fi
# Set name of the theme to load --- if set to "random", it will
# load a random theme each time Oh My Zsh is loaded, in which case,
# to know which specific one was loaded, run: echo $RANDOM_THEME
# See https://github.com/ohmyzsh/ohmyzsh/wiki/Themes
ZSH_THEME="powerlevel10k/powerlevel10k" ZSH_THEME="powerlevel10k/powerlevel10k"
# Set list of themes to pick from when loading at random plugins=(
# Setting this variable when ZSH_THEME=random will cause zsh to load git
# a theme from this variable instead of looking in $ZSH/themes/ z
# If set to an empty array, this variable will have no effect. sudo
# ZSH_THEME_RANDOM_CANDIDATES=( "robbyrussell" "agnoster" ) extract
command-not-found
dirhistory
web-search
zsh-autosuggestions
zsh-syntax-highlighting
zsh-history-substring-search
)
# Uncomment the following line to use case-sensitive completion. [[ -f "$ZSH/oh-my-zsh.sh" ]] && source "$ZSH/oh-my-zsh.sh"
# CASE_SENSITIVE="true"
# Uncomment the following line to use hyphen-insensitive completion. # Prompt theme (shipped in this repo as .p10k.zsh)
# Case-sensitive completion must be off. _ and - will be interchangeable.
# HYPHEN_INSENSITIVE="true"
# Uncomment one of the following lines to change the auto-update behavior
# zstyle ':omz:update' mode disabled # disable automatic updates
# zstyle ':omz:update' mode auto # update automatically without asking
# zstyle ':omz:update' mode reminder # just remind me to update when it's time
# Uncomment the following line to change how often to auto-update (in days).
# zstyle ':omz:update' frequency 13
# Uncomment the following line if pasting URLs and other text is messed up.
# DISABLE_MAGIC_FUNCTIONS="true"
# Uncomment the following line to disable colors in ls.
# DISABLE_LS_COLORS="true"
# Uncomment the following line to disable auto-setting terminal title.
# DISABLE_AUTO_TITLE="true"
# Uncomment the following line to enable command auto-correction.
# ENABLE_CORRECTION="true"
# Uncomment the following line to display red dots whilst waiting for completion.
# You can also set it to another string to have that shown instead of the default red dots.
# e.g. COMPLETION_WAITING_DOTS="%F{yellow}waiting...%f"
# Caution: this setting can cause issues with multiline prompts in zsh < 5.7.1 (see #5765)
# COMPLETION_WAITING_DOTS="true"
# Uncomment the following line if you want to disable marking untracked files
# under VCS as dirty. This makes repository status check for large repositories
# much, much faster.
# DISABLE_UNTRACKED_FILES_DIRTY="true"
# Uncomment the following line if you want to change the command execution time
# stamp shown in the history command output.
# You can set one of the optional three formats:
# "mm/dd/yyyy"|"dd.mm.yyyy"|"yyyy-mm-dd"
# or set a custom format using the strftime function format specifications,
# see 'man strftime' for details.
# HIST_STAMPS="mm/dd/yyyy"
# Would you like to use another custom folder than $ZSH/custom?
# ZSH_CUSTOM=/path/to/new-custom-folder
# Which plugins would you like to load?
# Standard plugins can be found in $ZSH/plugins/
# Custom plugins may be added to $ZSH_CUSTOM/plugins/
# Example format: plugins=(rails git textmate ruby lighthouse)
# Add wisely, as too many plugins slow down shell startup.
plugins=(git sudo z colored-man-pages fzf zsh-syntax-highlighting zsh-autosuggestions web-search copypath)
source $ZSH/oh-my-zsh.sh
# User configuration
# export MANPATH="/usr/local/man:$MANPATH"
# You may need to manually set your language environment
# export LANG=en_US.UTF-8
# Preferred editor for local and remote sessions
# if [[ -n $SSH_CONNECTION ]]; then
# export EDITOR='vim'
# else
# export EDITOR='nvim'
# fi
# Compilation flags
# export ARCHFLAGS="-arch $(uname -m)"
# Set personal aliases, overriding those provided by Oh My Zsh libs,
# plugins, and themes. Aliases can be placed here, though Oh My Zsh
# users are encouraged to define aliases within a top-level file in
# the $ZSH_CUSTOM folder, with .zsh extension. Examples:
# - $ZSH_CUSTOM/aliases.zsh
# - $ZSH_CUSTOM/macos.zsh
# For a full list of active aliases, run `alias`.
#
# Example aliases
# alias zshconfig="mate ~/.zshrc"
# alias ohmyzsh="mate ~/.oh-my-zsh"
# To customize prompt, run `p10k configure` or edit ~/.p10k.zsh.
[[ ! -f ~/.p10k.zsh ]] || source ~/.p10k.zsh [[ ! -f ~/.p10k.zsh ]] || source ~/.p10k.zsh
[ -f ~/.fzf.zsh ] && source ~/.fzf.zsh
# pnpm
export PNPM_HOME="${PNPM_HOME:-$HOME/Library/pnpm}"
case ":$PATH:" in
*":$PNPM_HOME:"*) ;;
*) [[ -d "$PNPM_HOME" ]] && export PATH="$PNPM_HOME:$PATH" ;;
esac
command -v direnv >/dev/null 2>&1 && eval "$(direnv hook zsh)"
[[ -f ~/.fzf.zsh ]] && source ~/.fzf.zsh
# Optional local tools (skip quietly if missing)
[[ -x "/Applications/LibreOffice.app/Contents/MacOS/soffice" ]] && \
alias libreoffice="/Applications/LibreOffice.app/Contents/MacOS/soffice"
[[ -x "$HOME/Documents/code/free-claude-code/claude-pick" ]] && \
alias ccode="$HOME/Documents/code/free-claude-code/claude-pick"
[[ -f "$HOME/Documents/code/hermes/scripts/hermes-mac.zsh" ]] && \
source "$HOME/Documents/code/hermes/scripts/hermes-mac.zsh"
# ── Custom aliases ───────────────────────────────────────────────────────────
alias reload="source ~/.zshrc && echo 'ZSH config reloaded from ~/.zshrc'" alias reload="source ~/.zshrc && echo 'ZSH config reloaded from ~/.zshrc'"
alias editrc="nano ~/.zshrc" alias editrc="${EDITOR:-nano} ~/.zshrc"
alias c="clear" alias c="clear"
alias ls="ls --color=auto" alias cls="clear"
if [[ "$OSTYPE" == darwin* ]]; then
alias ls="ls -G"
else
alias ls="ls --color=auto"
fi
alias l="ls -lah"
alias ll="ls -lah"
alias la="ls -A"
alias md="mkdir -p"
alias grep="grep --color=auto"
alias ..="cd .." alias ..="cd .."
alias ...="cd ../.." alias ...="cd ../.."
alias ....="cd ../../.." alias ....="cd ../../.."
alias cd..="cd .." alias cd..="cd .."
alias h="cd ~" alias h="cd ~"
alias dc="cd ~/Documents/code" alias cdc="cd ~/Documents/code"
# System information alias df="df -h"
alias df="df -h" # disk usage human readable alias du="du -h"
alias du="du -h" # directory usage human readable
alias free="free -h" # memory usage human readable
# Process management
alias ps="ps aux" alias ps="ps aux"
alias cpu="lscpu" alias cpu="lscpu 2>/dev/null || sysctl -a | grep -E 'cpu|machdep'"
alias top="btop" alias top="btop 2>/dev/null || top"
alias mem="free -m" alias ports="lsof -nP -iTCP -sTCP:LISTEN 2>/dev/null || ss -tulpn"
alias ports="ss -tulpn" # open ports
if [[ "$OSTYPE" == darwin* ]]; then
alias free="vm_stat"
alias mem="vm_stat"
alias localip="ipconfig getifaddr en0 2>/dev/null || ipconfig getifaddr en1"
else
alias free="free -h"
alias mem="free -m"
alias localip="ip route get 1.2.3.4 | awk '{print \$7}'"
alias ports="ss -tulpn"
fi
# Network information
alias myip="curl -s http://ipecho.net/plain; echo" alias myip="curl -s http://ipecho.net/plain; echo"
alias localip="ip route get 1.2.3.4 | awk '{print $7}'"
# Python
alias py="python3" alias py="python3"
alias pip="pip3" alias pip="pip3"
alias venv="python3 -m venv" alias venv="python3 -m venv"
alias activate="source venv/bin/activate" alias activate="source venv/bin/activate"
# Docker
alias d="docker" alias d="docker"
alias dc="docker-compose" alias dc="docker compose"
alias dcu="docker-compose up -d" alias dcu="docker compose up -d"
alias dcd="docker-compose down" alias dcd="docker compose down"
alias dcb="docker-compose build" alias dcb="docker compose build"
alias dps="docker ps" alias dps="docker ps"
alias di="docker images" alias di="docker images"
# Date and time
alias now="date +'%Y-%m-%d %H:%M:%S'" alias now="date +'%Y-%m-%d %H:%M:%S'"
alias today="date +'%Y-%m-%d'" alias today="date +'%Y-%m-%d'"
# Package management (Debian/Ubuntu) if command -v apt >/dev/null 2>&1; then
alias update="sudo apt update && sudo apt upgrade -y" alias update="sudo apt update && sudo apt upgrade -y"
alias install="sudo apt install" alias install="sudo apt install"
alias remove="sudo apt remove" alias remove="sudo apt remove"
alias search="apt search" alias search="apt search"
fi
# Permissions and ownership
alias chmox="chmod +x" alias chmox="chmod +x"
alias own="sudo chown -R $USER:$USER" alias own="sudo chown -R $USER:$USER"
# Safety nets — prompt before delete/overwrite
alias rm='rm -i'
alias cp='cp -i'
alias mv='mv -i'
alias nfresh="rm -rf node_modules/ package-lock.json && npm install" alias nfresh="rm -rf node_modules/ package-lock.json && npm install"
# Homelab / ansible shortcuts (no-op helpers if ansible not cloned)
export ANSIBLE_DIR="${ANSIBLE_DIR:-$HOME/Documents/code/ansible}"
export PERSONAL_SCRIPTS_DIR="${PERSONAL_SCRIPTS_DIR:-$HOME/Documents/code/personal-scripts}"
export LEVKIN_DIR="${LEVKIN_DIR:-$HOME/Documents/code/levkin}"
_DOTFILES_DIR="${DOTFILES_DIR:-}"
if [[ -z "$_DOTFILES_DIR" ]]; then
if [[ -L "$HOME/.zshrc" ]]; then
_link="$(readlink "$HOME/.zshrc")"
[[ "$_link" != /* ]] && _link="$HOME/$_link"
_DOTFILES_DIR="$(cd "$(dirname "$_link")" && pwd)"
unset _link
elif [[ -n "${(%):-%x}" ]]; then
# When sourced from a real file path
_DOTFILES_DIR="$(cd "$(dirname "${(%):-%x}")" && pwd)"
fi
fi
# Fallbacks if install put the repo in the usual place
[[ -z "$_DOTFILES_DIR" && -f "$HOME/Documents/code/dotfiles/zsh/homelab.zsh" ]] && _DOTFILES_DIR="$HOME/Documents/code/dotfiles"
[[ -n "$_DOTFILES_DIR" && -f "$_DOTFILES_DIR/zsh/homelab.zsh" ]] && source "$_DOTFILES_DIR/zsh/homelab.zsh"
# Machine-local overrides (gitignored when living in the repo; usually ~/.zshrc.local)
[[ -f "$HOME/.zshrc.local" ]] && source "$HOME/.zshrc.local"

64
README.md Normal file
View File

@ -0,0 +1,64 @@
# Family / machine shared config (Ilia + Irina)
Shell, Cursor rules/skills, and install helpers so either Mac can:
```bash
git clone gitea@git.levkin.ca:ilia/dotfiles.git ~/Documents/code/dotfiles
cd ~/Documents/code/dotfiles
./install.sh # Ilia / general
./install.sh --ira # Irina — same install + printed follow-ups
exec zsh
```
## What’s in here
| Path | Purpose |
|------|---------|
| `.zshrc` | Live Oh My Zsh + Powerlevel10k config (portable `$HOME` paths) |
| `.p10k.zsh` | Prompt theme |
| `zsh/homelab.zsh` | Ansible shortcuts (`hsp`, `hs`, `mk`, `hvk`, `mps`, …) |
| `zsh/zshrc.local.example` | → `~/.zshrc.local` for machine-only tweaks |
| `cursor/rules/` | Shared Cursor rules (`family-machine`, `new-project-standards`) |
| `cursor/skills/` | Shared skills (`humanizer`, `frontend-design`) |
| `cursor/mcp.json.example` | Optional Playwright MCP (no Hermes SSH) |
| `scripts/git-hooks/` | Local gitleaks pre-commit |
**Not** included (stay on Ilia’s machine only): job-application Cursor rules,
Hermes MCP over SSH, Ansible Vault password, full `~/.cursor` dump.
## Irina — pull and go
```bash
git clone gitea@git.levkin.ca:ilia/dotfiles.git ~/Documents/code/dotfiles
cd ~/Documents/code/dotfiles && ./install.sh --ira
```
Then follow the printed steps: Vaultwarden app password → clone
`personal-scripts` → `.env.irina` → Cursor prompt.
Gmail work lives in **`ilia/personal-scripts`** (lighter than full ansible).
Ansible is optional unless you want `hsp` / inventory SSH helpers.
## Ilia — keep this repo updated
When `~/.zshrc` drifts:
1. Edit files **in this repo** (or sync from live after reviewing diffs).
2. `./install.sh` re-links.
3. Commit + push `master` so Irina can `git pull` and re-run `./install.sh`.
Homelab Make/SSH helpers expect `~/Documents/code/ansible`. Gmail Make
targets for Irina expect `~/Documents/code/personal-scripts`.
## Prerequisites (macOS)
- Oh My Zsh + Powerlevel10k theme
- Recommended: `brew install fzf jq direnv` (and `fzf` for `hsp`)
- Optional OMZ plugins: `zsh-autosuggestions`, `zsh-syntax-highlighting`,
`zsh-history-substring-search` under `$ZSH_CUSTOM/plugins/`
## Safety
- `install.sh` backs up existing `~/.zshrc` / `~/.p10k.zsh` before replacing.
- Does not overwrite an existing `~/.cursor/mcp.json`.
- No secrets in this repo — use Vaultwarden and gitignored `.env*` files.

12
cursor/mcp.json.example Normal file
View File

@ -0,0 +1,12 @@
{
"mcpServers": {
"playwright": {
"command": "npx",
"args": [
"-y",
"@playwright/mcp@latest",
"--allowed-origins=https://*.levkin.ca;https://*.levkine.ca;https://auth.levkin.ca;http://127.0.0.1:*"
]
}
}
}

43
cursor/rules/family-machine.mdc Normal file
View File

@ -0,0 +1,43 @@
---
description: Family Mac + Cursor — shared conventions for Ilia and Irina
alwaysApply: true
---
# Family machine (Cursor)
This Mac uses shared **dotfiles** (`ilia/dotfiles`). Homelab apps and passwords
live in Vaultwarden (`vault.levkin.ca`); family docs live in `ilia/levkin`.
## What to clone
| Repo | Why |
|------|-----|
| `ilia/dotfiles` | Shell + Cursor rules/skills (`./install.sh`) |
| `ilia/personal-scripts` | Gmail cleanup / household scripts (Irina: start here) |
| `ilia/ansible` | Infra + Make targets (optional for Irina; needed for `hsp` / vault helpers) |
| `ilia/levkin` | Family knowledge base (health, apps, how-tos) |
Default paths: `~/Documents/code/{dotfiles,personal-scripts,ansible,levkin}`.
## Irina Gmail / digital cleanup
1. Vaultwarden item **"Gmail App Password (Ira)"** (generate in Google Account →
App passwords).
2. In `personal-scripts`: `cp .env.irina.example .env.irina` and fill `GMAIL_*`.
3. Cursor prompt: `personal-scripts/docs/irina-cursor-onboarding-prompt.md`
(or ansible guide if that copy is still present).
4. Prefer `make gmail-audit-irina` / `gmail-cleanup-irina` with `DRY_RUN=1`
before any trash. Never commit `.env.irina`.
## Agent guardrails
- Do **not** open Ansible Vault or run production playbooks unless Ilia asks.
- Do **not** invent medical/financial facts — only report what emails/docs show.
- Secrets stay in Vaultwarden / gitignored `.env*` — never in git.
- Prefer `make` targets in the relevant repo over ad-hoc one-off scripts.
## Useful shell (after `./install.sh`)
- `cdc` — `~/Documents/code`
- `mps` — `make -C personal-scripts`
- `mk` / `hsp` / `hvk` — ansible helpers (need ansible clone + creds)

44
cursor/rules/new-project-standards.mdc Normal file
View File

@ -0,0 +1,44 @@
# New project standards (post 2026-07 hygiene sweep)
Hard requirements for any NEW repo, and the bar for existing repos when
touching them. Skeleton: Gitea `ilia/project-template` — copy it and run
`bootstrap.sh`.
## Day-one requirements for every new repo
1. **LICENSE** (MIT), README that explains what/why/how to an outsider.
2. **CI from the first push**: `.gitea/workflows/ci.yml` with lint + tests +
gitleaks. Lint/typecheck/test steps are **hard gates — `|| true` on a lint
or test step is forbidden**. If a gate is red, fix the findings or narrow
the lint config with an explanatory comment; never mute the step.
3. **Branch protection on `main`** requiring the CI contexts, plus
`default_delete_branch_after_merge: true` (bootstrap.sh does both).
4. **Linter configured**: ruff (`select = ["E4","E7","E9","F","I"]` minimum)
for Python; Biome or ESLint for JS/TS; `tsc --noEmit` alone is not a linter.
## Secrets & data
- **Secrets** live in Infisical or Ansible Vault for infra — never in git.
Local runtime config goes in gitignored `.env`.
- **Real data never goes in fixtures.** Commit `*.example.json` /
`*.example.yml` with fake values; real `data/*` is gitignored.
- **Other people's PII never goes in git**, even in private repos.
- A global pre-commit hook (`~/.git-hooks/pre-commit`) runs gitleaks.
Do not bypass with `--no-verify`.
## Code portability
- **No absolute home paths** (`/Users/...`) — use `Path.home()`, `$HOME`,
or env vars with sane defaults.
- **No LAN IPs / homelab topology in public repos.** Use placeholders;
deploy runbooks live in the private ansible repo.
## Repo lifecycle hygiene
- New repos start **private**; flip public only after the project-template
checklist passes.
- Don't leave work uncommitted for weeks: land it, park it on a pushed
branch, or delete it.
- Merged branches are deleted.
- One-off personal automation goes in `ilia/personal-scripts`, not into
whatever repo is nearby.

190
cursor/skills/frontend-design/LICENSE.txt Normal file
View File

@ -0,0 +1,190 @@
Apache License
Version 2.0, January 2004
http://www.apache.org/licenses/
TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
1. Definitions.
"License" shall mean the terms and conditions for use, reproduction,
and distribution as defined by Sections 1 through 9 of this document.
"Licensor" shall mean the copyright owner or entity authorized by
the copyright owner that is granting the License.
"Legal Entity" shall mean the union of the acting entity and all
other entities that control, are controlled by, or are under common
control with that entity. For the purposes of this definition,
"control" means (i) the power, direct or indirect, to cause the
direction or management of such entity, whether by contract or
otherwise, or (ii) ownership of fifty percent (50%) or more of the
outstanding shares, or (iii) beneficial ownership of such entity.
"You" (or "Your") shall mean an individual or Legal Entity
exercising permissions granted by this License.
"Source" form shall mean the preferred form for making modifications,
including but not limited to software source code, documentation
source, and configuration files.
"Object" form shall mean any form resulting from mechanical
transformation or translation of a Source form, including but
not limited to compiled object code, generated documentation,
and conversions to other media types.
"Work" shall mean the work of authorship, whether in Source or
Object form, made available under the License, as indicated by a
copyright notice that is included in or attached to the work
(an example is provided in the Appendix below).
"Derivative Works" shall mean any work, whether in Source or Object
form, that is based on (or derived from) the Work and for which the
editorial revisions, annotations, elaborations, or other modifications
represent, as a whole, an original work of authorship. For the purposes
of this License, Derivative Works shall not include works that remain
separable from, or merely link (or bind by name) to the interfaces of,
the Work and Derivative Works thereof.
"Contribution" shall mean any work of authorship, including
the original version of the Work and any modifications or additions
to that Work or Derivative Works thereof, that is intentionally
submitted to Licensor for inclusion in the Work by the copyright owner
or by an individual or Legal Entity authorized to submit on behalf of
the copyright owner. For the purposes of this definition, "submitted"
means any form of electronic, verbal, or written communication sent
to the Licensor or its representatives, including but not limited to
communication on electronic mailing lists, source code control systems,
and issue tracking systems that are managed by, or on behalf of, the
Licensor for the purpose of discussing and improving the Work, but
excluding communication that is conspicuously marked or otherwise
designated in writing by the copyright owner as "Not a Contribution."
"Contributor" shall mean Licensor and any individual or Legal Entity
on behalf of whom a Contribution has been received by Licensor and
subsequently incorporated within the Work.
2. Grant of Copyright License. Subject to the terms and conditions of
this License, each Contributor hereby grants to You a perpetual,
worldwide, non-exclusive, no-charge, royalty-free, irrevocable
copyright license to reproduce, prepare Derivative Works of,
publicly display, publicly perform, sublicense, and distribute the
Work and such Derivative Works in Source or Object form.
3. Grant of Patent License. Subject to the terms and conditions of
this License, each Contributor hereby grants to You a perpetual,
worldwide, non-exclusive, no-charge, royalty-free, irrevocable
(except as stated in this section) patent license to make, have made,
use, offer to sell, sell, import, and otherwise transfer the Work,
where such license applies only to those patent claims licensable
by such Contributor that are necessarily infringed by their
Contribution(s) alone or by combination of their Contribution(s)
with the Work to which such Contribution(s) was submitted. If You
institute patent litigation against any entity (including a
cross-claim or counterclaim in a lawsuit) alleging that the Work
or a Contribution incorporated within the Work constitutes direct
or contributory patent infringement, then any patent licenses
granted to You under this License for that Work shall terminate
as of the date such litigation is filed.
4. Redistribution. You may reproduce and distribute copies of the
Work or Derivative Works thereof in any medium, with or without
modifications, and in Source or Object form, provided that You
meet the following conditions:
(a) You must give any other recipients of the Work or
Derivative Works a copy of this License; and
(b) You must cause any modified files to carry prominent notices
stating that You changed the files; and
(c) You must retain, in the Source form of any Derivative Works
that You distribute, all copyright, patent, trademark, and
attribution notices from the Source form of the Work,
excluding those notices that do not pertain to any part of
the Derivative Works; and
(d) If the Work includes a "NOTICE" text file as part of its
distribution, then any Derivative Works that You distribute must
include a readable copy of the attribution notices contained
within such NOTICE file, excluding those notices that do not
pertain to any part of the Derivative Works, in at least one
of the following places: within a NOTICE text file distributed
as part of the Derivative Works; within the Source form or
documentation, if provided along with the Derivative Works; or,
within a display generated by the Derivative Works, if and
wherever such third-party notices normally appear. The contents
of the NOTICE file are for informational purposes only and
do not modify the License. You may add Your own attribution
notices within Derivative Works that You distribute, alongside
or as an addendum to the NOTICE text from the Work, provided
that such additional attribution notices cannot be construed
as modifying the License.
You may add Your own copyright statement to Your modifications and
may provide additional or different license terms and conditions
for use, reproduction, or distribution of Your modifications, or
for any such Derivative Works as a whole, provided Your use,
reproduction, and distribution of the Work otherwise complies with
the conditions stated in this License.
5. Submission of Contributions. Unless You explicitly state otherwise,
any Contribution intentionally submitted for inclusion in the Work
by You to the Licensor shall be under the terms and conditions of
this License, without any additional terms or conditions.
Notwithstanding the above, nothing herein shall supersede or modify
the terms of any separate license agreement you may have executed
with Licensor regarding such Contributions.
6. Trademarks. This License does not grant permission to use the trade
names, trademarks, service marks, or product names of the Licensor,
except as required for reasonable and customary use in describing the
origin of the Work and reproducing the content of the NOTICE file.
7. Disclaimer of Warranty. Unless required by applicable law or
agreed to in writing, Licensor provides the Work (and each
Contributor provides its Contributions) on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
implied, including, without limitation, any warranties or conditions
of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
PARTICULAR PURPOSE. You are solely responsible for determining the
appropriateness of using or redistributing the Work and assume any
risks associated with Your exercise of permissions under this License.
8. Limitation of Liability. In no event and under no legal theory,
whether in tort (including negligence), contract, or otherwise,
unless required by applicable law (such as deliberate and grossly
negligent acts) or agreed to in writing, shall any Contributor be
liable to You for damages, including any direct, indirect, special,
incidental, or consequential damages of any character arising as a
result of this License or out of the use or inability to use the
Work (including but not limited to damages for loss of goodwill,
work stoppage, computer failure or malfunction, or any and all
other commercial damages or losses), even if such Contributor
has been advised of the possibility of such damages.
9. Accepting Warranty or Additional Liability. While redistributing
the Work or Derivative Works thereof, You may choose to offer,
and charge a fee for, acceptance of support, warranty, indemnity,
or other liability obligations and/or rights consistent with this
License. However, in accepting such obligations, You may act only
on Your own behalf and on Your sole responsibility, not on behalf
of any other Contributor, and only if You agree to indemnify,
defend, and hold each Contributor harmless for any liability
incurred by, or claims asserted against, such Contributor by reason
of your accepting any such warranty or additional liability.
END OF TERMS AND CONDITIONS
Copyright 2026 Anthropic, PBC
Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
implied. See the License for the specific language governing
permissions and limitations under the License.

58
cursor/skills/frontend-design/SKILL.md Normal file
View File

@ -0,0 +1,58 @@
---
name: frontend-design
description: Guidance for distinctive, intentional visual design when building new UI or reshaping an existing one. Helps with aesthetic direction, typography, and making choices that don't read as templated defaults.
license: Complete terms in LICENSE.txt
metadata:
source: https://github.com/anthropics/skills/blob/main/skills/frontend-design/SKILL.md
imported: "2026-07-25"
---
# Frontend Design
Approach this as the design lead at a small studio known for giving every client a visual identity that could not be mistaken for anyone else's. This client has already rejected proposals that felt templated, and is paying for a distinctive point of view: make deliberate, opinionated choices about palette, typography, and layout that are specific to this brief, and take one real aesthetic risk you can justify.
## Ground it in the subject
If the brief does not pin down what the product or subject is, pin it yourself before designing: name one concrete subject, its audience, and the page's single job, and state your choice. If there's any information in your memory about the human's preferences, context about what they're building, or designs you've made before – use that as a hint. The subject's own world, its materials, instruments, artifacts, and vernacular, is where distinctive choices come from. Build with the brief's real content and subject matter throughout.
## Design principles
For web designs, the hero is a thesis. Open with the most characteristic thing in the subject's world, in whatever form makes sense for it: a headline, an image, an animation, a live demo, an interactive moment. Be deliberate with your choice: a big number with a small label, supporting stats, and a gradient accent is the template answer, only use if that's truly the best option.
Typography carries the personality of the page. Pair the display and body faces deliberately, not the same families you would reach for on any other project, and set a clear type scale with intentional weights, widths, and spacing. Make the type treatment itself a memorable part of the design, not a neutral delivery vehicle for the content.
Structure is information. Structural devices, numbering, eyebrows, dividers, labels, should encode something true about the content, not decorate it. Many generic designs use numbered markers (01 / 02 / 03), but that's only appropriate if the content actually is a sequence - like a real process or a typed timeline where order carries information the reader needs. Question if choices like numbered markers actually make sense before incorporating them.
Leverage motion deliberately. Think about where and if animation can serve the subject: a page-load sequence, a scroll-triggered reveal, hover micro-interactions, ambient atmosphere. An orchestrated moment usually lands harder than scattered effects; choose what the direction calls for. However, sometimes less is more, and extra animation contributes to the feeling that the design is AI-generated.
Match complexity to the vision. Maximalist directions need elaborate execution; minimal directions need precision in spacing, type, and detail. Elegance is executing the chosen vision well.
Consider written content carefully. Often a design brief may not contain real content, and it's up to you to come up with copy. Copy can make a design feel as templated as the design itself. See the below section on writing for more guidance.
## Process: brainstorm, explore, plan, critique, build, critique again
For calibration: AI-generated design right now clusters around three looks: (1) a warm cream background (near #F4F1EA) with a high-contrast serif display and a terracotta accent; (2) a near-black background with a single bright acid-green or vermilion accent; (3) a broadsheet-style layout with hairline rules, zero border-radius, and dense newspaper-like columns. All three are legitimate for some briefs, but they are defaults rather than choices, and they appear regardless of subject. Where the brief pins down a visual direction, follow it exactly — the brief's own words always win, including when it asks for one of these looks. Where it leaves an axis free, don't spend that freedom on one of these defaults. Just like a human designer who's hired, there's often a careful balance between doing what you're good at and taking each project as a chance to experiment and learn.
Work in two passes. First, brainstorm a short design plan based on the human's design brief: create a compact token system with color, type, layout, and signature. Color: describe the palette as 4–6 named hex values. Type: the typefaces for 2+ roles (a characterful display face that's used with restraint, a complementary body face, and a utility face for captions or data if needed). Layout: a layout concept, using one-sentence prose descriptions and ASCII wireframes to ideate and compare. Signature: the single unique element this page will be remembered by that embodies the brief in an appropriate way.
Then review that plan against the brief before building: if any part of it reads like the generic default you would produce for any similar page (work through a similar prompt to see if you arrive somewhere similar) rather than a choice made for this specific brief — revise that part, say what you changed and why. Only after you've confirmed the relative uniqueness of your design plan should you start to write the code, following the revised plan exactly and deriving every color and type decision from it.
When writing the code, be careful of structuring your CSS selector specificities. It's easy to generate CSS classes that cancel each other out (especially with a type-based selector like .section and a element-based selector like .cta). This can happen often with paddings/margins between sections.
Try to do a lot of this planning and iteration in your thinking, and only show ideas to the user when you have higher confidence it'll delight them.
## Restraint and self-critique
Spend your boldness in one place. Let the signature element be the one memorable thing, keep everything around it quiet and disciplined, and cut any decoration that does not serve the brief. Not taking a risk can be a risk itself! Build to a quality floor without announcing it: responsive down to mobile, visible keyboard focus, reduced motion respected. Critique your own work as you build, taking screenshots if your environment supports it – a picture is worth 1000 tokens. Consider Chanel's advice: before leaving the house, take a look in the mirror and remove one accessory. Human creators have memory and always try to do something new, so if you have a space to quickly jot down notes about what you've tried, it can help you in future passes.
## More on writing in design
Words appear in a design for one reason: to make it easier to understand, and therefore easier to use. They are design material, not decoration. Bring the same intentionality to copy that you would bring to spacing and color. Before writing anything, ask what the design needs to say, and how it can best be said to help the person navigate the experience.
Write from the end user's side of the screen. Name things by what people control and recognize, never by how the system is built. A person manages notifications, not webhook config. Describe what something does in plain terms rather than selling it. Being specific is always better than being clever.
Use active voice as default. A control should say exactly what happens when it's used: "Save changes," not "Submit." An action keeps the same name through the whole flow, so the button that says "Publish" produces a toast that says "Published." The vocabulary of an interface is the signposting for someone navigating the product. Cohesion and consistency are how people learn their way around.
Treat failure and emptiness as moments for direction, not mood. Explain what went wrong and how to fix it, in the interface's voice rather than a person's. Errors don't apologize, and they are never vague about what happened. An empty screen is an invitation to act.
Keep the register conversational and tuned: plain verbs, sentence case, no filler, with tone matched to the brand and the audience. Let each element do exactly one job. A label labels, an example demonstrates, and nothing quietly does double duty.

21
cursor/skills/humanizer/LICENSE Normal file
View File

@ -0,0 +1,21 @@
MIT License
Copyright (c) 2025 Siqi Chen
Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.

230
cursor/skills/humanizer/README.md Normal file
View File

@ -0,0 +1,230 @@
# Humanizer
[![skills.sh installs](https://skills.sh/b/blader/humanizer)](https://skills.sh/blader/humanizer)
A portable agent skill that removes signs of AI-generated writing from text, making it sound more natural and human. It is plain Markdown, so it can run in any harness that supports skill-style instructions.
## Installation
### Skills CLI
Install globally with the cross-agent skills CLI so Humanizer is available in every project:
```bash
npx skills add blader/humanizer --global
```
Update an existing install:
```bash
npx skills update humanizer --global
```
To install globally into every supported agent harness:
```bash
npx skills add blader/humanizer --global --agent '*'
```
To target one configured harness, pass its agent name:
```bash
npx skills add blader/humanizer --global --agent <agent-name>
```
Omit `--global` for a project-local install that can be committed and shared with collaborators. Start a new agent session or reload skills after installation.
### Claude Code plugin
Claude Code users can also install Humanizer as a plugin:
```
/plugin marketplace add blader/humanizer
/plugin install humanizer@humanizer
```
The skill is then invoked as `/humanizer:humanizer`.
### Manual
Any agent harness can use the skill directly because the runtime artifact is `SKILL.md`. Install it wherever your harness expects skill directories, or copy `SKILL.md` into an existing skill folder.
For example:
```bash
git clone https://github.com/blader/humanizer.git /path/to/your/skills/humanizer
```
Or, if you already have this repo cloned:
```bash
mkdir -p /path/to/your/skills/humanizer
cp SKILL.md /path/to/your/skills/humanizer/
```
## Usage
Invoke the skill however your agent harness exposes installed skills. Common forms include a slash command or a direct request:
```
/humanizer
[paste your text here]
```
```
Please humanize this text: [your text]
```
Point it at a file and the skill rewrites it in place:
```
Humanize the prose in docs/launch-post.md
```
### Voice Calibration
To match your personal writing style, provide a sample of your own writing:
```
/humanizer
Here's a sample of my writing for voice matching:
[paste 2-3 paragraphs of your own writing]
Now humanize this text:
[paste AI text to humanize]
```
The skill will analyze your sentence rhythm, word choices, and quirks, then apply them to the rewrite instead of producing generic "clean" output.
## Overview
Based on [Wikipedia's "Signs of AI writing"](https://en.wikipedia.org/wiki/Wikipedia:Signs_of_AI_writing) guide, maintained by WikiProject AI Cleanup. This comprehensive guide comes from observations of thousands of instances of AI-generated text.
The skill also includes a final "obviously AI generated" audit pass and a second rewrite, to catch lingering AI-isms in the first draft.
Rewrites follow a no-fabrication rule: they never add facts, names, dates, or citations that aren't in the source text. Specificity has to come from the source or the author, not from the rewrite.
### Key Insight from Wikipedia
> "LLMs use statistical algorithms to guess what should come next. The result tends toward the most statistically likely result that applies to the widest variety of cases."
## 33 Patterns Detected (with Before/After Examples)
### Content Patterns
| # | Pattern | Before | After |
|---|---------|--------|-------|
| 1 | **Significance inflation** | "marking a pivotal moment in the evolution of..." | "was established in 1989 as part of a wider decentralization" |
| 2 | **Notability name-dropping** | "cited in NYT, BBC, FT, and The Hindu" | Trim the list; keep only sourced context |
| 3 | **Superficial -ing analyses** | "symbolizing... reflecting... showcasing..." | Remove, or keep only what the source supports |
| 4 | **Promotional language** | "nestled within the breathtaking region" | "is a town in the Gonder region" |
| 5 | **Vague attributions** | "Experts believe it plays a crucial role" | Name a real source or cut the claim |
| 6 | **Formulaic challenges** | "Despite challenges... continues to thrive" | Keep the sourced facts; cut the boosterism |
### Language Patterns
| # | Pattern | Before | After |
|---|---------|--------|-------|
| 7 | **AI vocabulary** | "Actually... additionally... testament... landscape... showcasing" | "also... remain common" |
| 8 | **Copula avoidance** | "serves as... features... boasts" | "is... has" |
| 9 | **Negative parallelisms / tailing negations** | "It's not just X, it's Y", "..., no guessing" | State the point directly |
| 10 | **Rule of three** | "innovation, inspiration, and insights" | Use natural number of items |
| 11 | **Synonym cycling** | "protagonist... main character... central figure... hero" | "protagonist" (repeat when clearest) |
| 12 | **False ranges** | "from the Big Bang to dark matter" | List topics directly |
| 13 | **Passive voice / subjectless fragments** | "No configuration file needed" | Name the actor when it helps clarity |
### Style Patterns
| # | Pattern | Before | After |
|---|---------|--------|-------|
| 14 | **Em/en dashes** | "institutions—not the people—yet this continues—" | Cut them: periods, commas, colons, or parentheses |
| 15 | **Boldface overuse** | "**OKRs**, **KPIs**, **BMC**" | "OKRs, KPIs, BMC" |
| 16 | **Inline-header lists** | "**Performance:** Performance improved" | Convert to prose |
| 17 | **Title Case Headings** | "Strategic Negotiations And Partnerships" | "Strategic negotiations and partnerships" |
| 18 | **Emojis** | "🚀 Launch Phase: 💡 Key Insight:" | Remove emojis |
| 19 | **Curly quotes** | `said “the project”` | `said "the project"` |
| 26 | **Hyphenated word pairs** | “cross-functional, data-driven, client-facing” | Drop hyphens on common word pairs |
| 27 | **Persuasive authority tropes** | "At its core, what matters is..." | State the point directly |
| 28 | **Signposting announcements** | "Let's dive in", "Here's what you need to know" | Start with the content |
| 29 | **Fragmented headers** | "## Performance" + "Speed matters." | Let the heading do the work |
| 30 | **Diff-anchored writing** | "This function was added to replace..." | Describe what it does, not what changed |
| 31 | **Manufactured punchlines / staccato drama** | "It had no preference. No prior. No nostalgia." | Use varied sentence lengths and concrete claims |
| 32 | **Aphorism formulas** | "Symmetry is the language of trust" | Replace the formula with the actual claim |
| 33 | **Conversational rhetorical openers** | "Honestly? It depends..." | Remove the fake-candid setup |
### Communication Patterns
| # | Pattern | Before | After |
|---|---------|--------|-------|
| 20 | **Chatbot artifacts** | "I hope this helps! Let me know if..." | Remove entirely |
| 21 | **Cutoff disclaimers** | "While details are limited in available sources..." | Find sources or remove |
| 22 | **Sycophantic tone** | "Great question! You're absolutely right!" | Respond directly |
### Filler and Hedging
| # | Pattern | Before | After |
|---|---------|--------|-------|
| 23 | **Filler phrases** | "In order to", "Due to the fact that" | "To", "Because" |
| 24 | **Excessive hedging** | "could potentially possibly" | "may" |
| 25 | **Generic conclusions** | "The future looks bright" | Specific plans or facts |
## Full Example
*(Illustration note: the rewrite below adds specifics, like the month and the neighborhoods, that stand in for details the author would supply. In a real session those come from the user; the skill asks rather than invents.)*
**Before (AI-sounding):**
> I recently spent five unforgettable days in Lisbon, and let me tell you — this city completely stole my heart. From the moment I arrived, I knew I was somewhere truly special.
>
> Nestled along the banks of the Tagus River, Lisbon stands as a vibrant testament to Portugal's enduring spirit, where rich history and modern energy intertwine at every turn. Yes, the famous hills are challenging — my legs certainly felt it! — but every climb rewards you with breathtaking, panoramic views that make it all worthwhile.
>
> No trip would be complete without riding the iconic Tram 28, winding through the city's most historic neighborhoods. And the food? Simply divine. The original pastéis de nata at Pastéis de Belém are a beloved national treasure, and savoring one still warm was a moment I will never forget.
>
> But what truly makes Lisbon special isn't just the sights — it's the feeling. Wander a few steps off the main squares and you'll discover a quieter, more authentic side: sun-drenched alleys, charming tiled facades, and friendly locals going about their daily lives, inviting you to slow down and savor every moment.
>
> Of course, the must-see São Jorge Castle offers stunning views over the rooftops below. The queues can be long, but the experience is absolutely worth it for any history buff or curious traveler.
>
> Would I go back? Absolutely. Lisbon isn't just a place to visit — it's a place to fall in love with, again and again. If you're dreaming of your next getaway, this is one destination that promises memories to last a lifetime. ✨
**After (Humanized):**
> I spent five days in Lisbon last October and still have mixed feelings about it. Beautiful, yes. Also harder on the knees than anyone warned me.
>
> The hills are the whole story and somehow never make the brochures. My hotel was up in Alfama, which photographs beautifully and translates, in practice, to climbing what felt like a six-story staircase every time I wanted coffee. By the second day my calves had opinions. I started planning each walk around which way was downhill, which is a strange way to see a city but probably an honest one.
>
> Everyone says to ride Tram 28, so I did, wedged against a stranger's backpack for forty minutes while three tour groups filmed the same corner. I would walk the route next time, or go before breakfast. The custard tarts, though, earn the fuss. I had one at a plain little place in Graça, still warm, and for about thirty seconds I understood why people build trips around pastry.
>
> What I did not expect was how quiet the city gets away from the main squares. Two blocks uphill from any plaza it turns into laundry lines, chipped tile, open windows, and old men watching football with the sound turned up. That is the Lisbon I keep thinking about, not the castle.
>
> The castle is fine. The view is great, the queue is long, and I spent more time shuffling toward the entrance than looking at anything once I got inside. If I had only two days, I would trade it for an afternoon of getting lost.
>
> I would go back, but in spring and with better shoes. Lisbon does not bend over backward to make things easy for you. I think I liked that, even when my legs disagreed.
## References
- [Wikipedia: Signs of AI writing](https://en.wikipedia.org/wiki/Wikipedia:Signs_of_AI_writing) - Primary source
- [WikiProject AI Cleanup](https://en.wikipedia.org/wiki/Wikipedia:WikiProject_AI_Cleanup) - Maintaining organization
## Version History
- **2.9.1** - Improved distribution and portability: removed nonportable frontmatter and tool preapprovals, made global installation the documented default, added package validation, and removed the duplicated long-form example from the runtime prompt. No change to the 33 patterns.
- **2.9.0** - Added a no-fabrication rule: rewrites may not invent facts, names, dates, or citations not present in the source, and every example that modeled invented specifics was re-cut to use only source information (fixes #187). Replaced paragraph-count parity with an information-over-shape rule, made a user's voice sample outrank the em dash ban, and added invocation modes (pasted text / file / embedded). No change to the 33 patterns.
- **2.8.3** - Moved the skill version from the unsupported top-level frontmatter key to `metadata.version` for Agent Skills and Claude compatibility. No change to the 33 patterns.
- **2.8.2** - Replaced the full before/after example with a first-person Lisbon trip recap. The after now keeps the same topic, perspective, and rough length as the before while removing the AI tells without becoming clipped or slogan-like. No change to the 33 patterns.
- **2.8.1** - Added cross-agent installation docs, optional Claude Code plugin packaging, and a compact secondhand-text false-positive guard. No change to the 33 patterns.
- **2.8.0** - Added style/cadence patterns #31-33 for manufactured punchlines, aphorism formulas, and conversational rhetorical openers; expanded #20 to catch offer-to-continue chatbot closers. 33 patterns total.
- **2.7.0** - Added pattern #30 (diff-anchored writing); made em/en dashes a hard cut rather than "overuse"; expanded #21 to cover speculative gap-filling ("maintains a low profile"). 30 patterns total.
- **2.6.0** - Cleanup pass: consolidated the duplicated workflow sections, gated the personality guidance to content where voice is wanted, removed the model-fingerprinting subsection, and condensed the worked example. No change to the 29 patterns.
- **2.5.1** - Added a passive-voice / subjectless-fragment rule, raising the total to 29 patterns
- **2.5.0** - Added patterns for persuasive framing, signposting, and fragmented headers; expanded negative parallelisms to cover tailing negations; tightened wording around em dash overuse; fixed frontmatter wording to use "filler phrases"
- **2.4.0** - Added voice calibration: match the user's personal writing style from samples
- **2.3.0** - Added pattern #25: hyphenated word pair overuse
- **2.2.0** - Added a final "obviously AI generated" audit + second-pass rewrite prompts
- **2.1.1** - Fixed pattern #18 example (curly quotes vs straight quotes)
- **2.1.0** - Added before/after examples for all 24 patterns
- **2.0.0** - Complete rewrite based on raw Wikipedia article content
- **1.0.0** - Initial release
## License
MIT

412
cursor/skills/humanizer/SKILL.md Normal file
View File

@ -0,0 +1,412 @@
---
name: humanizer
description: |
Remove signs of AI-generated writing from text. Use when editing or reviewing
text to make it sound more natural and human-written. Based on Wikipedia's
comprehensive "Signs of AI writing" guide. Detects and fixes patterns including:
inflated symbolism, promotional language, superficial -ing analyses, vague
attributions, em dash overuse, rule of three, AI vocabulary words, passive
voice, negative parallelisms, and filler phrases.
license: MIT
metadata:
version: "2.9.1"
---
# Humanizer: Remove AI Writing Patterns
You are a writing editor that identifies and removes signs of AI-generated text to make writing sound more natural and human. This guide is based on Wikipedia's "Signs of AI writing" page, maintained by WikiProject AI Cleanup.
## Your Task
When given text to humanize:
1. **Identify AI patterns** - Scan for the patterns listed below.
2. **Preserve the information, not the shape** - Every claim in the original survives into the rewrite, but depth doesn't have to be uniform: compress the dull parts, dwell where a human would, and merge or split paragraphs freely. When keeping the information and mirroring the original's structure pull in different directions, the information wins.
3. **Never invent facts** - The rewrite must not contain any fact, name, number, date, quote, or citation that isn't in the source text. Swapping a vague claim for a specific one is allowed only when the specific comes from the source or from the user; if a sentence needs real-world detail to work, ask for it or write the plain version without it. Opinions and reactions are voice, not facts: where PERSONALITY AND SOUL applies you may add stance, but never new factual claims. (In fiction, invented detail is the job. This rule governs everything else.)
4. **Match the voice** - Fit the intended tone (formal, casual, technical). Add personality only when the content and the author's voice call for it (see PERSONALITY AND SOUL).
How you're invoked changes what you deliver (see Invocation Modes). The draft → audit → final loop itself is defined under Process and Output, below.
## Voice Calibration
If the user provides a writing sample (their own previous writing), analyze it before rewriting:
1. Read the sample first. Note its sentence lengths, vocabulary, paragraph openings, punctuation, recurring phrases, and transitions.
2. Match those habits instead of merely deleting AI patterns. Do not upgrade casual words or regularize deliberate quirks.
3. Without a sample, use the default behavior below.
A sample outranks this skill's style rules, including the em dash rule in §14: if the sample uses em dashes, keep them at roughly the sample's frequency. Matching the author beats scrubbing the tell.
## PERSONALITY AND SOUL
Avoiding AI patterns is only half the job. Sterile, voiceless writing is just as obvious as slop. Good writing has a human behind it.
**Apply this section only when the content and the author's voice call for it** - blog posts, essays, opinion, personal writing. For encyclopedic, technical, legal, or reference text, neutral and plain *is* the correct human voice; don't inject opinions or first person there.
When voice is appropriate, avoid uniform sentence structures, bloodless neutrality, and perfect organization. Let the writer have opinions, uncertainty, mixed feelings, humor, asides, and uneven rhythm. Never add factual claims to create that personality.
## CONTENT PATTERNS
### 1. Undue Emphasis on Significance, Legacy, and Broader Trends
**Words to watch:** stands/serves as, is a testament/reminder, a vital/significant/crucial/pivotal/key role/moment, underscores/highlights its importance/significance, reflects broader, symbolizing its ongoing/enduring/lasting, contributing to the, setting the stage for, marking/shaping the, represents/marks a shift, key turning point, evolving landscape, focal point, indelible mark, deeply rooted
**Problem:** LLM writing puffs up importance by adding statements about how arbitrary aspects represent or contribute to a broader topic.
**Before:**
> The Statistical Institute of Catalonia was officially established in 1989, marking a pivotal moment in the evolution of regional statistics in Spain. This initiative was part of a broader movement across Spain to decentralize administrative functions and enhance regional governance.
**After:**
> The Statistical Institute of Catalonia was established in 1989, part of a wider decentralization of administrative functions in Spain.
### 2. Undue Emphasis on Notability and Media Coverage
**Words to watch:** independent coverage, local/regional/national media outlets, written by a leading expert, active social media presence
**Problem:** LLMs hit readers over the head with claims of notability, often listing sources without context.
**Before:**
> Her views have been cited in The New York Times, BBC, Financial Times, and The Hindu. She maintains an active social media presence with over 500,000 followers.
**After:**
> Her views have been cited in The New York Times and the BBC.
(If the source gives real context for one citation, what she said and where, keep that one and drop the rest of the list. Don't invent the context to make the trimmed version sound better.)
### 3. Superficial Analyses with -ing Endings
**Words to watch:** highlighting/underscoring/emphasizing..., ensuring..., reflecting/symbolizing..., contributing to..., cultivating/fostering..., encompassing..., showcasing...
**Problem:** AI chatbots tack present participle ("-ing") phrases onto sentences to add fake depth.
**Before:**
> The temple's color palette of blue, green, and gold resonates with the region's natural beauty, symbolizing Texas bluebonnets, the Gulf of Mexico, and the diverse Texan landscapes, reflecting the community's deep connection to the land.
**After:**
> The temple is painted blue, green, and gold, colors meant to evoke Texas bluebonnets and the Gulf of Mexico.
### 4. Promotional and Advertisement-like Language
**Words to watch:** boasts a, vibrant, rich (figurative), profound, enhancing its, showcasing, exemplifies, commitment to, natural beauty, nestled, in the heart of, groundbreaking (figurative), renowned, breathtaking, must-visit, stunning
**Problem:** LLMs have serious problems keeping a neutral tone, especially for "cultural heritage" topics.
**Before:**
> Nestled within the breathtaking region of Gonder in Ethiopia, Alamata Raya Kobo stands as a vibrant town with a rich cultural heritage and stunning natural beauty.
**After:**
> Alamata Raya Kobo is a town in the Gonder region of Ethiopia.
### 5. Vague Attributions and Weasel Words
**Words to watch:** Industry reports, Observers have cited, Experts argue, Some critics argue, several sources/publications (when few cited)
**Problem:** AI chatbots attribute opinions to vague authorities without specific sources.
**Before:**
> Due to its unique characteristics, the Haolai River is of interest to researchers and conservationists. Experts believe it plays a crucial role in the regional ecosystem.
**After:**
> Researchers and conservationists study the Haolai River for its unusual characteristics.
(If a real source exists, name it. Never invent one to make a sentence sound sourced; an unsupported claim gets cut, not decorated.)
### 6. Outline-like "Challenges and Future Prospects" Sections
**Words to watch:** Despite its... faces several challenges..., Despite these challenges, Challenges and Legacy, Future Outlook
**Problem:** Many LLM-generated articles include formulaic "Challenges" sections.
**Before:**
> Despite its industrial prosperity, Korattur faces challenges typical of urban areas, including traffic congestion and water scarcity. Despite these challenges, with its strategic location and ongoing initiatives, Korattur continues to thrive as an integral part of Chennai's growth.
**After:**
> Korattur has recurring traffic congestion and water shortages.
(The specifics you'd want here, like when the congestion worsened or what the city did about it, come from sources or the user, not from the rewrite.)
## LANGUAGE AND GRAMMAR PATTERNS
### 7. Overused "AI Vocabulary" Words
**High-frequency AI words:** Actually, additionally, align with, crucial, delve, emphasizing, enduring, enhance, fostering, garner, highlight (verb), interplay, intricate/intricacies, key (adjective), landscape (abstract noun), pivotal, showcase, tapestry (abstract noun), testament, underscore (verb), valuable, vibrant
**Problem:** These words appear far more frequently in post-2023 text. They often co-occur.
**Before:**
> Additionally, a distinctive feature of Somali cuisine is the incorporation of camel meat. An enduring testament to Italian colonial influence is the widespread adoption of pasta in the local culinary landscape, showcasing how these dishes have integrated into the traditional diet.
**After:**
> Somali cuisine also includes camel meat, which is considered a delicacy. Pasta dishes, introduced during Italian colonization, remain common, especially in the south.
### 8. Avoidance of "is"/"are" (Copula Avoidance)
**Words to watch:** serves as/stands as/marks/represents [a], boasts/features/offers [a]
**Problem:** LLMs substitute elaborate constructions for simple copulas.
**Before:**
> Gallery 825 serves as LAAA's exhibition space for contemporary art. The gallery features four separate spaces and boasts over 3,000 square feet.
**After:**
> Gallery 825 is LAAA's exhibition space for contemporary art. The gallery has four rooms totaling 3,000 square feet.
### 9. Negative Parallelisms and Tailing Negations
**Problem:** Constructions like "Not only...but..." or "It's not just about..., it's..." are overused. So are clipped tailing-negation fragments such as "no guessing" or "no wasted motion" tacked onto the end of a sentence instead of written as a real clause.
**Before:**
> It's not just about the beat riding under the vocals; it's part of the aggression and atmosphere. It's not merely a song, it's a statement.
**After:**
> The heavy beat adds to the aggressive tone.
**Before (tailing negation):**
> The options come from the selected item, no guessing.
**After:**
> The options come from the selected item without forcing the user to guess.
### 10. Rule of Three Overuse
**Problem:** LLMs force ideas into groups of three to appear comprehensive.
**Before:**
> The event features keynote sessions, panel discussions, and networking opportunities. Attendees can expect innovation, inspiration, and industry insights.
**After:**
> The event includes talks and panels. There's also time for informal networking between sessions.
### 11. Elegant Variation (Synonym Cycling)
**Problem:** AI has repetition-penalty code causing excessive synonym substitution.
**Before:**
> The protagonist faces many challenges. The main character must overcome obstacles. The central figure eventually triumphs. The hero returns home.
**After:**
> The protagonist faces many challenges but eventually triumphs and returns home.
### 12. False Ranges
**Problem:** LLMs use "from X to Y" constructions where X and Y aren't on a meaningful scale.
**Before:**
> Our journey through the universe has taken us from the singularity of the Big Bang to the grand cosmic web, from the birth and death of stars to the enigmatic dance of dark matter.
**After:**
> The book covers the Big Bang, star formation, and current theories about dark matter.
### 13. Passive Voice and Subjectless Fragments
**Problem:** LLMs often hide the actor or drop the subject entirely with lines like "No configuration file needed" or "The results are preserved automatically." Rewrite these when active voice makes the sentence clearer and more direct.
**Before:**
> No configuration file needed. The results are preserved automatically.
**After:**
> You do not need a configuration file. The system preserves the results automatically.
## STYLE PATTERNS
### 14. Em Dashes (and En Dashes): Cut Them
**Rule:** The final rewrite contains no em dashes (—) or en dashes (–). The em dash is one of the most reliable AI tells, so treat this as a hard constraint, not a "use sparingly" preference. Replace each one, in rough order of preference: a period (start a new sentence), a comma (a tight aside), a colon (introducing an explanation), parentheses (a true aside), or restructure the sentence. Also catch spaced em dashes (` — `) and double hyphens (` -- `) used the same way.
**Before:**
> The term is primarily promoted by Dutch institutions—not by the people themselves. You don't say "Netherlands, Europe" as an address—yet this mislabeling continues—even in official documents.
**After:**
> The term is primarily promoted by Dutch institutions, not by the people themselves. You don't say "Netherlands, Europe" as an address, yet this mislabeling continues in official documents.
**Before:**
> The new policy — announced without warning — affects thousands of workers. The changes -- long overdue according to critics -- will take effect immediately.
**After:**
> The new policy, announced without warning, affects thousands of workers. The changes, long overdue according to critics, will take effect immediately.
Before returning the final rewrite, scan it for `—` and `–`. Any hit means the draft isn't done. One exception: a user-provided writing sample that uses em dashes overrides this rule (see Voice Calibration); match the sample's frequency instead of banning them.
### 15. Overuse of Boldface
**Problem:** AI chatbots emphasize phrases in boldface mechanically.
**Before:**
> It blends **OKRs (Objectives and Key Results)**, **KPIs (Key Performance Indicators)**, and visual strategy tools such as the **Business Model Canvas (BMC)** and **Balanced Scorecard (BSC)**.
**After:**
> It blends OKRs, KPIs, and visual strategy tools like the Business Model Canvas and Balanced Scorecard.
### 16. Inline-Header Vertical Lists
**Problem:** AI outputs lists where items start with bolded headers followed by colons.
**Before:**
> - **User Experience:** The user experience has been significantly improved with a new interface.
> - **Performance:** Performance has been enhanced through optimized algorithms.
> - **Security:** Security has been strengthened with end-to-end encryption.
**After:**
> The update improves the interface, speeds up load times through optimized algorithms, and adds end-to-end encryption.
### 17. Title Case in Headings
**Problem:** AI chatbots capitalize all main words in headings.
**Before:**
> ## Strategic Negotiations And Global Partnerships
**After:**
> ## Strategic negotiations and global partnerships
### 18. Emojis
**Problem:** AI chatbots often decorate headings or bullet points with emojis.
**Before:**
> 🚀 **Launch Phase:** The product launches in Q3
> 💡 **Key Insight:** Users prefer simplicity
> ✅ **Next Steps:** Schedule follow-up meeting
**After:**
> The product launches in Q3. User research showed a preference for simplicity. Next step: schedule a follow-up meeting.
### 19. Curly Quotation Marks
**Problem:** ChatGPT uses curly quotes (“...”) instead of straight quotes ("...").
**Before:**
> He said “the project is on track” but others disagreed.
**After:**
> He said "the project is on track" but others disagreed.
## COMMUNICATION PATTERNS
### 20. Collaborative Communication Artifacts
**Words to watch:** I hope this helps, Of course!, Certainly!, You're absolutely right!, Would you like..., Want me to...?, Want me to give examples?, Should I continue?, let me know, here is a...
**Problem:** Text meant as chatbot correspondence gets pasted as content.
**Before:**
> Here is an overview of the French Revolution. I hope this helps! Let me know if you'd like me to expand on any section.
**After:**
> The French Revolution began in 1789 when financial crisis and food shortages led to widespread unrest.
### 21. Knowledge-Cutoff Disclaimers and Speculative Gap-Filling
**Words to watch:** as of [date], Up to my last training update, While specific details are limited/scarce..., based on available information, not publicly available, maintains a low profile, keeps personal details private, prefers to stay out of the spotlight, likely [grew up/studied/began], it is believed that
**Problem:** Two related tells. (a) Older models leave hard knowledge-cutoff disclaimers in the text. (b) When a model can't find a source, it writes a paragraph *about* not finding one and then invents plausible filler to cover the gap. For a private person the guess almost always lands on the same stock phrases ("maintains a low profile," "keeps personal details private"), none of it sourced. Say what isn't known, or cut the sentence; don't dress a guess up as fact.
**Before (cutoff disclaimer):**
> While specific details about the company's founding are not extensively documented in readily available sources, it appears to have been established sometime in the 1990s.
**After:**
> The company's founding date is not documented in the available sources. (Or cut the sentence. State a date only if a source provides one.)
**Before (speculative gap-fill):**
> Information about her early life is not publicly available, suggesting she maintains a low profile and keeps personal details private. She likely grew up in a middle-class household, which shaped her later interest in education reform.
**After:**
> Her early life is not documented in the available sources. (Or omit the section.)
### 22. Sycophantic/Servile Tone
**Problem:** Overly positive, people-pleasing language.
**Before:**
> Great question! You're absolutely right that this is a complex topic. That's an excellent point about the economic factors.
**After:**
> The economic factors you mentioned are relevant here.
## FILLER AND HEDGING
### 23. Filler Phrases
**Before → After:**
- "In order to achieve this goal" → "To achieve this"
- "Due to the fact that it was raining" → "Because it was raining"
- "At this point in time" → "Now"
- "In the event that you need help" → "If you need help"
- "The system has the ability to process" → "The system can process"
- "It is important to note that the data shows" → "The data shows"
### 24. Excessive Hedging
**Problem:** Over-qualifying statements.
**Before:**
> It could potentially possibly be argued that the policy might have some effect on outcomes.
**After:**
> The policy may affect outcomes.
### 25. Generic Positive Conclusions
**Problem:** Vague upbeat endings.
**Before:**
> The future looks bright for the company. Exciting times lie ahead as they continue their journey toward excellence. This represents a major step in the right direction.
**After:**
> (Cut the paragraph. End on the last concrete fact instead of a send-off. If the source states real plans, use those.)
### 26. Hyphenated Word Pair Overuse
**Words to watch:** third-party, cross-functional, client-facing, data-driven, decision-making, well-known, high-quality, real-time, long-term, end-to-end
**Problem:** AI hyphenates these uniformly, including in predicate position (`the report is high-quality`). Humans hyphenate inconsistently — typically only when the compound is attributive (`a high-quality report`) and often dropping the hyphen otherwise (`the report is high quality`). Keep attributive-position hyphens; drop them when the compound follows the noun.
**Before:**
> The cross-functional team delivered a high-quality, data-driven report. The team is cross-functional, the report is high-quality, and the methodology is data-driven.
**After:**
> The cross-functional team delivered a high-quality, data-driven report. The team is cross functional, the report is high quality, and the methodology is data driven.
### 27. Persuasive Authority Tropes
**Phrases to watch:** The real question is, at its core, in reality, what really matters, fundamentally, the deeper issue, the heart of the matter
**Problem:** LLMs use these phrases to pretend they are cutting through noise to some deeper truth, when the sentence that follows usually just restates an ordinary point with extra ceremony.
**Before:**
> The real question is whether teams can adapt. At its core, what really matters is organizational readiness.
**After:**
> The question is whether teams can adapt. That mostly depends on whether the organization is ready to change its habits.
### 28. Signposting and Announcements
**Phrases to watch:** Let's dive in, let's explore, let's break this down, here's what you need to know, now let's look at, without further ado
**Problem:** LLMs announce what they are about to do instead of doing it. This meta-commentary slows the writing down and gives it a tutorial-script feel.
**Before:**
> Let's dive into how caching works in Next.js. Here's what you need to know.
**After:**
> Next.js caches data at multiple layers, including request memoization, the data cache, and the router cache.
### 29. Fragmented Headers
**Signs to watch:** A heading followed by a one-line paragraph that simply restates the heading before the real content begins.
**Problem:** LLMs often add a generic sentence after a heading as a rhetorical warm-up. It usually adds nothing and makes the prose feel padded.
**Before:**
> ## Performance
>
> Speed matters.
>
> When users hit a slow page, they leave.
**After:**
> ## Performance
>
> When users hit a slow page, they leave.
### 30. Diff-Anchored Writing
**Problem:** Documentation or comments written as if narrating a change rather than describing the thing as it is. Unless the document is inherently version-scoped (changelogs, release notes, migration guides), it should read coherently without knowing what changed in the last commit.
**Before:**
> This function was added to replace the previous approach of iterating through all items, which caused O(n²) performance.
**After:**
> This function uses a hash map for O(1) lookups, avoiding the O(n²) cost of naive iteration.
### 31. Manufactured Punchlines and Staccato Drama
**Problem:** LLMs often make every sentence land like a quotable closer, then stack short declarative fragments to manufacture drama. A single short sentence for emphasis is fine; a run of them starts to sound engineered.
**Before:**
> Then AlphaEvolve arrived. It had no preference for symmetry. No aesthetic prior. No nostalgia for human taste. The old rules were gone.
**After:**
> AlphaEvolve changed the search because it did not favor symmetry or human-looking designs. That made some of the older assumptions less useful.
### 32. Aphorism Formulas
**Words to watch:** X is the Y of Z, X becomes a trap, X is not a tool but a mirror, the language of, the currency of, the architecture of
**Problem:** LLMs turn ordinary claims into reusable aphorisms that sound profound without adding precision. Replace the formula with the concrete claim it is gesturing at.
**Before:**
> Symmetry is the language of trust. Efficiency becomes a trap when teams forget the human layer.
**After:**
> Symmetric layouts often feel more predictable to users. Teams can over-optimize workflows and miss how people actually use them.
### 33. Conversational Rhetorical Openers
**Phrases to watch:** Honestly?, Look, Here's the thing, The thing is, Let's be honest, Real talk, when used as standalone hooks or fake-candid pauses before an ordinary point.
**Problem:** LLMs open with a fake-candid hook to manufacture intimacy before delivering a routine claim. The tell is the theatrical pause-and-reveal: a one-word question or aside, then the "real" answer. A person being honest usually just says the thing.
**Before:**
> Is it worth the price? Honestly? It depends on how often you'll use it.
**After:**
> Whether it's worth the price depends on how often you'll use it.
## DETECTION GUIDANCE
### What NOT to flag (false positives)
A clean human writer can hit several of the patterns above without any AI involvement. Before rewriting, sanity-check that you are not gutting legitimate prose. The following are *not* reliable indicators on their own:
- **Perfect grammar and consistent style.** Many writers are professionals or have been edited. Polish does not equal AI.
- **Mixed casual and formal registers.** This often signals a person in a technical field, a young writer, or someone with neurodivergent prose habits — not a chatbot.
- **"Bland" or "robotic" prose.** AI prose has *specific* tells. Generic dryness without those tells is just dry writing.
- **Formal or academic vocabulary.** AI overuses *specific* fancy words (see §7), not all fancy words. Don't flatten "ostensibly" or "constituent" just because they sound brainy.
- **Letter-style opening or closing on a comment.** Salutations and sign-offs predate ChatGPT by centuries.
- **Common transition words in isolation.** *Additionally*, *moreover*, *consequently* are AI-coded only when piled up. One *however* is not a tell.
- **Curly quotes alone.** macOS, Word, Google Docs, and most CMSes auto-curl by default. Curly quotes only count when stacked with other tells.
- **Em dashes alone.** Many editors and journalists use them often. Em dashes are evidence only when paired with formulaic sales-y rhythm.
- **One short emphatic sentence.** Humans use clipped sentences to land a point. Flag staccato drama only when several short fragments appear in a row and inflate the tone.
- **"Honestly" or "look" mid-sentence.** These are ordinary in casual writing. The tell is the standalone theatrical opener, not the word itself.
- **Unsourced claims.** Most of the web is unsourced. Lack of citations doesn't prove anything.
- **Correct, complex formatting.** Visual editors and templates produce clean output without any AI.
- **Secondhand text.** Do not rewrite watched phrases inside quotations, titles, proper names, or examples where the phrase is being discussed rather than used.
When in doubt, look for **clusters** of tells, not isolated ones. A single em dash means nothing; em dashes plus rule-of-three plus *vibrant tapestry* plus a "Conclusion" section is a confession.
### Signs of human writing (preserve these)
When you see these, lean toward leaving the prose alone — they are evidence of a real person writing, and over-editing will destroy what makes the piece sound human:
- **Specific, unusual, hard-to-fabricate detail.** A real address. A weird quote. The phrase "the lawyer who used to work upstairs from my dentist." LLMs round off specifics; humans hoard them.
- **Mixed feelings and unresolved tension.** "I think this is mostly good, but it bothers me, and I can't fully explain why." LLMs default to clean takes.
- **Dated, era-bound references.** Slang, memes, or in-jokes that map to a specific year and subculture. Models lag by a year or more.
- **First-person editorial choices the writer can defend.** If the writer can explain *why* they made a particular cut or used a particular word, that's a strong human signal.
- **Variety in sentence length.** Real writing alternates short and long. AI writing tends toward an even, mid-length cadence.
- **Genuine asides, parentheticals, or self-corrections.** "(I keep wanting to say 'almost' here, but it really was certain.)" Models rarely interrupt themselves like this.
- **Edits made before November 30, 2022.** ChatGPT's public launch. Anything older than that is, with very rare exceptions, not AI-written.
---
## Invocation Modes
**Pasted text (default).** The user gives text in the conversation. Run the full loop below and deliver the draft, the audit bullets, and the final rewrite.
**File mode.** The user points at a file. Read it, run the draft → audit → final loop internally, then rewrite the file in place so it ends up containing only the final rewrite. Humanize the prose only: leave code blocks, frontmatter, data, and link targets untouched. In the conversation, report a short summary of what changed rather than pasting the whole rewrite back.
**Embedded mode.** Another task or agent is using this skill as one step of a larger job (a PR description, a commit message, a doc). Run the loop internally and output only the final text. No draft, no audit bullets, no summary. The caller wants prose, not ceremony.
## Process and Output
1. Read the input carefully and identify every instance of the patterns above.
2. Write a **draft rewrite**. Check that it reads naturally aloud, varies sentence length, prefers specific details and simple constructions (is/are/has), and keeps the appropriate register.
3. Ask two questions: **"What makes the below so obviously AI generated?"** and **"Does the rewrite state any fact, name, number, date, or citation that isn't in the source?"** Answer briefly. A fabrication is a defect even when it sounds more human than the vague original.
4. Revise into a **final rewrite** that addresses them and contains no em or en dashes (see §14).
In pasted-text mode, deliver the draft, the brief "still-AI" bullets, the final rewrite, and (optionally) a short summary of changes. In file and embedded modes, run the same loop but deliver only what the mode calls for (see Invocation Modes).
## Reference
This skill is based on [Wikipedia:Signs of AI writing](https://en.wikipedia.org/wiki/Wikipedia:Signs_of_AI_writing), maintained by WikiProject AI Cleanup. The patterns documented there come from observations of thousands of instances of AI-generated text on Wikipedia.
Key insight from Wikipedia: "LLMs use statistical algorithms to guess what should come next. The result tends toward the most statistically likely result that applies to the widest variety of cases."

135
install.sh Executable file
View File

@ -0,0 +1,135 @@
#!/usr/bin/env bash
# Install shared Levkin machine config from this repo onto the current Mac.
# Safe to re-run. Does not overwrite ~/.zshrc.local or secrets.
set -euo pipefail
ROOT="$(cd "$(dirname "$0")" && pwd)"
BACKUP_DIR="${BACKUP_DIR:-$HOME/.dotfiles-backup-$(date +%Y%m%d-%H%M%S)}"
usage() {
cat <<'EOF'
Usage: ./install.sh [--ira] [--no-cursor] [--no-zsh] [--dry-run]
--ira Print Irina follow-up steps (clone personal-scripts, Gmail app password)
--no-cursor Skip ~/.cursor rules/skills/mcp example
--no-zsh Skip ~/.zshrc and ~/.p10k.zsh
--dry-run Show actions only
EOF
}
DO_ZSH=1
DO_CURSOR=1
IRA=0
DRY=0
while [[ $# -gt 0 ]]; do
case "$1" in
--ira) IRA=1 ;;
--no-cursor) DO_CURSOR=0 ;;
--no-zsh) DO_ZSH=0 ;;
--dry-run) DRY=1 ;;
-h|--help) usage; exit 0 ;;
*) echo "Unknown option: $1" >&2; usage; exit 1 ;;
esac
shift
done
run() {
if [[ "$DRY" -eq 1 ]]; then
echo "+ $*"
else
"$@"
fi
}
backup_if_exists() {
local path="$1"
if [[ -e "$path" || -L "$path" ]]; then
run mkdir -p "$BACKUP_DIR"
run mv "$path" "$BACKUP_DIR/$(basename "$path")"
echo "Backed up $path → $BACKUP_DIR/"
fi
}
link_file() {
local src="$1" dest="$2"
if [[ -L "$dest" ]] && [[ "$(readlink "$dest")" == "$src" ]]; then
echo "OK (already linked): $dest"
return 0
fi
backup_if_exists "$dest"
run ln -s "$src" "$dest"
echo "Linked $dest → $src"
}
copy_tree_merge() {
local src="$1" dest="$2"
run mkdir -p "$dest"
# Copy files; do not delete extras already on the machine
if [[ "$DRY" -eq 1 ]]; then
echo "+ rsync -a $src/ $dest/"
else
rsync -a "$src/" "$dest/"
fi
echo "Synced $src → $dest"
}
echo "dotfiles root: $ROOT"
if [[ "$DO_ZSH" -eq 1 ]]; then
link_file "$ROOT/.zshrc" "$HOME/.zshrc"
link_file "$ROOT/.p10k.zsh" "$HOME/.p10k.zsh"
if [[ ! -f "$HOME/.zshrc.local" ]]; then
run cp "$ROOT/zsh/zshrc.local.example" "$HOME/.zshrc.local"
echo "Created ~/.zshrc.local from example (edit as needed)"
fi
# Global gitleaks pre-commit (optional)
if [[ -x "$ROOT/scripts/git-hooks/install.sh" ]]; then
if [[ "$DRY" -eq 1 ]]; then
echo "+ $ROOT/scripts/git-hooks/install.sh"
else
"$ROOT/scripts/git-hooks/install.sh" || echo "git-hooks install skipped/failed (non-fatal)"
fi
fi
fi
if [[ "$DO_CURSOR" -eq 1 ]]; then
run mkdir -p "$HOME/.cursor/rules" "$HOME/.cursor/skills"
copy_tree_merge "$ROOT/cursor/rules" "$HOME/.cursor/rules"
copy_tree_merge "$ROOT/cursor/skills" "$HOME/.cursor/skills"
if [[ ! -f "$HOME/.cursor/mcp.json" && -f "$ROOT/cursor/mcp.json.example" ]]; then
run cp "$ROOT/cursor/mcp.json.example" "$HOME/.cursor/mcp.json"
echo "Installed ~/.cursor/mcp.json from example (edit if needed)"
elif [[ -f "$HOME/.cursor/mcp.json" ]]; then
echo "Left existing ~/.cursor/mcp.json alone (see cursor/mcp.json.example)"
fi
fi
mkdir -p "$HOME/Documents/code" 2>/dev/null || true
cat <<EOF
Done.
Reload shell: exec zsh (or: source ~/.zshrc)
Homelab help: hhlp
Personal make: mps (after cloning personal-scripts)
EOF
if [[ "$IRA" -eq 1 ]]; then
cat <<'EOF'
── Irina next steps ──────────────────────────────────────────
1. Vaultwarden → "Gmail App Password (Ira)" (create Google App Password)
2. Clone household scripts:
git clone gitea@git.levkin.ca:ilia/personal-scripts.git ~/Documents/code/personal-scripts
(HTTPS: https://git.levkin.ca/ilia/personal-scripts.git as ira)
3. Optional infra clone (for hsp / mk ping — not required for Gmail):
git clone gitea@git.levkin.ca:ilia/ansible.git ~/Documents/code/ansible
4. Optional family docs:
git clone gitea@git.levkin.ca:ilia/levkin.git ~/Documents/code/levkin
5. In personal-scripts:
cp .env.irina.example .env.irina && chmod 600 .env.irina
# fill GMAIL_ADDRESS / GMAIL_APP_PASSWORD
6. Open personal-scripts (or ansible) in Cursor and paste the prompt from:
docs/irina-cursor-onboarding-prompt.md
EOF
fi

145
zsh/homelab.zsh Normal file
View File

@ -0,0 +1,145 @@
# Homelab + ansible shell helpers (sourced from ~/.zshrc when present).
# Requires a checkout at $ANSIBLE_DIR for SSH/secret pickers; Gmail make
# targets for Irina live in personal-scripts (or ansible — see README).
# Ansible repo shortcuts
alias mk='make -C "$ANSIBLE_DIR"'
alias mps='make -C "$PERSONAL_SCRIPTS_DIR"'
alias hping='mk ping'
alias hlist='[[ -f "$ANSIBLE_DIR/docs/guides/host-list.md" ]] && less "$ANSIBLE_DIR/docs/guides/host-list.md"'
_homelab-ansible-inventory() {
local bin="$ANSIBLE_DIR/.venv/bin/ansible-inventory"
if [[ -x "$bin" ]]; then
"$bin" -i "$ANSIBLE_DIR/inventories/production" --list "$@"
else
command ansible-inventory -i "$ANSIBLE_DIR/inventories/production" --list "$@"
fi
}
_homelab-hosts-tsv() {
local repo="${ANSIBLE_DIR:-$HOME/Documents/code/ansible}"
local script="${repo}/scripts/homelab-hosts.sh"
if [[ -x "$script" ]]; then
"$script" && return 0
fi
if [[ -f "$repo/inventories/production/hosts" ]]; then
echo "hsp: run chmod +x $script (or fix ANSIBLE_DIR=$repo)" >&2
fi
command -v jq >/dev/null 2>&1 || return 1
_homelab-ansible-inventory 2>/dev/null | jq -r '
._meta.hostvars | to_entries[]
| select(.value.ansible_host != null)
| "\(.key)\t\(.value.ansible_user // "root")@\(.value.ansible_host)\t\(.value.url // "-")"
'
}
homelab-hosts() {
_homelab-hosts-tsv | sort | column -t -s $'\t'
}
homelab-ssh() {
local host="${1:?Usage: homelab-ssh HOST (run homelab-hosts to list)}"
local row ip user
row=$(_homelab-hosts-tsv | awk -F'\t' -v h="$host" '$1 == h {print; exit}')
if [[ -z "$row" ]]; then
echo "Unknown host: $host (try: homelab-hosts)" >&2
return 1
fi
user=${row#*$'\t'}
user=${user%%@*}
ip=${row#*@}
ip=${ip%%$'\t'*}
ssh "${user}@${ip}"
}
unalias hs 2>/dev/null
hs() { homelab-ssh "$@"; }
alias hh="homelab-hosts"
alias gohermes='homelab-ssh hermes'
alias goedge='homelab-ssh edge'
alias gomon='homelab-ssh monitoring'
alias goobs='homelab-ssh observability'
alias goauth='homelab-ssh identity'
alias gopve10='homelab-ssh pve10'
alias gopve='ssh pve'
alias goimmich='homelab-ssh immich'
alias gogitea='homelab-ssh giteaVM'
hsp() {
local repo="${ANSIBLE_DIR:-$HOME/Documents/code/ansible}"
local script="${repo}/scripts/homelab-hosts.sh"
local lines pick
[[ -x "$script" ]] || chmod +x "$script" 2>/dev/null || true
lines=$(_homelab-hosts-tsv | sort)
if [[ -z "$lines" ]]; then
echo "hsp: no hosts (ANSIBLE_DIR=${ANSIBLE_DIR:-unset}, repo=$repo)" >&2
echo " Fix: export ANSIBLE_DIR=\$HOME/Documents/code/ansible && clone ansible" >&2
return 1
fi
if ! command -v fzf >/dev/null 2>&1; then
echo "hsp: install fzf, or use: hs HOST / hh" >&2
return 1
fi
pick=$(printf '%s\n' "$lines" | fzf --header='Homelab SSH — pick a host' --height=40% --reverse | awk '{print $1}')
[[ -n "$pick" ]] && homelab-ssh "$pick"
}
# Homelab secrets picker (Ansible vault + Vaultwarden) — Ilia day-to-day;
# Irina usually only needs Vaultwarden UI for "Gmail App Password (Ira)".
hvk() {
local repo="${ANSIBLE_DIR:-$HOME/Documents/code/ansible}"
local script="${repo}/scripts/homelab-secret-pick.sh"
[[ -f "$script" ]] || { echo "hvk: missing $script (clone ansible)" >&2; return 1; }
chmod +x "$script" "${repo}/scripts/hbw.sh" 2>/dev/null || true
if [[ -z "${BW_SESSION:-}" ]] && command -v bw >/dev/null 2>&1; then
local st
st="$(bw status 2>/dev/null | "${repo}/.venv/bin/python3" -c 'import json,sys; print(json.load(sys.stdin).get("status",""))' 2>/dev/null || true)"
if [[ "$st" == "locked" ]]; then
echo "hvk: run hbw first to include Vaultwarden passwords" >&2
elif [[ "$st" == "unlocked" ]]; then
export BW_SESSION="$(bw unlock --raw 2>/dev/null)" || true
fi
fi
command bash "$script" "$@"
}
alias hsec='hvk'
alias hvka='hvk -a'
homelab-help() {
local doc="${ANSIBLE_DIR:-$HOME/Documents/code/ansible}/docs/guides/homelab-shell-shortcuts.md"
if [[ -f "$doc" ]]; then
less -F "$doc"
else
cat <<'EOF'
Homelab shortcuts — SSH: hsp | hs HOST | hh | gohermes goimmich goedge …
Secrets: hbw (unlock) → hvk (copy) | hvk -e (export)
Ansible: mk | hping | hlist | cdc
Personal scripts (Gmail etc.): mps | cd $PERSONAL_SCRIPTS_DIR
Help: hhlp
EOF
fi
}
alias hhlp='homelab-help'
alias hhelp='homelab-help'
unalias hbw 2>/dev/null
hbw() {
local dir="${ANSIBLE_DIR:-$HOME/Documents/code/ansible}"
local script="${dir}/scripts/hbw.sh"
if [[ ! -x "$script" ]]; then
chmod +x "${dir}/scripts/bw-unlock.sh" "${dir}/scripts/hbw.sh" 2>/dev/null || true
fi
if [[ ! -f "$script" ]]; then
echo "hbw: not found: $script (clone ansible)" >&2
return 1
fi
local session
session="$(command bash "$script" 2>/dev/tty)" || return $?
if [[ -n "$session" ]]; then
eval "$session"
echo "Vaultwarden ready — pick a password with: hvk (or export: hvk -e)" >&2
fi
}

7
zsh/zshrc.local.example Normal file
View File

@ -0,0 +1,7 @@
# Machine-local overrides (not committed).
# Copy to ~/.zshrc.local after install:
# cp zsh/zshrc.local.example ~/.zshrc.local
# export EDITOR=nano
# export ANSIBLE_DIR="$HOME/Documents/code/ansible"
# export PERSONAL_SCRIPTS_DIR="$HOME/Documents/code/personal-scripts"