ShipfoxHQ/shipfox / .github/skills/impeccable
impeccable
FlaggedUse when the user wants to design, redesign, shape, critique, audit, polish, clarify, distill, harden, optimize, adapt, animate, colorize, extract, or otherwise improve a frontend interface. Covers websites, landing pages, dashboards, product UI, app shells, components, forms, settings, onboarding, and empty states. Handles UX review, visual hierarchy, information architecture, cognitive load, accessibility, performance, responsive behavior, theming, anti-patterns, typography, fonts, spacing, layout, alignment, color, motion, micro-interactions, UX copy, error states, edge cases, i18n, and reusable design systems or tokens. Also use for bland designs that need to become bolder or more delightful, loud designs that should become quieter, live browser iteration on UI elements, or ambitious visual effects that should feel technically extraordinary. Not for backend-only or non-UI tasks.
scripts/pin.mjs
View on GitHub#!/usr/bin/env node
/**
* Pin/unpin sub-commands as standalone skill shortcuts.
*
* Usage:
* node <scripts_path>/pin.mjs pin <command>
* node <scripts_path>/pin.mjs unpin <command>
*
* `pin audit` creates a lightweight audit skill that redirects to Impeccable's audit workflow.
* `unpin audit` removes that shortcut.
*
* The script discovers harness directories (.claude/skills, .cursor/skills, etc.)
* in the project root and creates/removes the pin in all of them.
*/
import { existsSync, readFileSync, writeFileSync, mkdirSync, rmSync, readdirSync } from 'node:fs';
import { basename, join, resolve, dirname } from 'node:path';
import { fileURLToPath } from 'node:url';
const __dirname = dirname(fileURLToPath(import.meta.url));
// All known harness directories
const HARNESS_DIRS = [
'.claude', '.cursor', '.gemini', '.codex', '.agents', '.github', '.grok',
'.trae', '.trae-cn', '.pi', '.opencode', '.kiro', '.rovodev', '.vibe', '.qoder',
];
const CODEX_HARNESSES = new Set(['.codex', '.agents']);
// Valid sub-command names
const VALID_COMMANDS = [
'craft', 'init', 'extract', 'document', 'shape',
'critique', 'audit',
'polish', 'bolder', 'quieter', 'distill', 'harden', 'onboard', 'live',
'animate', 'colorize', 'typeset', 'layout', 'delight', 'overdrive',
'clarify', 'adapt', 'optimize',
];
// Marker to identify pinned skills (so unpin doesn't delete user skills)
const PIN_MARKER = '<!-- impeccable-pinned-skill -->';
/**
* Walk up from startDir to find a project root.
*/
function findProjectRoot(startDir = process.cwd()) {
let dir = resolve(startDir);
while (dir !== '/') {
if (
existsSync(join(dir, 'package.json')) ||
existsSync(join(dir, '.git')) ||
existsSync(join(dir, 'skills-lock.json'))
) {
return dir;
}
const parent = resolve(dir, '..');
if (parent === dir) break;
dir = parent;
}
return resolve(startDir);
}
/**
* Find harness skill directories that have an impeccable skill installed.
*/
function findHarnessDirs(projectRoot) {
const dirs = [];
for (const harness of HARNESS_DIRS) {
const skillsDir = join(projectRoot, harness, 'skills');
// Only pin in harness dirs that already have impeccable installed
const impeccableDir = join(skillsDir, 'impeccable');
if (existsSync(impeccableDir) || existsSync(join(skillsDir, 'i-impeccable'))) {
dirs.push(skillsDir);
}
}
return dirs;
}
/**
* Load command metadata (descriptions for pinned skills).
*/
function loadCommandMetadata() {
const metadataPath = join(__dirname, 'command-metadata.json');
if (existsSync(metadataPath)) {
return JSON.parse(readFileSync(metadataPath, 'utf-8'));
}
return {};
}
/**
* Generate a pinned skill's SKILL.md content.
*/
function commandPrefixForSkillsDir(skillsDir) {
return CODEX_HARNESSES.has(basename(dirname(skillsDir))) ? '$' : '/';
}
function generatePinnedSkill(command, metadata, commandPrefix) {
const desc = metadata[command]?.description || `Shortcut for ${commandPrefix}impeccable ${command}.`;
const hint = metadata[command]?.argumentHint || '[target]';
return `---
name: ${command}
description: "${desc}"
argument-hint: "${hint}"
user-invocable: true
---
${PIN_MARKER}
This is a pinned shortcut for \`${commandPrefix}impeccable ${command}\`.
Invoke ${commandPrefix}impeccable ${command}, passing along any arguments provided here, and follow its instructions.
`;
}
/**
* Pin a command: create shortcut skill in all harness dirs.
*/
function pin(command, projectRoot) {
const metadata = loadCommandMetadata();
const harnessDirs = findHarnessDirs(projectRoot);
if (harnessDirs.length === 0) {
console.log('No harness directories with impeccable installed found.');
return false;
}
let created = 0;
for (const skillsDir of harnessDirs) {
const commandPrefix = commandPrefixForSkillsDir(skillsDir);
const content = generatePinnedSkill(command, metadata, commandPrefix);
// Check if skill already exists (and isn't a pin)
const skillDir = join(skillsDir, command);
if (existsSync(skillDir)) {
const existingMd = join(skillDir, 'SKILL.md');
if (existsSync(existingMd)) {
const existing = readFileSync(existingMd, 'utf-8');
if (!existing.includes(PIN_MARKER)) {
console.log(` SKIP: ${skillDir} (non-pinned skill already exists)`);
continue;
}
}
}
mkdirSync(skillDir, { recursive: true });
writeFileSync(join(skillDir, 'SKILL.md'), content, 'utf-8');
console.log(` + ${skillDir}`);
created++;
}
if (created > 0) {
console.log(`\nPinned '${command}' as a standalone shortcut in ${created} location(s).`);
console.log('Use the pinned command directly in each harness.');
}
return created > 0;
}
/**
* Unpin a command: remove shortcut skill from all harness dirs.
*/
function unpin(command, projectRoot) {
const harnessDirs = findHarnessDirs(projectRoot);
let removed = 0;
for (const skillsDir of harnessDirs) {
const skillDir = join(skillsDir, command);
if (!existsSync(skillDir)) continue;
const skillMd = join(skillDir, 'SKILL.md');
if (!existsSync(skillMd)) continue;
// Safety: only remove if it's a pinned skill
const content = readFileSync(skillMd, 'utf-8');
if (!content.includes(PIN_MARKER)) {
console.log(` SKIP: ${skillDir} (not a pinned skill)`);
continue;
}
rmSync(skillDir, { recursive: true, force: true });
console.log(` - ${skillDir}`);
removed++;
}
if (removed > 0) {
console.log(`\nUnpinned '${command}' from ${removed} location(s).`);
console.log(`Use Impeccable's '${command}' workflow directly to access it.`);
} else {
console.log(`No pinned '${command}' shortcut found.`);
}
return removed > 0;
}
// --- CLI ---
const [,, action, command] = process.argv;
if (!action || !command) {
console.log('Usage: node pin.mjs <pin|unpin> <command>');
console.log(`\nAvailable commands: ${VALID_COMMANDS.join(', ')}`);
process.exit(1);
}
if (action !== 'pin' && action !== 'unpin') {
console.error(`Unknown action: ${action}. Use 'pin' or 'unpin'.`);
process.exit(1);
}
if (!VALID_COMMANDS.includes(command)) {
console.error(`Unknown command: ${command}`);
console.error(`Available commands: ${VALID_COMMANDS.join(', ')}`);
process.exit(1);
}
const root = findProjectRoot();
if (action === 'pin') {
pin(command, root);
} else {
unpin(command, root);
}
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| rea-analysis-optimizationmorluto/reaOptimize REA providers and shared analysis workflows for agent context, latency, CPU, and memory while preserving correctness and Evidence. Use for analysis bottlenecks and cache or query design; CI/test-suite optimization belongs to rea-ci-tests-audit. | Stars: 472k | Updated | Claude CodeCodex | Verified | Install |
| rea-ci-tests-auditmorluto/reaAudit REA CI and test suites for correctness, fixture drift, false passes, and measured performance; use for suite or workflow investigations and efficiency changes, rather than ordinary feature testing or a single test failure. | Stars: 472k | Updated | Claude CodeCodex | Verified | Install |
| rea-tool-designmorluto/reaAudit, investigate, design, or change REA investigation tools, CLI/MCP contracts, provider capabilities, and Evidence semantics. | Stars: 472k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-auditDietrichGebert/ponytailQuality audit of the whole repo: bugs, security, real load, missing tests, speed, and what to delete. Most important first. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |