funboy322/avoid-ai-design

Purpose and Distribution

avoid-ai-design is a portable Agent Skills specification for auditing and rewriting existing frontend UI that exhibits recognizable AI-generated design patterns. It is content-driven rather than an executable application: no build, runtime service, dependencies, API keys, or deployment infrastructure are required.

Primary installation/agent entry point: SKILL.md. Repository overview and user-facing installation guidance: README.md.

Invocation and Operating Modes

An AI coding client that supports the agentskills.io format loads SKILL.md and applies it when the user asks to audit, de-slop, or redesign existing frontend code.

Two control paths are defined:

• rewrite (default): audit, choose and confirm a visual direction, edit target UI files, then re-audit.

• detect: audit and score only; do not modify files.

The skill is intended for Claude Code, Cursor, Codex CLI, GitHub Copilot, and compatible skill consumers; compatibility is based on the plain skill-file format, not a repository-specific runtime.

Paths: SKILL.md, README.md.

Workflow Orchestrator

SKILL.md defines the agent workflow and behavioral constraints: establish scope and stack, inspect source and optionally rendered output, identify design tells, select a direction, calibrate intervention depth, rewrite, and re-audit.

The workflow preserves application-level boundaries: functionality, props, state, routing, accessibility, copy meaning, and existing design-system tokens should remain intact. New dependencies must be disclosed rather than silently introduced.

Path: SKILL.md.

Audit and Severity Model

The audit stage classifies issues by category and severity:

• P0: visually dominant AI signals requiring priority remediation.

• P1: obvious generic/default component and copy choices.

• P2: secondary spacing and motion issues.

Findings are expected to include source location, category, severity, rationale, and confidence. Rendering/screenshot inspection is optional; visual-only conclusions are lower confidence without it. Re-audit seeks to eliminate P0 findings.

Canonical detection signals and framework-specific remediation guidance live in references/ai-tells-catalog.md; workflow/output expectations are in SKILL.md.

Design-Direction Decision Boundary

Before rewrite mode edits source, the agent commits to one concrete aesthetic direction described through several defining moves. This is a confirmation boundary between diagnosis and mutation, preventing unprincipled restyling.

Intervention is calibrated by artifact context: existing design-system components receive surgical changes, while standalone pages or marketing artifacts may receive a more comprehensive visual rebuild.

Direction options and commitment guidance: references/aesthetic-directions.md. Decision procedure: SKILL.md.

Knowledge Base and Framework Coverage

The catalog is the primary domain knowledge source. It maps typography, color, layout, component, spacing, motion, icon, copy, and imagery tells to detection criteria and fixes for both plain HTML/CSS and React/Tailwind/shadcn contexts.

This allows the skill to operate across target repositories without embedding framework code or taking dependencies.

Paths: references/ai-tells-catalog.md, references/aesthetic-directions.md.

Demonstration and Maintainer Assets

A concrete before/after artifact validates the intended transformation: a generic SaaS landing page and a refined version retaining product content while changing presentation. Its audit documents discovered tells, selected direction, and changes.

Paths: examples/demo/slop.html, examples/demo/refined.html, examples/demo/AUDIT.md.

Launch/discoverability material is separated from the skill’s runtime behavior: docs/LAUNCH.md, docs/SEO.md.