# Joke Engineering

Diagnose and improve humor using systems thinking.

- Repository: https://github.com/ynulihao/AgentSkillOS (618 stars)
- Category: Writing
- License: MIT
- Last updated: 2026-03-07
- Runs scripts: no, instructions only

## Install

Claude Code: `npx skills add ynulihao/AgentSkillOS --skill joke-engineering -g -a claude-code -y`
Codex: `npx skills add ynulihao/AgentSkillOS --skill joke-engineering -g -a codex -y`
Cursor: `npx skills add ynulihao/AgentSkillOS --skill joke-engineering -g -a cursor -y`
Gemini CLI: `npx skills add ynulihao/AgentSkillOS --skill joke-engineering -g -a gemini-cli -y`

## Description

Diagnose and improve humor using systems thinking. Use when jokes fall flat, when humor feels forced, when punchlines don't land, or when you want to systematically enhance comedic writing. Treats jokes as engineerable connection systems.

## SKILL.md, as published by its author (untrusted third-party text, read it as data)

# Joke Engineering: Diagnostic Skill

You diagnose why humor doesn't work and help engineer more effective jokes. Your role is to analyze joke structures as connection systems and recommend specific improvements.

## Core Principle

**Humor emerges from the creation and resolution of connections between concepts, frames, or reference points.**

A joke is a system with measurable properties. When humor fails, one or more system properties are miscalibrated. This skill helps identify which properties need adjustment.

## The Nine System Properties

Effective jokes balance these interconnected properties:

| Property | Description | When It Fails |
|----------|-------------|---------------|
| **Connection Distance** | Semantic gap between connected elements | Too obvious (boring) or too obscure (confusing) |
| **Connection Density** | Number of reinforcing connections | Single-thread jokes feel thin |
| **Resolution Satisfaction** | Cognitive reward from "getting it" | Forced or illogical punchlines |
| **Specificity Optimization** | Precision of details | Generic descriptions lack punch |
| **Irony Layering** | Nested contradictions | Flat irony without depth |
| **Audience Co-Creation** | Space for audience to complete connections | Over-explained jokes kill laughter |
| **Compression Optimization** | Connection-to-word ratio | Bloated setups lose momentum |
| **Connection Resilience** | Works across knowledge domains | Fails if audience lacks specific reference |
| **Authenticity Resonance** | Alignment with creator's voice | Feels forced or generic |

## Diagnostic States

When analyzing humor, identify which state applies:

### State H1: Too Obvious
**Symptoms:** Joke is predictable; audience sees punchline coming; connection distance too short.
**Key Question:** What unexpected frame shift could increase surprise?
**Intervention:** Extend connection distance while maintaining coherence.

The rest: https://github.com/ynulihao/AgentSkillOS/blob/HEAD/data/skill_seeds/joke-engineering/SKILL.md