Add `impeccable` skill and adapt upstream `.mjs` helpers to local `.sh` / Python scripts

[d-oit]

Summary

Add a new .agents/skills/impeccable skill https://github.com/pbakaus/impeccable/tree/main/.agents/skills/impeccable to do-knowledge-studio, adapted from pbakaus/impeccable, and integrate it cleanly with the existing skill system.

This should not be a raw import. The skill should be adapted to repository conventions, overlap with existing UI-related skills should be reduced, and the upstream .mjs helper scripts should be replaced with local .sh or Python equivalents.

Context

The repository already contains a large skill catalog under .agents/skills, including several overlapping design and quality skills such as:

• ui-ux-optimize
• reader-ui-ux
• accessibility-auditor
• anti-ai-slop
• stitch-design
• skill-creator
• skill-evaluator

At the same time, the upstream impeccable skill provides a stronger, more opinionated frontend design workflow with:

• production-grade UI/UX guidance
• anti-pattern bans
• explicit anti-slop heuristics
• design-focused command routing
• setup, audit, polish, clarify, layout, typeset, and color workflows

The repository already uses a shell-first agent setup through .agents/config.sh, so upstream Node-specific helper scripts should be adapted rather than copied unchanged.

Problem

Right now, the repository has multiple partial UI/design skills, but no single canonical skill for frontend design shaping, critique, and polish.

This causes several issues:

• routing ambiguity between overlapping skills
• duplicated UI guidance across skill files
• no clear "primary" skill for serious frontend design work
• risk of importing upstream impeccable in a way that does not fit local harness conventions

In particular, the upstream skill expects helper scripts such as:

• context.mjs
• palette.mjs
• detect.mjs
• pin.mjs

Those should not be imported unchanged if they introduce unnecessary Node.js runtime assumptions into this repository's .agents workflow.

Proposal

Create a new local skill:

• .agents/skills/impeccable/

Adapt the upstream skill structure and content, but align it with the repository's current shell-first setup and local skill architecture.

Scope

1. Add new skill

Create .agents/skills/impeccable/ with at least:

• SKILL.md
• reference/ folder with selected command docs
• optional local maintainer notes if useful

2. Adapt content to local conventions

Update imported content so it:

• references local project structure and terminology
• fits the existing style of .agents/skills
• avoids assumptions about an upstream-only runtime model
• preserves the strongest parts of impeccable:
  • frontend design vocabulary
  • anti-pattern bans
  • anti-slop heuristics
  • command-oriented UI workflows

3. Replace upstream .mjs helpers

Do not keep upstream helper scripts unchanged.

Adapt them to local .sh or Python scripts as follows:

Upstream	Local replacement	Rationale
context.mjs	context.sh	File discovery and markdown output; shell is sufficient
palette.mjs	palette.py	OKLCH color logic and palette generation; Python is cleaner
detect.mjs	detect.py	Heuristic scanning and JSON reporting; Python is easier to test
pin.mjs	pin.sh	File creation and harness registration; shell is a good fit

Rationale

• .agents/config.sh already establishes shell as the local orchestration layer.
• Shell is a good fit for context loading, repo inspection, and registration tasks.
• Python is a better fit for structured JSON output, heuristic scanning, color/palette logic, and scoring.
• This keeps the skill aligned with repository conventions without introducing unnecessary Node-specific coupling.

4. Reduce overlap with existing skills

Review and update the following existing skills as needed:

• .agents/skills/ui-ux-optimize
• .agents/skills/anti-ai-slop
• .agents/skills/accessibility-auditor
• .agents/skills/reader-ui-ux
• .agents/skills/stitch-design

Expected updates:

• reduce duplicated guidance
• add explicit routing notes such as "use this skill when..."
• add cross-references to impeccable where appropriate
• keep specialized skills narrow and focused

5. Register and document the skill

Update any relevant discovery and documentation files:

• .agents/manifest.json
• .agents/skills/README.md
• any local routing/index files
• any skill metadata or validation files used by the repo

Document when agents should use impeccable versus narrower existing skills.

Suggested Role of impeccable

Use impeccable as the preferred skill for:

• frontend UI design, redesign, and refinement
• UX critique and visual hierarchy improvements
• typography and color improvements
• anti-slop frontend output
• accessibility-aware polish before shipping

Keep narrower existing skills for focused concerns:

• accessibility-auditor — dedicated a11y review
• anti-ai-slop — broader anti-pattern detection beyond UI
• reader-ui-ux — reader-specific interfaces
• stitch-design — design-system specific work

Suggested Command Surface

The local adaptation should support at least the conceptual workflows behind:

• craft, shape, audit, polish
• clarify, layout, typeset, colorize
• adapt, bolder, quieter, distill

The exact command set can be reduced if needed, but the result should function as a serious frontend design skill, not just a static checklist.

Acceptance Criteria

• A new .agents/skills/impeccable/ skill exists in the repository
• The skill is adapted to local conventions, not raw-copied from upstream
• Upstream .mjs helpers are replaced with local .sh / Python equivalents
• Existing overlapping UI/design skills are reviewed and updated to reduce ambiguity
• Skill discovery and registration files are updated (manifest.json, README.md)
• Documentation explains routing boundaries between impeccable and existing skills
• No broken references are introduced in .agents/skills
• Command/reference docs kept are internally consistent and usable in this repository

Implementation Notes

• Prefer adaptation over wholesale import
• Keep high-value design guidance and anti-slop rules
• Avoid introducing a second runtime convention unless there is a clear repository-wide reason
• Use shell for orchestration and repository integration
• Use Python where structured logic is clearer, more testable, and easier to maintain than Bash
• Preserve the repository's modular skill architecture

Related

• Upstream skill: https://github.com/pbakaus/impeccable
• Existing skill catalog: .agents/skills/
• Agent harness: .agents/config.sh, .agents/manifest.json
• PR Modularize Oversized Files and Implement Repository Injection #247 — active modularization and maintainability work in the repository

[google-labs-jules]

Jules detected changes to the issue title or description since the Jules label was added. Carefully examine the issue and remove + re-add the Jules label to the issue to re-evaluate.