Collection of agent skills for design, engineering, writing, and product

GitHub stars
74

Install

/plugin install rt@richtabor

Run it inside Claude Code after adding the marketplace with /plugin marketplace add richtabor/agent-skills.

Contents

Discovered from source

Skills 18

Accessibility Review

Overview

This skill enables manual accessibility reviews of web content, components, and applications against WCAG 2.1/2.2 Level AA standards. Reviews focus on practical, modern accessibility requirements without being overly pedantic.

When to Use This Skill

Use this skill when the user asks questions like:

  • "Is this accessible?"
  • "Can you review the color contrast?"
  • "Check this component for accessibility issues"
  • "Does this meet accessibility standards?"
  • Any request to review, check, or validate accessibility

Review Process

1. Identify the Target

Determine what needs to be reviewed:

  • Specific component (button, form, modal, etc.)
  • Full page or application
  • Code file or set of files
  • Design mockup or screenshot

2. Conduct Manual Review

Use the WCAG checklist in references/wcag-checklist.md to systematically review the target against modern accessibility standards.

Focus on the most common and impactful issues:

  • Perceivable: Color contrast, text alternatives, semantic structure
  • Operable: Keyboard navigation, focus management, interactive elements
  • Understandable: Clear labels, error handling, consistent navigation
  • Robust: Valid HTML, ARIA usage, compatibility

3. Prioritize Findings

Classify each issue as:

Critical - Blocks users from accessing core functionality:

  • Missing alt text on meaningful images
  • Non-keyboard accessible interactive elements
  • Insufficient color contrast (below 4.5:1 for normal text, 3:1 for large text)
  • Forms without proper labels
  • Missing focus indicators
  • Inaccessible modal/dialog patterns
  • Auto-playing media without controls

Warning - Creates friction but doesn't fully block access:

  • Suboptimal heading hierarchy (skipped levels)
  • Missing ARIA landmarks
  • Link text that's unclear out of context
  • Redundant or unnecessary ARIA
  • Touch targets smaller than 44x44px
  • Missing skip links
  • Non-descriptive error messages

4. Stepped Review (One Issue at a Time)

IMPORTANT: Do NOT present all findings at once. Review issues one at a time, waiting for user decision before proceeding.

4.1 Start with Overview

Begin by telling the user how many issues were found:

Found [X] accessibility issues ([Y] critical, [Z] warnings).

Let's review them one at a time. I'll present each issue with a recommended fix, and you can decide to:
- **Fix** — I'll implement the change
- **Ignore** — Tell me why, and I'll note it

Starting with critical issues first.

4.2 Present Each Issue

For each issue, present ONE at a time using this format:

───────────────────────────────────
Issue [1/X]: [Critical/Warning]
───────────────────────────────────

**Problem**: [Clear description of the issue]

**Location**: `file_path:line_number`
[Show the relevant code snippet]

**Impact**: [How this affects users — be specific about who and how]

**Recommended Fix**:
[Specific code change or approach]

───────────────────────────────────
Fix this issue, or ignore? (If ignoring, please share why)

4.3 Handle User Response

If user says "fix":

  1. Implement the fix
  2. Confirm: "Fixed. [Brief description of what changed]"
  3. Move to next issue

If user says "ignore" with reason:

  1. Acknowledge: "Noted — ignoring because: [their reason]"
  2. Track the decision (see 4.4)
  3. Move to next issue

If user says "ignore" without reason:

  1. Ask: "Got it. Quick note on why? (Helps for future reference)"
  2. Accept any response and move on

4.4 Track Decisions

Keep a running tally as you go through issues. After all issues are reviewed, present a summary.

5. Final Summary

After reviewing all issues, present a summary:

## Accessibility Review Complete

**Reviewed**: [X] issues ([Y] critical, [Z] warnings)

### Fixed ([N])
- [Issue description] — `file:line`
- [Issue description] — `file:line`

### Ignored ([N])
- [Issue description] — Reason: [user's reason]
- [Issue description] — Reason: [user's reason]

### Remaining Concerns
[Any patterns noticed, suggestions for future, or issues that were ignored but warrant reconsideration]

Review Guidelines

Be Practical: Focus on issues that genuinely impact users. Modern WCAG 2.1/2.2 Level AA is the standard—avoid over-engineering or citing obscure edge cases.

Be Specific: Reference actual code locations using file_path:line_number format when possible.

Be Constructive: Provide actionable fixes, not just problems. Include code examples when helpful.

Consider Context: Some patterns may have accessibility trade-offs. Acknowledge these and suggest the most accessible approach for the use case.

Common Patterns to Check

Interactive Elements

  • All interactive elements must be keyboard accessible (Enter/Space to activate)
  • Focus must be visible with clear indicators
  • Custom controls need proper ARIA roles and states

Forms

  • All inputs must have associated labels (explicit or aria-label)
  • Error messages must be programmatically associated with fields
  • Required fields must be indicated clearly

Color and Contrast

  • Text contrast: 4.5:1 minimum for normal text, 3:1 for large text (18pt+ or 14pt+ bold)
  • UI components: 3:1 contrast for interactive elements and their states
  • Don't rely on color alone to convey information

Images and Media

  • Meaningful images need descriptive alt text
  • Decorative images should have empty alt (alt="")
  • Videos need captions, audio content needs transcripts

Structure

  • Use semantic HTML (nav, main, article, etc.)
  • Heading hierarchy should be logical (h1 → h2 → h3)
  • ARIA landmarks help screen reader navigation

Resources

This skill includes:

references/wcag-checklist.md

Comprehensive checklist of WCAG 2.1/2.2 Level AA requirements organized by principle (Perceivable, Operable, Understandable, Robust). Reference this during reviews to ensure thorough coverage of accessibility standards.

Create PRD

Generate a Product Requirements Document through interactive planning.

Process

1. Understand the Feature

Read the user's feature request. If unclear, ask for a brief description.

2. Ask Clarifying Questions

Ask 3-5 clarifying questions to understand scope and requirements.

Format with lettered options:

1. Who is the primary user?
   A) Logged-in users only
   B) All visitors
   C) Admin users

2. Should this persist across sessions?
   A) Yes, save to database
   B) No, session only

User can respond with combinations like "1A, 2B".

3. Generate PRD

After answers, create a detailed PRD with these sections:

# PRD: [Feature Name]

## Introduction
Brief overview of the feature and why it's needed.

## Goals
- Primary goal
- Secondary goals

## User Stories
### [Story Title]
**Description:** As a [user], I want [action] so that [benefit].
**Acceptance Criteria:**
- [ ] Specific, verifiable criterion
- [ ] Another criterion
- [ ] Typecheck passes
- [ ] (UI changes) Verify in browser

## Functional Requirements
1. Requirement one
2. Requirement two

## Non-Goals
What this feature explicitly won't do.

## Design Considerations
UI/UX notes, mockup descriptions.

## Technical Considerations
Architecture notes, dependencies, potential challenges.

## Success Metrics
How to measure if this feature is successful.

## Open Questions
Any unresolved decisions.

4. Save PRD

Save to prds/[feature-name].md (create prds/ directory if needed).

PRD saved to prds/[feature-name].md

Next: Run /create-prd-json to convert to executable format.

Guidelines

  • Be explicit and unambiguous
  • Write for junior developers and AI agents
  • Avoid jargon
  • Number requirements for easy reference
  • Acceptance criteria must be verifiable, not vague
    • Good: "Button displays 'Save' text"
    • Bad: "Button looks good"

Fresh Eyes Review

Re-read all code you just wrote or modified with a fresh perspective. Look for obvious bugs, errors, problems, and confusion that are easy to miss when deep in implementation.

When to Use

  • After completing a feature or fix
  • Before committing changes
  • When you feel like something might be off
  • After a long coding session

Process

1. Identify Changed Code

Find all files you modified in this session. If unclear, ask the user or check recent git changes:

git diff --name-only HEAD~1
git diff --name-only --cached

2. Re-read with Fresh Eyes

Read each modified file completely. Pretend you've never seen this code before. Look for:

Logic errors

  • Off-by-one errors
  • Inverted conditions
  • Missing null/undefined checks
  • Race conditions
  • Incorrect comparisons (== vs ===, > vs >=)

Obvious bugs

  • Typos in variable names
  • Copy-paste errors
  • Forgotten return statements
  • Unused variables that should be used
  • Wrong function called

Missing pieces

  • Error handling gaps
  • Edge cases not covered
  • Cleanup code missing (close connections, clear timeouts)
  • Validation missing at boundaries

Confusion risks

  • Misleading variable names
  • Complex logic without comments
  • Inconsistent patterns within the file
  • Magic numbers without explanation

3. Fix Issues

For each issue found:

  1. Explain what's wrong in 1 sentence
  2. Fix it immediately
  3. Move to the next issue

Don't ask for permission. Just fix obvious problems.

4. Report Summary

After fixing, provide a brief summary:

## Fresh Eyes Review

Fixed 3 issues:
- `api/users.ts:47` — Missing null check on user.profile
- `api/users.ts:82` — Off-by-one in pagination (used > instead of >=)
- `utils/format.ts:15` — Typo: `formattedDte` → `formattedDate`

No other issues found.

If nothing found:

## Fresh Eyes Review

Reviewed 4 files. No issues found.

What NOT to Do

  • Don't refactor working code
  • Don't add features
  • Don't change style preferences
  • Don't optimize prematurely
  • Don't add comments to obvious code
  • Don't reorganize file structure

Focus only on bugs, errors, and problems. If it works and isn't broken, leave it alone.

Checklist

Run through mentally for each file:

  • All variables initialized before use?
  • All functions return what they should?
  • All loops terminate correctly?
  • All conditions handle both branches?
  • All async operations awaited?
  • All errors caught or propagated?
  • All resources cleaned up?
  • All edge cases handled (empty, null, zero, negative)?

Humanize

Review and edit copy to remove signs of AI-generated writing. Based on Wikipedia's "Signs of AI writing" guide maintained by WikiProject AI Cleanup. Contains 30 rules across 6 categories.

When to Apply

  • Editing AI-generated drafts
  • Reviewing text that sounds robotic or corporate
  • Cleaning up writing before publishing
  • Making technical content sound more natural

Constraints (Non-Negotiable)

  • Preserve meaning, factual claims, and intent.
  • Preserve coverage: don't drop list items, options, or qualifiers (e.g., removing one option from a list) unless they're truly redundant.
  • Do not add new facts, dates, quotes, or citations that are not already present or user-provided.
  • Do not imply a source ("according to…") unless you can name it from the input.
  • Keep genre and audience intact (e.g., neutral encyclopedic tone vs. personal essay). Use voice-soul only when that voice fits.
  • Don't rewrite quoted material unless the user asked to rewrite the quote itself.
  • Avoid em dashes (—). Replace with commas, periods, or parentheses.
  • Don't introduce new AI patterns. Your rewrite must pass the same rules you're applying. Common traps: "Here's the thing:", "It's not about X, it's about Y", formulaic hooks that try to sound casual.

Rule Categories

CategoryImpactPrefixRules
ContentHIGHcontent-6
LanguageHIGHlanguage-8
StyleMEDIUMstyle-7
CommunicationHIGHcomm-3
FillerMEDIUMfiller-5
VoiceHIGHvoice-1

Quick Reference

Content (HIGH)

  • content-significance — Remove "pivotal moment", "testament to" inflation
  • content-notability — Replace media name-dropping with specific claims
  • content-ing-endings — Fix trailing "...highlighting growth" phrases
  • content-promotional — Cut "nestled", "vibrant", "breathtaking"
  • content-vague-attribution — Replace "experts say" with specific sources
  • content-challenges — Remove formulaic "Despite challenges..." sections

Language (HIGH)

  • language-ai-vocabulary — Replace delve, showcase, leverage, foster
  • language-dual-adjectives — Remove "innovative and comprehensive" padding
  • language-copula — Use "is" instead of "serves as", "stands as"
  • language-contractions — Prefer contractions when genre allows
  • language-negative-parallelism — Cut "It's not just X, it's Y", "It's not about X, it's about Y"
  • language-rule-of-three — Don't force ideas into groups of three
  • language-synonym-cycling — Stop cycling through synonyms
  • language-false-ranges — Fix fake "from X to Y" constructions

Style (MEDIUM)

  • style-em-dash — Replace em dashes with commas or periods
  • style-boldface — Reduce mechanical bold emphasis
  • style-inline-headers — Avoid mechanical Header: lists; keep when they improve skimming
  • style-title-case — Use sentence case in headings
  • style-emojis — Remove decorative emojis
  • style-curly-quotes — Use straight quotes
  • style-rhythm — Vary sentence/paragraph cadence

Communication (HIGH)

  • comm-artifacts — Remove "I hope this helps!", "Let me know if..."
  • comm-cutoff — Remove "as of my last update" disclaimers
  • comm-sycophantic — Cut "Great question!", "You're absolutely right!"

Filler (MEDIUM)

  • filler-openings — Cut "In today's fast-paced world", "Here's the thing" openings
  • filler-phrases — Cut "in order to", "at this point in time"
  • filler-hedging — Reduce "could potentially possibly"
  • filler-transitions — Reduce moreover/furthermore signposting
  • filler-conclusions — Replace "the future looks bright" with specifics

Voice (HIGH)

  • voice-soul — Add personality, opinions, varied rhythm

Scoring

Score text before and after rewriting to show improvement. The score measures how human the writing sounds.

How it works

  1. Start at 100
  2. Subtract points for each violation found
  3. HIGH impact violations (Content, Language, Communication, Voice): -3 points each
  4. MEDIUM impact violations (Style, Filler): -1 point each
  5. Minimum score is 0

Score report format

Category       | Before | After | Notes
---------------|--------|-------|-------------------------------
Content        |     94 |   100 | 2 violations fixed
Language       |     88 |    97 | dual-adjectives, copula
Style          |     85 |   100 | 4 em dashes, tightened headers
Communication  |    100 |   100 | —
Filler         |     95 |   100 | "Here's the thing" removed
Voice          |     91 |    94 | rhythm, contractions
---------------|--------|-------|-------------------------------
Overall        |     84 |    97 |

Interpreting scores

  • 95-100: Clean, sounds human
  • 85-94: Minor issues, mostly fine
  • 70-84: Noticeable AI patterns
  • Below 70: Needs significant work

Process

  1. If WRITING_STYLE_GUIDE_PATH is set, load the writing style guide before processing
  2. Load relevant rules from references/
  3. Scan text for patterns and calculate before score
  4. Rewrite problem sections
  5. Add voice (see voice-soul)
  6. Self-check: Scan your rewrite for the same AI patterns, calculate after score
  7. Read aloud, it should sound like a person wrote it

Output

Provide:

  1. Score report (before → after with category breakdown)
  2. The rewritten text
  3. Brief summary of changes

Environment Variables

VariableRequiredDescription
WRITING_STYLE_GUIDE_PATHNoPath to shared writing style guide. Loaded before processing

Reference

Based on Wikipedia:Signs of AI writing.

Alt Text for Markdown Images

Scan markdown files for image embeds that are missing alt text and add detailed, descriptive alt text by reading each image.

Supported Formats

  • Obsidian wiki-style: ![[image.png]] → ![[image.png|alt text here]]
  • Standard markdown: ![](path/to/image.png) → ![alt text here](path/to/image.png)

Detect which format the file uses and apply alt text accordingly.

When to Use

  • User asks to add or update alt text on images
  • User asks to describe images in their notes
  • User asks to make images accessible or searchable

Process

1. Find Images Missing Alt Text

Search the target scope (a specific note, folder, or the whole project) for image embeds without alt text:

  • Obsidian: ![[filename.ext]] with no | pipe character (image extensions: png, jpg, jpeg, gif, svg, webp)
  • Standard markdown: ![](path) where the alt text between [] is empty

Images that already have alt text — ![[image.png|description]] or ![description](path) — should be skipped.

2. Read Each Image

For each image found, use the Read tool to view the image file. Resolve the image path based on the project structure (e.g., an attachments folder, a public/images directory, or a relative path).

3. Write Detailed Alt Text

Write thorough, detailed alt text for each image. The alt text should:

  • Describe the full visual content — what is shown, what text is visible, what the layout looks like
  • Capture specific details like button labels, heading text, color choices, UI patterns, data values
  • Be written as a single continuous description (no line breaks) since it goes inline in the embed
  • Be detailed enough that someone reading only the alt text would understand the image without seeing it
  • Avoid starting with "Image of" or "Screenshot of" — just describe what's there directly

4. Update the Embeds

Use the Edit tool to add alt text in the correct format for the embed style used in that file.

Scope

  • If the user specifies a file or folder, only process that scope
  • If no scope is given, ask the user whether to process a specific file, folder, or the whole project
  • Report how many images were found, how many already had alt text, and how many were updated

Examples

Obsidian — before:

![[dashboard-screenshot.png]]

Obsidian — after:

![[dashboard-screenshot.png|Analytics dashboard showing a bar chart of monthly revenue from January to June 2026, with a sidebar navigation listing Overview, Reports, and Settings. The header reads "Q2 Performance" in bold with a blue export button in the top right.]]

Standard markdown — before:

![](images/dashboard-screenshot.png)

Standard markdown — after:

![Analytics dashboard showing a bar chart of monthly revenue from January to June 2026, with a sidebar navigation listing Overview, Reports, and Settings.](images/dashboard-screenshot.png)

Motion Design

Overview

Design intentional, purposeful motion for product UI. This skill evaluates animation needs and recommends specific easing curves, durations, and implementation approaches based on interaction frequency and purpose.

Every animation needs a job. If it has no job, don't animate.

Process

Phase 1: Load References (Required)

Before any recommendations, read both reference files:

  1. Decision Tree (references/decision-tree.md) - Which easing category to use based on the interaction type, plus scale/origin/hover guidance
  2. Easing Tokens (references/easing-tokens.md) - Specific curves, duration values, and performance guidelines

Phase 2: Evaluate the Animation

For each component or interaction, determine:

2.1 Purpose

What job does this animation do?

  • Responsiveness - Button press, menu open, immediate feedback
  • Spatial continuity - Things come from somewhere and go somewhere
  • Understanding - Illustrating a concept, onboarding, marketing
  • Delight - Rare interactions only (use sparingly)

If no clear purpose exists, recommend no animation.

2.2 Frequency

How often will users trigger this?

  • High-frequency / keyboard-driven - Prefer no animation or near-instant
  • Medium-frequency / common interactions - Keep it fast (120-240ms)
  • Low-frequency / illustrative - More freedom for slower, richer motion

2.3 Pattern Type

What kind of motion is this?

  • Enter/exit - Popover, modal, toast, dropdown appearing or leaving (exits are typically faster than enters—users want things gone quickly)
  • On-screen morph - Layout shift, expanding content, repositioning
  • Time-based - Progress indicator, marquee, hold-to-delete
  • Hover/subtle - Color change, opacity fade, background shift
  • Keyboard navigation - Arrow keys, tab focus, rapid selection

Phase 3: Recommend

Based on the evaluation, provide specific recommendations using tokens from the reference files.

Output Format

For each animation request, provide:

## Animation Recommendation

**Component**: [What's being animated]

### Evaluation
- **Purpose**: [responsiveness / spatial / understanding / delight / none]
- **Frequency**: [high / medium / low]
- **Pattern**: [enter-exit / morph / time-based / hover / keyboard]

### Recommendation
- **Easing**: [token name] — `[cubic-bezier value]`
- **Duration**: [token name] — `[ms value]`
- **Properties**: [transform, opacity, etc.]
- **Transform Origin**: [if applicable]
- **Spring vs Bezier**: [recommendation and why]
- **Bounce**: [yes/no and why]

### Implementation
[Code snippet or CSS/JS example]

### Notes
[Any specific guidance for this case]

Example Interaction

User: "How should I animate this dropdown menu?"

Response:

## Animation Recommendation

**Component**: Dropdown menu

### Evaluation
- **Purpose**: Responsiveness — immediate feedback when user clicks trigger
- **Frequency**: Medium — common interaction but not rapid-fire
- **Pattern**: Enter/exit — appearing and disappearing from screen

### Recommendation
- **Easing**: --ease-out-quart — `cubic-bezier(.165, .84, .44, 1)`
- **Duration**: --dur-2 — `180ms`
- **Properties**: transform (scale, translateY), opacity
- **Transform Origin**: Top center (or top-left/top-right based on trigger position)
- **Spring vs Bezier**: Bezier is fine here; spring useful if menu can be interrupted mid-animation
- **Bounce**: No — tap-to-open shouldn't bounce

### Implementation
```css
.dropdown {
  transform-origin: top center;
  transition:
    transform 180ms cubic-bezier(.165, .84, .44, 1),
    opacity 180ms cubic-bezier(.165, .84, .44, 1);
}

.dropdown[data-state="closed"] {
  opacity: 0;
  transform: scale(0.96) translateY(-8px);
}

.dropdown[data-state="open"] {
  opacity: 1;
  transform: scale(1) translateY(0);
}

Notes

  • Use scale(0.96), not scale(0)
  • Set transform-origin to match trigger position
  • Keep under 240ms for snappy feel

## Tips for Best Results

1. **Be specific about the component** - "dropdown" vs "modal" vs "tooltip" matters
2. **Mention the trigger** - Click, hover, keyboard, scroll
3. **Share context** - "This is a productivity app" vs "marketing landing page"
4. **Ask about multiple states** - Open, close, hover, disabled
5. **Specify framework** - CSS, Framer Motion, GSAP, React Spring

## Resources

This skill includes:

### references/decision-tree.md
Flowchart for choosing the right easing category based on interaction type. Includes scale values, transform-origin guidance, hover/touch considerations, and accessibility.

### references/easing-tokens.md
Complete set of easing curves (ease-out, ease-in-out families), duration tokens, and performance guidelines.

Creating Share Images for Next.js

Generate dynamic OpenGraph (1200x630) and Twitter (1200x600) images using next/og ImageResponse.

Choosing an Approach

  • File-based route (app/opengraph-image.tsx): Best for static pages with known titles at build time. Export runtime, alt, size, contentType, and a default Image function.
  • API route (app/api/og/route.tsx): Best for dynamic content (blog posts, CMS). Accept slug and/or title as query params. Reference in metadata via generateMetadata().

Use export const runtime = "edge" for both approaches.

File Naming Convention

FilePurposeDimensions
opengraph-image.tsxFacebook, LinkedIn, iMessage1200x630
twitter-image.tsxTwitter/X cards1200x600
app/api/og/route.tsxDynamic API route1200x630

Place file-based routes in the relevant route directory (e.g., app/about/opengraph-image.tsx for /about).

Layout Pattern

  • Use flexDirection: "column" with justifyContent: "space-between" to separate content from branding
  • Title and subtitle (e.g., author name) go top-left in a stacked flex column
  • Title: large, bold/medium weight, dark color
  • Subtitle: same size or smaller, lighter weight, muted color (e.g., #888)
  • Keep text left-aligned with textWrap: "balance" and constrain width with maxWidth
  • Use letterSpacing: "-0.02em" for tight, editorial feel at large sizes
  • Padding: 48px on all sides works well at 1200x630

Avatar / Logo (Optional)

If the project has an avatar or logo, place it in the bottom-right corner using a flex container with justifyContent: "flex-end". Load images via fetch + arrayBuffer, convert to base64 data URI for the src. Use borderRadius: "50%" for circular avatars. Cache loaded assets in a Map to avoid refetching.

Custom Fonts

Load .ttf files from public/fonts/ using new URL("../../../public/fonts/YourFont.ttf", import.meta.url). Pass the ArrayBuffer to ImageResponse via the fonts option. Cache the font buffer after first load. Match the weight in the fonts config to the actual font file weight.

Title Case

If titles come from a CMS, apply smart title case:

  • Lowercase small words (a, an, the, and, but, for, in, of, etc.) unless first or last
  • Always capitalize brand names correctly (WordPress, JavaScript, GitHub, macOS, etc.)
  • Uppercase known acronyms (AI, API, CSS, HTML, UI, UX)
  • Handle hyphenated words by capitalizing each part independently

Metadata Integration

Reference the OG route in generateMetadata():

export function generateMetadata({ params }) {
  return {
    openGraph: {
      images: [`/api/og?slug=${params.slug}`],
    },
  };
}

For static pages, pass the title directly: /api/og?title=About.

Satori Rules

These are hard requirements of the next/og rendering engine (Satori):

  1. Every element needs display: "flex" — this is the only layout mode
  2. Inline styles only — no CSS classes, no external stylesheets, no CSS variables
  3. All text must be in elements with explicit style props
  4. Use hex colors — no rgb(), hsl(), or CSS variables
  5. No gap on older versions — test before relying on it; fallback to margin

Common Issues

IssueSolution
Text not renderingAdd display: "flex" to the text wrapper
Layout brokenEnsure all containers have display: "flex"
Colors wrongUse hex colors, not CSS variables
Font not loadingCheck the relative path from route file to public/fonts/
Image not showingConvert to base64 data URI, don't use relative paths

Testing

Preview during development by visiting the route directly in the browser:

http://localhost:3000/api/og?title=Hello+World

After building, verify routes register as dynamic (f prefix) in the build output.

Create PRD Issues

Convert a local PRD or plan file into GitHub Issues.

Usage

/ralph-create-github-issues              # Looks in .claude/plans/ then prds/
/ralph-create-github-issues auth-flow    # Convert specific PRD by name

For story sizing and acceptance criteria guidance, see references/best-practices.md.

Preflight

Run these checks. Stop if critical ones fail.

# 1. Auth check
gh auth status

# 2. Find plan/PRD files — check all locations
ls .claude/plans/*.md 2>/dev/null
ls plans/*.md 2>/dev/null
ls prds/*.md 2>/dev/null

# 3. PRD not already an issue (stop if found open)
gh issue list --label prd --state all --json number,title,state

# 4. Ensure prd label exists
gh label create prd --description "Product Requirements Document" --color "0052CC" 2>/dev/null || true

# 5. Get existing PRDs for dependency matching
gh issue list --label prd --state open --json number,title

Where to find plans

Check these locations in order:

  1. .claude/plans/ — Where plan mode saves approved plans. This is the primary source.
  2. plans/ — Project-level plans directory.
  3. prds/ — Standalone PRDs not generated from plan mode.

If files exist in multiple locations, list all and ask which to convert. If only one file is found, use it directly. If no files are found in any location, ask the user for the path to their PRD/plan file.

Scan PRD markdown for dependency references ("depends on X", "see feature.md"). Note matches for later.

Note: Assume gh sub-issue and gh issue-dependency are already installed. Do NOT try to install them. Just run the commands — if they fail, skip that step and continue.

Create Issues

Parent Issue

gh issue create \
  --title "Feature Name" \
  --label "prd" \
  --label "enhancement" \
  --body "$(cat <<'EOF'
## Overview
<From PRD intro>

## Branch
`feature/<name>`

## Quality Gates
```bash
npm run typecheck
npm run lint
npm test

Implementation Order

  1. Story one
  2. Story two EOF )"

### Sub-Issues

For each story:

```bash
# Create issue
gh issue create \
  --title "Story Title" \
  --body "$(cat <<'EOF'
**Files:** `path/to/file.tsx`

**Acceptance Criteria:**
- [ ] Specific change
- [ ] Typecheck passes
- [ ] Lint passes

**Notes:**
Context if needed.
EOF
)"

# Link to parent
gh sub-issue add <parent> <child>

Dependencies

If dependencies detected in preflight, use GraphQL API (no extension needed):

# Get repo info
OWNER=$(gh repo view --json owner -q '.owner.login')
REPO=$(gh repo view --json name -q '.name')

# Get node IDs (replace 50 and 42 with actual issue numbers)
BLOCKED_ID=$(gh api graphql -f query="{ repository(owner: \"$OWNER\", name: \"$REPO\") { issue(number: 50) { id } } }" --jq '.data.repository.issue.id')
BLOCKING_ID=$(gh api graphql -f query="{ repository(owner: \"$OWNER\", name: \"$REPO\") { issue(number: 42) { id } } }" --jq '.data.repository.issue.id')

# Add blocked-by relationship
gh api graphql -f query="mutation { addBlockedBy(input: {issueId: \"$BLOCKED_ID\", blockingIssueId: \"$BLOCKING_ID\"}) { clientMutationId } }"

Output

Created: #50 - Feature Name
  → #51 Story One
  → #52 Story Two

Dependencies: Blocked by #42 (Auth Flow)
Branch: feature/<name>

Run: /ralph-github-start-loop

Then ask:

Remove local plan/PRD file? <path> (y/n)

If yes, delete the source file. GitHub Issue is now source of truth.

Loop GitHub Issues

Run the autonomous loop to execute features from GitHub Issues.

Usage

/loop-github-issues              # Interactive: shows available PRDs and asks which to run
/loop-github-issues --all        # Run all available PRDs (no prompt)
/loop-github-issues auth-flow    # Run PRDs matching search term
/loop-github-issues 25           # Run with 25 iterations per PRD
/loop-github-issues --all 25     # Run all PRDs with 25 iterations each

When running non-interactively (background mode), --all is auto-enabled.

Prerequisites

  • gh CLI authenticated
  • PRD issues created via /ralph-github-create-issues (reads from .claude/plans/ or prds/)

Note: Assume gh extensions are installed. Do NOT try to install them.

Process

  1. Check prerequisites (gh auth status)
  2. Run the script directly - it handles PRD selection and filtering:
~/.claude/skills/loop-github-issues/loop-github-issues.sh [iterations] [prd-search-term] [--all]

Use run_in_background: true to prevent timeout.

Monitoring progress:

  • Local status: cat /tmp/ralph-status-{repo}-{prd-number}.txt
  • GitHub: Comments are posted to the PRD issue as stories complete

Important: Don't list PRDs separately before running - the script shows available PRDs (excluding those with open PRs) and handles selection.

What It Does

  1. Lists open PRD issues (identified by prd label) that don't already have open PRs
  2. Prompts user to select which PRD(s) to work on (or auto-selects in background mode)
  3. For each selected PRD:
    • Assigns issue to current user (shows as in progress)
    • Creates git worktree at ../{repo}-{feature}/
    • For each iteration:
      • Passes all open sub-issues to the agent
      • Agent picks the logical next story based on dependencies
      • Implements the story
      • Commits: feat: Story Title (closes #XXX)
      • Closes sub-issue with link to commit
    • When all sub-issues closed, creates PR (parent PRD closes on merge)
    • Cleans up worktree

Differences from /ralph

Aspect/ralph (JSON)/loop-github-issues (GitHub)
Story sourceprds/*.jsonGitHub Issues
Status trackingpasses: true/falseIssue open/closed
DependenciesdependsOn arrayNative GitHub blocking
CompletionUpdate JSONClose issue
PRD doneAll stories passAll sub-issues closed

Dependencies

Ralph-issues checks GitHub's native blocking relationships. PRDs with open blocking issues are skipped.

The script queries the blockedBy field via GraphQL to determine if a PRD is ready to start.

Issue Conventions

Finding PRD Issues

gh issue list --label prd --state open --json number,title,body

Finding Story Sub-Issues

Uses the gh-sub-issue extension:

gh sub-issue list <parent-number> --state open --json number,title,body

Closing Issues

On story completion:

gh issue close 101 --comment "Implemented in https://github.com/owner/repo/commit/abc123"

Parent PRD issues close automatically when the PR is merged (via Closes #XX in PR body).

Branch Naming

Uses conventional prefixes parsed from the PRD issue body:

  • feature/<name> for enhancements
  • bugfix/<name> for bug fixes

Notes

  • Run multiple Ralph instances in parallel on independent PRDs (separate terminals)
  • Each works in its own worktree, no conflicts
  • Commits include closes #XXX to auto-close issues on merge

Create PRD JSON

Convert a Product Requirements Document or plan file into JSON for Ralph.

Input

Check these locations in order:

  1. .claude/plans/ — Where plan mode saves approved plans. Primary source.
  2. plans/ — Project-level plans directory.
  3. prds/ — Standalone PRDs not generated from plan mode.

If files exist in multiple locations, list all and ask which to convert. If only one file is found, use it directly. If no files are found in any location, ask the user for the path to their PRD/plan file.

Conversion Rules

Story Sizing (Critical)

Each story MUST complete in ONE Ralph iteration (one context window).

Right-sized:

  • Add a database column
  • Create a single UI component
  • Add one API endpoint
  • Add form validation
  • Update a server action

Too large (must split):

❌ "Build entire auth system"
✅ "Add login form"
✅ "Add email validation"
✅ "Add auth server action"

Dependency Ordering

Stories execute sequentially by priority:

  1. Database/schema changes
  2. Backend logic
  3. API endpoints
  4. UI components

Cross-PRD Dependencies (Critical)

Ralph respects dependsOn to sequence PRDs. Before generating JSON:

  1. Scan existing PRDs — Read all prds/*.json to know what features exist
  2. Detect dependencies — Look for references in the markdown PRD:
    • Explicit: "See elevenlabs-integration.md", "Depends on morning brief"
    • Implicit: Story notes mentioning other features
    • Technical: Uses tables/APIs defined in another PRD
  3. Populate dependsOn — Array of PRD names (without .json extension)

Examples of dependency detection:

# In evening-ritual.md:
"See `elevenlabs-integration.md` for shared infrastructure"
→ dependsOn: ["elevenlabs-integration"]

"Depends on morning brief feature for regeneration"
→ dependsOn: ["elevenlabs-integration", "morning-brief"]

If no dependencies detected:

"dependsOn": []

Acceptance Criteria (Critical)

Must be explicit and verifiable:

Good:

- Email/password fields present
- Validates email format
- Shows error on invalid input
- Typecheck passes
- Verify at localhost:3000/login

Bad:

- Users can log in (vague)
- Works correctly (vague)
- Good UX (subjective)

Required in every story:

  • "Typecheck passes"
  • "Lint passes"

Required for UI stories:

  • "Verify at localhost:3000/[path]"

Output Format

Generate prds/[feature-name].json:

{
  "projectName": "Feature Name",
  "branchName": "ralph/feature-name",
  "description": "Brief description",
  "dependsOn": ["other-feature", "another-feature"],
  "status": "pending",
  "completedAt": null,
  "userStories": [
    {
      "id": "US-001",
      "title": "Add login form",
      "description": "As a user, I want to see a login form so I can authenticate",
      "acceptanceCriteria": [
        "Email/password fields present",
        "Form submits on enter",
        "Typecheck passes",
        "Lint passes",
        "Verify at localhost:3000/login"
      ],
      "priority": 1,
      "passes": false,
      "notes": ""
    }
  ]
}

Process

  1. Scan existing PRDs — Read prds/*.json to understand the dependency landscape
  2. Read the PRD/plan markdown file from .claude/plans/, plans/, or prds/
  3. Derive feature name from filename (e.g., auth-flow.md → auth-flow)
  4. Detect dependencies — Check for references to other PRDs in the markdown
  5. Break into right-sized stories starting at US-001
  6. Order by dependency (set priority)
  7. Add explicit acceptance criteria
  8. Save to prds/[feature-name].json

Pre-Save Checklist

Before saving, verify:

  • Each story completable in one iteration
  • Stories ordered by dependency
  • All criteria include "Typecheck passes"
  • UI stories include "Verify at localhost:3000/..."
  • No vague criteria ("works", "good", "correct")
  • Story IDs are sequential (US-001, US-002, ...)
  • dependsOn is populated (empty array if no dependencies)
  • Dependencies reference existing PRD names (without extension)

After Conversion

Created prds/[feature-name].json with [N] stories
Dependencies: [list or "none"]
Branch: ralph/[feature-name]

Run: /ralph-json-start-loop

Ralph

Run the autonomous loop to execute features from prds/ directory.

Usage

/ralph              # Run next available project (respects dependencies)
/ralph 25           # Run with 25 iterations
/ralph auth-flow    # Run specific project

Process

Run the loop script in background mode:

~/.claude/skills/ralph/ralph.sh [iterations] [project-name]

Use run_in_background: true to prevent timeout. After starting, tell the user to check progress with tail -f <worktree>/.ralph-progress.txt.

What It Does

  1. Shows dependency graph, finds next available project
  2. Creates git worktree at ../{repo}-{feature}/
  3. For each iteration:
    • Picks first story where passes: false
    • Implements it, runs quality checks
    • Commits: feat: [id] - [title]
    • Updates JSON, syncs back to main repo
  4. When all stories pass, outputs <promise>COMPLETE</promise>

Dependencies

Ralph reads dependsOn from each PRD and enforces ordering:

{
  "projectName": "Dashboard",
  "dependsOn": ["auth-flow", "user-profile"]
}

Projects with incomplete dependencies are blocked. Ralph picks the first ready project alphabetically.

Prerequisites

  1. At least one .json PRD file in .claude/plans/, plans/, or prds/
  2. Use plan mode to create a plan, then run /ralph-json-create-issues to convert it

Notes

  • Run multiple Ralphs in parallel on independent projects (separate terminals)
  • Each works in its own worktree, no conflicts

Red Pen

You are a ruthless but fair copy editor. Your job is to find every place where the writing is flabby, vague, pretentious, or typographically sloppy — and say so clearly. You don't rewrite the piece. You mark it up and explain what's wrong.

How to review

Read the entire piece first. Then go through it again and flag every issue you find. Group your feedback into three sections: Language, Typography, and AI Tells. Within each section, list issues in the order they appear in the text.

For each issue:

  1. Quote the offending passage (keep it short — just enough to locate it)
  2. Name the problem in a few words
  3. Suggest a fix or, if the fix is obvious, just explain why it's a problem

After the issue list, close with a brief overall impression — one or two sentences on the piece's biggest strengths and its single most important area for improvement.

Don't sugarcoat, but don't be cruel. The goal is to make the writing better, not to make the writer feel bad.

Language rules

Inspired by Orwell's rules. The spirit matters more than the letter — Orwell's sixth rule is "Break any of these rules sooner than say anything outright barbarous."

Dead metaphors

Flag any metaphor, simile, or figure of speech that has lost its force through overuse. These are phrases people reach for without thinking about what the words actually mean. Examples: "level playing field", "think outside the box", "at the end of the day", "move the needle", "low-hanging fruit", "deep dive", "unpack", "lean in", "double down".

The test: if you've seen it in a hundred blog posts, it's dead. Fresh metaphors that create a vivid picture are fine — encouraged, even.

Long words where short ones will do

Flag words like "utilize" (use), "implement" (do, carry out), "leverage" (use), "facilitate" (help), "methodology" (method), "prior to" (before), "in order to" (to), "at this point in time" (now), "due to the fact that" (because).

This isn't about dumbing things down. Technical terms earn their place when they carry precise meaning that a simpler word doesn't. "Kerning" is fine in a typography discussion. "Utilizing a leveraged methodology" is not fine anywhere.

Cut unnecessary words

Flag padding. Common offenders: "very", "really", "quite", "rather", "somewhat", "basically", "actually", "literally" (when not literal), "just" (when it adds nothing), "that" (when the sentence works without it), "in terms of", "with regard to", "the fact that".

Also flag throat-clearing openings: "It is important to note that...", "It should be pointed out that...", "It goes without saying that..." — if it goes without saying, don't say it.

Passive voice

Flag passive constructions where the active voice would be clearer and more direct. "The decision was made to..." → who made it? "Mistakes were made" → by whom?

Not all passives are bad. Sometimes the actor is unknown, irrelevant, or deliberately de-emphasized. "The bridge was built in 1904" is fine — who built it isn't the point. Use judgment. But when passive voice hides responsibility or just makes the sentence weaker, flag it.

Pretentious diction and jargon

Flag words that dress up simple ideas in fancy clothing: "paradigm", "synergy", "holistic", "ecosystem" (outside biology), "deliverable", "actionable", "scalable" (outside engineering), "learnings" (not a word — use "lessons"), "cadence" (when you mean "schedule"), "align" (when you mean "agree").

Also flag foreign phrases that have everyday English equivalents: "vis-à-vis" (about, compared with), "inter alia" (among other things), "mutatis mutandis" (with the necessary changes).

Typography rules

These apply to the characters on the page. In markdown, some of these are limited by what the format supports, so focus on what the author can actually control.

Straight vs. curly quotes

Straight quotes (" and ') are typewriter leftovers. Proper text uses curly quotes (" " and ' '). Flag any straight quotes in body text. Exception: code samples, where straight quotes are correct.

Apostrophes

Apostrophes should be curly and point the right direction — the same character as a closing single quote ('). Flag straight apostrophes in body text. Watch especially for apostrophes at the start of abbreviated years ('90s, not '90s) — many tools get the direction wrong.

Hyphens and dashes

Three different characters, three different jobs:

  • Hyphen (-): joins compound words. "well-known", "state-of-the-art"
  • En dash (–): ranges and connections. "pages 10–15", "the London–Paris flight"
  • Em dash (—): breaks in thought. "The project — if it ever ships — will change everything."

Flag double hyphens (--) used as em dashes. Flag hyphens used for ranges. In markdown, flag any ambiguous dash usage.

Ellipses

Use the proper ellipsis character (…), not three periods (...). Flag three consecutive periods.

Spaces between sentences

One space, not two. Flag double spaces after periods.

Exclamation points

No more than one per document longer than three pages. Flag excessive exclamation points. In blog posts and professional writing, they almost always weaken the prose — if the sentence is exciting, the words should convey that.

Emphasis

Flag underlining for emphasis — use bold or italic instead. Flag bold and italic used together on the same text. Flag ALL CAPS used for emphasis in body text (short headings or labels are OK).

AI tells

These patterns mark prose as AI-generated. Always flag them.

Em dashes

Flag every em dash. AI text uses em dashes as an all-purpose connector where a period, comma, colon, or parentheses would be more precise. The author can decide which ones to keep, but the default should be: replace it with the punctuation that actually fits.

"Not X, but Y" and negative parallelism

Flag every instance of the negation-then-correction pattern: "It's not about speed, it's about precision." "This isn't a limitation — it's a feature." "The goal isn't to replace humans, but to augment them." This structure is the single most recognizable AI writing tic. Rewrite to state what something is rather than what it isn't.

Sycophantic hedging and throat-clearing

Phrases that sound diplomatic but say nothing: "It's worth noting that", "Interestingly,", "To be sure,", "That said,", "It bears mentioning". These are filler that AI reaches for to sound thoughtful. Cut them.

False profundity

Vague closing statements that gesture at depth without delivering it: "And that changes everything.", "The implications are profound.", "This is just the beginning.", "And perhaps that's the point." If the sentence could end any essay on any topic, it's not saying anything. Flag it.

Formulaic structure

AI tends to produce suspiciously balanced paragraphs: problem-solution-implication, three-part lists, mirror-image sentence pairs. If every section follows the same template, flag the monotony. Real writing has varied rhythm.

"Delve", "tapestry", "landscape", "navigate", "nuanced"

These are AI vocabulary tells — words that appear far more frequently in AI-generated text than in human writing. Also watch for: "foster", "crucial", "realm", "robust", "comprehensive", "straightforward", "moreover", "furthermore". Flag them.

What not to flag

  • Intentional stylistic choices that clearly serve the writing (Orwell's sixth rule)
  • Technical terminology used precisely in its proper domain
  • Quotes from other people — you're editing the author's words, not their sources
  • Code samples, URLs, or other literal strings
  • Markdown formatting conventions (like **bold** syntax)

Output format

Present your review in chat. Use this structure:

## Language

1. "the offending phrase" — **Problem name.** Explanation and/or suggested fix.
2. ...

## Typography

1. "the offending characters" — **Problem name.** Explanation and/or suggested fix.

## AI Tells

1. "the pattern or phrase" — **Problem name.** Explanation.

## Overall

One to two sentences.

Keep it scannable. The author should be able to read through, nod or disagree with each point, and get back to editing quickly.

AGENTS.md Skill

Overview

Creates and refactors AGENTS.md files following progressive disclosure principles. Keeps files minimal and focused—avoiding the "ball of mud" that hurts agent performance.

When to Use

  • Proactively when a project has no AGENTS.md at the root — check for this when starting work in a new project
  • Creating a new AGENTS.md from scratch
  • Refactoring a bloated AGENTS.md
  • Reviewing an existing file for best practices
  • Setting up AGENTS.md for a monorepo
  • When AGENTS.md exists but CLAUDE.md is missing (should be symlinked)

Core Principles

  1. Minimal by default: Only include what's relevant to every single task
  2. Progressive disclosure: Point to separate files, external docs, or agent skills for domain-specific rules
  3. Never document file structure: It goes stale fast and poisons agent context
  4. Describe capabilities, not locations: "Auth uses JWT" not "Auth is in src/auth/"

The Instruction Budget

Frontier LLMs can follow ~150-200 instructions with reasonable consistency. Every token in AGENTS.md loads on every request, regardless of relevance. The ideal file should be as small as possible.

Why Files Get Bloated

Agent does something wrong → you add a rule → repeat hundreds of times → "ball of mud." Different developers add conflicting opinions. Nobody does a full style pass. Auto-generated files make this worse by prioritizing comprehensiveness over restraint.

Stale Docs Poison Context

Humans can be skeptical of outdated docs. Agents can't — they trust what they read on every request. File paths are especially dangerous since they change constantly. Describe capabilities and domain concepts instead.

Process

Phase 0: Detect Missing Files

Check the project root for AGENTS.md and CLAUDE.md:

  1. If neither exists, offer to create AGENTS.md and symlink CLAUDE.md to it
  2. If AGENTS.md exists but CLAUDE.md does not, create the symlink: ln -s AGENTS.md CLAUDE.md
  3. If CLAUDE.md exists but AGENTS.md does not, rename it to AGENTS.md and create a symlink: mv CLAUDE.md AGENTS.md && ln -s AGENTS.md CLAUDE.md
  4. If both exist but CLAUDE.md is not a symlink to AGENTS.md, merge any unique content into AGENTS.md, remove the standalone CLAUDE.md, and create the symlink

Phase 1: Assess Current State

For new projects:

  • Ask about the project's purpose (one sentence)
  • Ask about package manager (if not npm)
  • Ask about non-standard build commands

For existing files:

  • Read the current AGENTS.md
  • Count lines and estimate token cost
  • Identify content that belongs elsewhere

Phase 2: Apply the Essential Test

Only these belong in root AGENTS.md:

IncludeWhy
One-sentence project descriptionAnchors every agent decision
Package manager (if not npm)Prevents wrong commands
Non-standard build/test commandsSaves trial and error
Links to domain-specific docsProgressive disclosure

Everything else goes in separate files or gets deleted.

Phase 3: Identify Anti-Patterns

Flag these for removal or relocation:

  • File tree structures: Always go stale, waste tokens
  • Obvious instructions: "Write clean code", "Use meaningful names"
  • Contradictory rules: Often from multiple contributors
  • Language-specific conventions: Move to docs/TYPESCRIPT.md etc.
  • Workflow instructions: Move to docs/GIT.md or docs/TESTING.md

Phase 4: Create Progressive Disclosure Structure

For content that shouldn't be deleted:

docs/
├── TYPESCRIPT.md    # TS conventions
├── TESTING.md       # Test patterns
├── API.md           # API design rules
└── GIT.md           # Commit/PR conventions

Reference these from AGENTS.md with light-touch pointers. Keep the tone conversational — no "ALWAYS," no all-caps forcing:

For TypeScript conventions, see docs/TYPESCRIPT.md

Each file can reference the next — agents walk the tree on demand, only loading what's relevant.

Link to external docs when they're the authoritative source rather than restating them:

For database migrations, follow the Prisma migration guide.

Agent skills are another layer of progressive disclosure. Instead of embedding procedures in AGENTS.md, package them as skills the agent pulls in when needed. The root file stays focused on what and where; skills handle how.

Phase 5: Handle Monorepos

For monorepos, use nested AGENTS.md files:

Root AGENTS.md:

Monorepo for [purpose]. Uses [pnpm/yarn] workspaces.
See each package's AGENTS.md for specifics.

Package AGENTS.md (e.g., packages/api/AGENTS.md):

GraphQL API using Prisma. See docs/API_CONVENTIONS.md for patterns.

Phase 6: Output

Provide:

  1. The new/refactored AGENTS.md content
  2. Any new files created for progressive disclosure
  3. List of removed content with reasoning

Output Format

When creating a new AGENTS.md:

# [Project Name]

[One-sentence description of what this project does.]

[Package manager if not npm]

[Non-standard commands if any]

[Light-touch pointers to separate docs if needed]

Example: Minimal AGENTS.md

# Acme Dashboard

React admin dashboard for managing customer accounts and billing.

Uses pnpm. Run `pnpm check` for type checking.

For API conventions, see docs/API.md
For component patterns, see docs/COMPONENTS.md

That's 6 lines. Every token earns its place.

Refactoring Prompt

When refactoring an existing bloated file, follow these steps:

  1. Find contradictions: Identify conflicting instructions. Ask which to keep.
  2. Identify essentials: Extract only what belongs in root — project description, package manager, non-standard commands, content relevant to every task.
  3. Group the rest: Organize into logical categories. Create separate files.
  4. Create structure: Output minimal root AGENTS.md with links to separate files.
  5. Flag for deletion: Identify instructions that are redundant, vague, or obvious.

Decision Framework

Before adding anything to AGENTS.md:

LocationWhen to use
Root AGENTS.mdRelevant to every single task
Separate fileRelevant to one domain
Nested docsFits hierarchical organization
Delete itObvious, redundant, or vague

Cross-Tool Compatibility

AGENTS.md is an open standard supported by 20+ tools including:

  • GitHub Copilot (Coding Agent)
  • Cursor
  • Codex (OpenAI)
  • Gemini CLI (Google)
  • Windsurf, Devin (Cognition)
  • Zed, Warp, VS Code
  • Aider, goose, RooCode

Claude Code uses CLAUDE.md instead. AGENTS.md is always the source of truth. CLAUDE.md must always be a symlink pointing to it:

ln -s AGENTS.md CLAUDE.md

Never create a standalone CLAUDE.md. Never put content in CLAUDE.md that isn't in AGENTS.md.

Resources

Review PR Comments

Fetch, evaluate, and address PR review comments from GitHub. Many reviewer comments reference outdated code or misunderstand the logic — always verify against the actual codebase before acting.

Process

This is a single-pass flow. Fetch comments, read files, evaluate, present assessment, reply to all comments, resolve all threads, and show the final summary — all without pausing for user confirmation.

1. Find the PR

If no PR number is provided, find the PR for the current branch:

gh pr list --head $(git branch --show-current) --json number,title --jq '.[0]'

2. Fetch Review Comments

Fetch comments with their IDs:

gh api repos/{owner}/{repo}/pulls/{number}/comments --jq '.[] | {id: .id, path: .path, line: (.line // .original_line), body: .body, in_reply_to_id: .in_reply_to_id}'

Filter to only top-level comments (where in_reply_to_id is null).

3. Read Referenced Files (Critical Step)

Before evaluating any comment, read the actual current code. Reviewers often:

  • Reference line numbers from an older commit
  • Misread the logic
  • Comment on code that's already been fixed

For each unique file path, read the file and verify:

  • Does the line number match what the reviewer is describing?
  • Has the issue already been addressed?
  • Is the reviewer's understanding of the code correct?

4. Evaluate All Comments

Categorize each comment:

CategoryCriteriaResponse
Already addressedIssue was fixed in a subsequent commit, or reviewer misread the codeExplain what the code actually does
FixValid bug, security issue, or typo that exists in current codeImplement the fix
Won't fixOver-engineering, style preference, feature request, or would break consistencyExplain reasoning

5. Present Assessment, Reply, and Resolve

Do all of this in one pass — no pausing for user confirmation. Present your assessment, reply to each comment, and resolve all threads immediately.

Present ALL comments with your assessment:

## PR #[number]: [title]

Found [X] review comments. Here's my assessment:

---

### 1. `path/file.ts:42` — **Already addressed**
> [comment body]

**Issue**: Reviewer concerned about X
**Actual code**: Lines 26-34 already handle this — [brief explanation]

---

### 2. `path/other.ts:15` — **Won't fix**
> [comment body]

**Issue**: Reviewer wants X
**Why skip**: [Over-engineering / Matches existing pattern / Feature request / etc]

---

### 3. `path/file.ts:88` — **Fix**
> [comment body]

**Issue**: Typo in user-facing string
**Proposed change**: Change "Jumpope" to "Jump Rope"

---

## Summary
- **Already addressed**: 6 comments
- **Won't fix**: 8 comments
- **Fix**: 2 comments

Then immediately reply to all comments and resolve all threads (steps 6-7 below). Don't wait for user input.

6. Reply to Comments

For Already addressed comments, reply explaining the current state:

gh api repos/{owner}/{repo}/pulls/{pr_number}/comments/{comment_id}/replies \
  -X POST \
  -f body="This is already handled — lines 26-34 fetch the authenticated user and verify user.id === state before proceeding. If they don't match, it rejects with a CSRF error."

For Won't fix comments, reply with concise reasoning:

gh api repos/{owner}/{repo}/pulls/{pr_number}/comments/{comment_id}/replies \
  -X POST \
  -f body="Won't fix — this matches the exact pattern used for the other integrations in the same file. Changing just this one would be inconsistent."

For Fix comments, implement the fix first, then reply:

gh api repos/{owner}/{repo}/pulls/{pr_number}/comments/{comment_id}/replies \
  -X POST \
  -f body="Fixed in abc1234"

7. Resolve All Threads

First, get all unresolved thread IDs:

cat << 'QUERY' | gh api graphql --input - --jq '.data.repository.pullRequest.reviewThreads.nodes[] | select(.isResolved == false) | {threadId: .id, commentId: .comments.nodes[0].databaseId}'
{"query": "query($owner: String!, $repo: String!, $pr: Int!) { repository(owner: $owner, name: $repo) { pullRequest(number: $pr) { reviewThreads(first: 100) { nodes { id isResolved comments(first: 1) { nodes { databaseId } } } } } } }", "variables": {"owner": "OWNER", "repo": "REPO", "pr": 123}}
QUERY

Then resolve each thread by ID:

cat << 'QUERY' | gh api graphql --input -
{"query": "mutation { resolveReviewThread(input: {threadId: \"THREAD_ID_HERE\"}) { thread { isResolved } } }"}
QUERY

8. Final Summary

After replying and resolving, show the final summary:

## Review Complete

All 16 conversations resolved.

### Already addressed (6)
| Comment | Explanation |
|---------|-------------|
| State validation | Already validates user.id === state at lines 26-34 |
| HR zones docs | Comments already say "milliseconds", not "percentage" |

### Won't fix (8)
| Comment | Reason |
|---------|--------|
| Form semantics | Matches existing pattern for other integrations |
| Rate limiting | Self-heals on next cron run, over-engineering |

### Fixed (2)
| Commit | Fix |
|--------|-----|
| `abc123` | Fixed typo "Jumpope" → "Jump Rope" |

Important: The entire flow (assess → reply → resolve → summarize) happens in one pass. Don't pause to ask "should I proceed?" — just do it.


Evaluation Guidelines

Already Addressed — Explain, don't fix

Common patterns where the reviewer is wrong:

  • Reviewer references wrong line numbers: Code has changed since they reviewed
  • Reviewer misread the logic: e.g., thinks condition is inverted when it's correct
  • Issue was already fixed: Subsequent commits addressed it
  • Code exists elsewhere: The check/validation happens in a different function

Response template:

"This is already handled — [specific location] does [what it does]. [Brief explanation of why it's correct]."

Fix — Implement and commit

Only fix issues that:

  • Actually exist in the current code
  • Are bugs, security issues, or typos
  • Can be verified by reading the file

Won't Fix — Explain reasoning

ReasonResponse template
Matches existing pattern"Won't fix — this matches the exact pattern of X, Y, and Z in the same file. Changing just this would be inconsistent."
Over-engineering"Won't fix — [the failure mode] will fail obviously / self-heal on retry / is handled by [existing mechanism]."
Feature request"Won't fix — this is a feature request rather than a bug. The current flow works: [what it does]. Out of scope for this PR."
Product decision"Won't fix — this is a product decision, not a bug. [Current behavior] is intentional because [reason]."
Would break things"Won't fix — this would break [existing behavior / consistency with X]."

Common Reviewer Misunderstandings

Inverted conditions

Reviewers often misread boolean logic. Example:

// "Refresh if expires in less than 5 minutes"
if (expiry.getTime() - Date.now() > 5 * 60 * 1000) {
  return integration.access_token!; // Token is fresh, return early
}
// Proceed to refresh...

Reviewer says: "Condition is inverted, tokens never refresh" Reality: Condition is correct — returns early when fresh, refreshes when stale.

Missing validation that exists

Reviewer says: "State parameter not validated" Reality: Lines 26-34 already validate it. Always check if the validation exists before agreeing.

Tokens in error messages

Reviewer says: "Sensitive tokens logged in error messages" Reality: The error logs the API's error response, not our tokens. Read what's actually in the error string.

Code that doesn't exist at that line

Reviewer references line 174, but file only has 161 lines. The file has changed since the review.


Key Principles

  1. Single-pass execution: Don't pause to ask "should I proceed?" — assess, reply, resolve, and summarize in one flow
  2. Verify before acting: Always read the actual file before evaluating a comment
  3. Trust the codebase: If existing patterns work, new code should match them
  4. Explain, don't just dismiss: Skipped comments deserve clear explanations
  5. Resolve everything: All threads should be resolved, whether fixed or explained
  6. Be concise: Responses should be 1-2 sentences, not paragraphs

Skill Review

Overview

Validates agent skills against the Agent Skills standard and compiled best practices. Reviews structure, frontmatter, description quality, progressive disclosure, and common anti-patterns.

When to Use

  • User asks to review or validate a skill
  • User is creating a new skill and wants feedback
  • User asks "is this skill well-written?"
  • User mentions skill quality, best practices, or improvement

Review Process

Phase 1: Load References

Before reviewing, read:

  • references/best-practices.md — Comprehensive guidelines
  • references/checklist.md — Quick validation checklist

Phase 2: Identify Target

Determine what to review:

  • Single skill: Review skills/<name>/SKILL.md and its structure
  • All skills: Audit entire skills/ directory
  • New skill draft: Review provided content before creation

Phase 3: Structural Audit

Check the skill directory structure:

skill-name/
├── SKILL.md              # Required
├── references/           # Optional - loaded docs
├── scripts/              # Optional - executable code
└── assets/               # Optional - output files (not loaded)

Verify:

  • SKILL.md exists
  • Directory name matches name in frontmatter
  • References are one level deep (no nested chains)
  • Scripts use forward slashes (no Windows paths)
  • No extraneous files (README.md, CHANGELOG.md, etc.)
  • Script paths in SKILL.md body (scripts/foo.py) exist in directory
  • If scripts use external binaries, dependencies are documented

Phase 4: Frontmatter Validation

Check YAML frontmatter:

---
name: skill-name          # Required: lowercase, hyphens, ≤64 chars
description: >-           # Required: ≤1024 chars, third-person
  What it does. When to use it.
---

Validate:

  • name: Lowercase with hyphens only ([a-z0-9-])
  • name: ≤64 characters
  • name: No "anthropic" or "claude" in name
  • description: Non-empty, ≤1024 characters
  • description: Third-person voice (not "I can" or "You can")
  • description: Includes what it does AND when to trigger
  • description: Contains specific trigger phrases

Phase 5: Description Quality

The description is the triggering mechanism. Evaluate:

Good descriptions include:

  • Specific actions: "Extract text and tables from PDF files"
  • Trigger phrases: "Use when analyzing Excel files, spreadsheets, or .xlsx"
  • Synonyms users might say: "tabular data, CSV, workbooks"

Bad descriptions:

  • Vague: "Helps with documents"
  • Generic: "Processes data"
  • Missing triggers: "Analyzes spreadsheets" (no "when to use")

Phase 6: Body Analysis

Review SKILL.md body content:

Length:

  • Under 500 lines (check with wc -l)
  • If longer, split into reference files

Progressive Disclosure:

  • Quick start or overview near top
  • Details moved to references/
  • Long reference files (>100 lines) have TOC

Token Efficiency:

  • No obvious explanations (Claude already knows)
  • Examples over lengthy prose
  • Each line justifies its token cost

Degrees of Freedom:

  • High freedom for context-dependent tasks
  • Low freedom for fragile/error-prone tasks
  • Defaults provided when multiple options exist

Phase 7: Anti-Pattern Check

Scan for common issues:

Anti-PatternLook For
Windows pathsscripts\file.py instead of scripts/file.py
Nested referencesA.md → B.md → C.md chains
Time-sensitive info"If before August 2025..."
Magic numbersUnexplained values
Too many options"You can use X, or Y, or Z..." without default
Inconsistent termsMixing "endpoint"/"URL"/"route"
User-facing docsREADME, CHANGELOG, installation guides
First/second person descriptions"I can help" or "You can use"

Phase 8: Report Findings

Present findings using this format:

## Skill Review: [skill-name]

### Summary
[1-2 sentence overall assessment]

### Structure
[✓/✗] Directory organization
[✓/✗] File presence
[✓/✗] Reference depth

### Frontmatter
[✓/✗] name validation
[✓/✗] description validation

### Description Quality
**Score**: [Strong / Adequate / Needs Work]
**Issues**: [List specific problems]
**Suggested rewrite** (if needed):
```yaml
description: >-
  [Improved description]

Body Analysis

Line count: [X] lines Token efficiency: [Good / Could trim] Progressive disclosure: [✓/✗]

Anti-Patterns Found

  • [Issue 1] — Location: file:line
  • [Issue 2] — Location: file:line

Recommendations

  1. [Actionable fix]
  2. [Actionable fix]

## Quick Review Mode

For rapid validation, run through the checklist in `references/checklist.md` and report only failures.

## Resources

### references/best-practices.md
Comprehensive guide covering architecture, design principles, writing effective descriptions, bundled resources, workflow patterns, and advanced patterns from production skills.

### references/checklist.md
Quick-reference validation checklist for fast reviews.

Technical Writing Skill

Overview

Create technical blog posts about features you're building. This skill analyzes your codebase to understand implementations, then structures clear, engaging content that balances technical detail with readability while avoiding AI-sounding language.

Process

Phase 1: Research and Planning

1.1 Load Writing Guides (REQUIRED - Load First)

Before any other work, load the following:

  1. Writing Rules (from WRITING_ANTI_PATTERNS_PATH env var, or fall back to references/anti-patterns.md) - Comprehensive lists of AI-sounding words, phrases, and patterns to avoid. This is the foundation - what NOT to sound like.

  2. Writing Style Guide (from WRITING_STYLE_GUIDE_PATH env var, or fall back to references/style-guide.md) - Personal writing voice, tone, structure, and signature moves. This is the voice layer - what TO sound like.

PRIORITY RULE: When guides conflict, anti-patterns win. Avoiding AI patterns always takes precedence over stylistic choices.

1.2 Fetch WordPress Taxonomy (if configured)

If WORDPRESS_URL, WORDPRESS_USERNAME, and WORDPRESS_APP_PASSWORD env vars are set, fetch available categories and tags before writing so frontmatter uses existing taxonomy:

curl -s -u "$WORDPRESS_USERNAME:$WORDPRESS_APP_PASSWORD" \
  "$WORDPRESS_URL/wp-json/wp/v2/categories?per_page=100" | python3 -c "import sys,json; [print(c['name']) for c in json.load(sys.stdin)]"

curl -s -u "$WORDPRESS_USERNAME:$WORDPRESS_APP_PASSWORD" \
  "$WORDPRESS_URL/wp-json/wp/v2/tags?per_page=100" | python3 -c "import sys,json; [print(t['name']) for t in json.load(sys.stdin)]"

Use these when choosing category and tags in frontmatter. Prefer existing values. Skip this step if WordPress env vars are not set.

1.3 Understand What Was Built

Investigate the codebase to understand the feature:

  • Ask which feature or changes they want to write about
  • Use git to check recent commits if relevant (skip if not a git repo): git log --oneline -10
  • Read relevant code files to understand implementation
  • Identify key technical decisions, architecture, and interesting details
  • Note any challenges solved or clever solutions

1.4 Plan the Structure

Plan what to cover in the post. Use these as a guide, not a rigid template:

  • Opening: Start with an engaging hook or context for what you built
  • Overview: Brief explanation of the feature (2-3 sentences)
  • Problem/Value: Why this matters or what problem it solves
  • Technical Details: How it works with code snippets
    • Key implementation details
    • Interesting technical decisions
    • Architecture or design patterns used
  • Challenges: What was tricky and how you solved it (if relevant)
  • Future: Next steps or related features (if relevant)
  • Tech Stack: Technologies used (can be woven into the narrative or listed)

The actual headings, structure, and flow should feel natural to the specific post - not formulaic.

Phase 2: Writing

2.1 Draft Creation

Create the blog post applying BOTH guides you loaded in Phase 1. After drafting, re-read the post against the anti-patterns guide and fix any violations before saving.

Code Snippets:

  • Keep snippets short (5-15 lines)

Target length: Match length to complexity. Default short.

  • Simple idea, announcement, or single concept: 400-600 words
  • Moderate technical walkthrough: 600-900 words
  • Deep architectural dive or multi-part explanation: 900-1200 words

Err on the side of shorter. If the post can be said in 500 words, don't stretch it to 800. Cut filler, merge thin sections, and stop when the point is made.

2.2 Save the Draft

Save the completed blog post to the drafts directory (create the folder if missing).

To find the save path, run: echo $WRITING_DRAFTS_PATH

  • If the output is non-empty, save there
  • If empty, fall back to .drafts/ in the current project

File naming convention:

  • Format: YYYY-MM-DD-slug.md
  • Slugs should be short, memorable, and easy to type — two words max
  • Capture the core concept of the post, not necessarily the title
  • Think "what would I type after the domain name?"
  • Examples: 2025-12-29-ralph.md (post: "How I Got Ralph to Ship Overnight"), 2026-01-10-listen.md (post: "Giving my blog a voice"), 2025-11-15-choosing-open.md (post: "WordPress Almost Didn't Happen" — about choosing open source)

Frontmatter (REQUIRED):

Every draft must start with YAML frontmatter containing title and url:

---
title: How I got Ralph to ship overnight
url: /ralph
category: Development
tags:
  - AI
  - Shipping
---
  • title — the post title (do NOT repeat as an H1 in the body). Titles should be short (3-7 words), evocative, and leave room for curiosity. Don't explain the whole post — hint at it. Think newspaper headline, not description.
    • Good: "Giving my blog a voice", "WordPress Almost Didn't Happen", "Planning Out Loud"
    • Bad: "I built a skill that writes blog posts from my codebase" (too long, explains everything)
  • url — the permalink path, matching the filename slug (e.g. /ralph, /listen, /choosing-open)
  • category — WordPress category (use an existing one from Phase 1.2 when available)
  • tags — WordPress tags (prefer existing ones from Phase 1.2)

Phase 3: Publishing (Optional)

3.1 WordPress Publishing

If the user wants to publish to WordPress, load WordPress Publishing Guide (references/wordpress-publishing.md) for complete setup and publishing instructions.

The guide covers:

  • Environment setup and credentials
  • Python dependencies installation
  • Publishing commands and workflow
  • Smart update tracking (no duplicate posts)
  • Troubleshooting common issues

Quick summary:

  • First time: Creates new WordPress draft
  • Subsequent: Updates existing draft (no duplicates)
  • Always saves as draft (never auto-publishes)
  • Returns post URL and edit URL

Output Format

After creating and saving the blog post, provide:

  1. Saved Location: Path where the post was saved
  2. Post Title: The final title used
  3. Key Files Referenced: List of files mentioned with line numbers
  4. Word Count: Approximate length

Example Interaction

User: "Help me write about the voice planning feature"

Response:

Let me investigate the voice planning implementation to write about it.

[Phase 1: Loads anti-patterns + style guide, fetches WP taxonomy, reads code]

[Phase 2: Creates and saves blog post applying both guides]

Blog post saved to: .drafts/2025-12-29-planning-aloud.md

Title: "Planning Out Loud"

Key Files Referenced:
- src/components/voice-session.tsx:78 (voice session initialization)
- src/app/api/webhook/route.ts:40 (webhook signature validation)
- src/lib/claude.ts:88 (Claude tool calling)

Word Count: ~550 words

Environment Variables

Configure in Claude Code settings (~/.claude/settings.json) under the env key:

{
  "env": {
    "WRITING_STYLE_GUIDE_PATH": "/path/to/style-guide.md",
    "WRITING_ANTI_PATTERNS_PATH": "/path/to/anti-patterns.md",
    "WRITING_DRAFTS_PATH": "/path/to/drafts",
    "WORDPRESS_URL": "https://yourblog.com",
    "WORDPRESS_USERNAME": "your_username",
    "WORDPRESS_APP_PASSWORD": "xxxx xxxx xxxx xxxx",
    "WRITING_TITLE_CASE_STYLE": "title",
    "WRITING_HEADING_CASE_STYLE": "sentence"
  }
}
VariableRequiredDescription
WRITING_STYLE_GUIDE_PATHNoPath to shared writing style guide. Loaded in Phase 1.1
WRITING_ANTI_PATTERNS_PATHNoPath to shared anti-patterns. Overrides references/anti-patterns.md
WRITING_DRAFTS_PATHNoWhere to save drafts. Falls back to .drafts/ in current project
WORDPRESS_URLFor publishingWordPress site URL (include https://)
WORDPRESS_USERNAMEFor publishingWordPress account username
WORDPRESS_APP_PASSWORDFor publishingApplication password (not regular password)
WRITING_TITLE_CASE_STYLENo"sentence" (default) or "title"
WRITING_HEADING_CASE_STYLENo"sentence" (default) or "title"

Tips for Best Results

  1. Be specific about scope: "Write about the webhook security implementation" is better than "write about webhooks"
  2. Mention target audience: "For developers familiar with Next.js" vs "For non-technical readers"
  3. Specify length preference: "Quick 500-word update" vs "Detailed deep-dive"
  4. Share context: "This is part 2 in a series" or "First post about this project"
  5. Request revisions: After the draft, ask to expand sections, simplify explanations, or adjust tone

Advanced: Series Posts

For multi-part series:

  • Start with "Help me outline a 3-part series about [topic]"
  • Each post should build on previous ones
  • Include "Previously" and "Next up" sections
  • Keep consistent structure across posts

WordPress Add Links

Find and add internal and external links to a blog post draft, naturally woven into existing sentences.

Trigger

  • "find links for this post"
  • "find internal links"
  • "add links to this post"
  • "link this draft"

Environment Variables

  • WORDPRESS_URL — Blog base URL (e.g. https://yourblog.com)
  • WORDPRESS_USERNAME — WordPress account username
  • WORDPRESS_APP_PASSWORD — Application password (not your regular password)

Process

Phase 1: Load the Post

Determine input type from what the user provides:

Local file — Read the markdown file. Parse any frontmatter for title, tags, or topic context.

WordPress URL — Extract the slug from the URL, then fetch via REST API:

curl -s "$WORDPRESS_URL/wp-json/wp/v2/posts?slug={slug}&_fields=id,title,content,tags,categories"

Store the post ID for later update if working from WordPress.

Phase 2: Fetch Internal Content

Fetch published posts from the same WordPress site:

curl -s -u "$WORDPRESS_USERNAME:$WORDPRESS_APP_PASSWORD" \
  "$WORDPRESS_URL/wp-json/wp/v2/posts?per_page=100&_fields=id,title,link,excerpt,tags,categories"

From the results:

  • Build a list of existing posts with titles, URLs, and excerpts
  • Identify posts that are topically relevant to the current draft
  • Internal links take priority over external links when both could cover the same topic

Phase 3: Find External Links

Use web search to find authoritative external references for key topics in the post (tools, libraries, concepts, standards).

Prefer in this order:

  1. Official documentation and project pages
  2. Primary sources (specs, RFCs, research)
  3. Well-known reference sites (MDN, Wikipedia)

Avoid linking to other blog posts or news articles unless no better source exists.

Phase 4: Add Links Inline

Insert links into the existing text. Rules:

  • Don't add new sentences or paragraphs — only add links to words/phrases already in the draft
  • Keep anchor text short — link the subject/topic (2–4 words), not full clauses or sentences. E.g. link "something new" not "Let each project teach you something new"
  • Natural reading test — if read aloud, the sentence should sound identical with or without the link
  • Link density constraints:
    • 3–5 internal links per post (fewer for shorter posts)
    • 2–4 external links per post (fewer for shorter posts)
  • No links in the opening paragraph — let the reader settle in
  • No link clustering — spread links across different paragraphs
  • No duplicate destinations — each URL appears once
  • No duplicate anchor text — each linked phrase is unique

Phase 5: Review with User

Do not explain what you found, list existing links, or narrate your process. Just present the table and ask for approval.

Present proposed links as a table using AskUserQuestion. Each link is a selectable option so the user can pick which ones to apply:

#TextURLTypeReason
1"block patterns"/block-patternsInternalRelated tutorial
2"WCAG"w3.org/WAI/WCAG21ExternalOfficial spec

Use AskUserQuestion with multiSelect: true so the user can check the links they want applied. List each link as an option (e.g. label: "block patterns" → /block-patterns, description: the reason).

Do not proceed to Phase 6 until the user selects links.

Phase 6: Save

After approval:

Local file — Overwrite the draft with the linked version.

WordPress post — Update via REST API:

curl -s -X POST \
  -u "$WORDPRESS_USERNAME:$WORDPRESS_APP_PASSWORD" \
  "$WORDPRESS_URL/wp-json/wp/v2/posts/{post_id}" \
  -H "Content-Type: application/json" \
  -d '{"content": "...updated HTML..."}'

Report final counts:

  • Internal links added: X
  • External links added: Y

X Writing Skill

Overview

Transform your notes, work updates, and observations into engaging X (Twitter) content. This skill analyzes your notes to identify the most shareable insights, then crafts authentic posts that match your voice and drive engagement.

Supports two idea sources — a markdown file (X_SOURCE_FILE) and/or macOS Notes (X_NOTES_APP_SOURCE). If both are configured, asks which to use.

Process

Phase 1: Preparation and Analysis

1.1 Load Writing Guides (REQUIRED - Load First)

Before any other work, load the following:

  1. Growth Principles (references/x-strategy.md) - Content selection criteria, what makes posts shareable, engagement patterns, and what to prioritize from notes. This guides WHAT to share.

  2. Writing Style Guide (from WRITING_STYLE_GUIDE_PATH env var) - Voice, tone, structure, banned phrases, and signature patterns. This guides HOW to share it. Skip if the env var is not set.

  3. Anti-Patterns - Run echo "$WRITING_ANTI_PATTERNS_PATH" to check the env var. If set, load that file. If not set, fall back to references/anti-patterns.md. AI writing patterns to avoid. Critical for ensuring posts sound human and authentic, not AI-generated. Avoid patterns like "It's not X, it's Y", formal transitions, hedging language, and AI-specific vocabulary.

PRIORITY RULE: When guides conflict, references/x-strategy.md wins. Content value and shareability take precedence over stylistic preferences. When the style guide and anti-patterns conflict, anti-patterns win.

1.2 Understand the Source Material

Get clarity on what notes to work with:

  • Ask which notes, ideas, or updates they want to transform into posts
  • Check for idea sources:
    • Run echo "$X_SOURCE_FILE" — if set, a markdown ideas file is available
    • Run echo "$X_NOTES_APP_SOURCE" — if set, a macOS Notes note is available (use scripts/fetch-notes.sh get to fetch)
    • If both are configured and the user says "check my ideas" or similar without specifying, ask which source to use
    • If one is configured, use it directly
    • If neither is configured, work from whatever the user provides (pasted content, markdown files, etc.)
  • Read the source material and identify the core insights, learnings, or updates
  • Note any specific tools, projects, numbers, or details mentioned

Multiple ideas/notes workflow:

  • When the user provides multiple distinct ideas or notes, work through them ONE AT A TIME
  • Create post options for the first idea
  • Wait for user approval/feedback before moving to the next idea
  • This prevents overwhelming the user and allows for refinement as you go

1.3 Apply Selection Criteria

Evaluate notes using the Content Selection Framework in references/x-strategy.md. Prioritize shipped work with learnings, non-obvious insights, and specific tool recommendations. Skip engagement bait, vague hype, and complaints without solutions.

Phase 2: Content Creation

2.1 Select the Best Angle

Identify one clear idea, the specific details that prove it, and the hook (first line).

2.2 Choose the Format

Default to single tweets. Only thread (2-5 tweets) when the story requires steps, multiple related insights, or before/after context. See Thread Strategy in references/x-strategy.md.

2.3 Draft the Content

Apply all three guides loaded in Phase 1 during drafting, not just as a post-check:

  • x-strategy.md — formatting rules, content strategy, High-Engagement Patterns, and Signature Patterns. Formatting is critical: one sentence per line, white space between lines, hook in first line, 180-250 chars, no italics.
  • Writing style guide (WRITING_STYLE_GUIDE_PATH) — voice, tone, banned phrases, language simplification. Apply casing preference from X_CASE_STYLE env var (standard by default). When set to "lowercase", use all lowercase including "i" as a pronoun — only capitalize personal names, WordPress, and product names.
  • Anti-patterns — actively avoid during drafting. If a draft uses any anti-pattern, rewrite before presenting. HARD RULE: NEVER use the "It's not X, it's Y" reframing pattern in any form. This includes: "isn't X, it's Y", "not because X, because Y", "isn't about X, it's about Y", "less about X, more about Y". Say the positive claim directly instead. Also avoid: em dashes, generic observations without specifics, and intensifiers.

2.4 Engagement Optimization

End ~70% of posts with engagement (specific question, teaser, or invitation). Let the rest land with a hard stop. See "What Makes Content Shareable" in references/x-strategy.md.

2.5 Quality Check

After drafting, re-read every post against the anti-patterns guide and fix any violations before presenting. Then verify:

  • Did I get to the point in line 1?
  • Is this specific? (names, numbers, examples)
  • Would I actually say this out loud?
  • Does it sound like ME, not ChatGPT?
  • Did I use any banned phrases from the writing style guide?
  • Did I avoid ALL anti-patterns? (reframing, em dashes, intensifiers, generic observations)
  • If it's a reaction, did I add MY angle?

Phase 3: Output

3.1 Present the Content

For each post created:

  1. The Post(s) - Show the actual tweet(s) ready to copy/paste
  2. Format - Indicate if it's a single tweet or thread
  3. Character Count - Show length (target: 180-250 chars)
  4. Pattern Used - Which pattern from x-strategy.md was applied
  5. Key Elements - What specifics, tools, or projects were highlighted

3.2 Offer Options

When appropriate, provide 2-3 variations:

  • Different angles on the same insight
  • Single tweet vs thread format
  • Different engagement endings

3.3 Explain Selections

Briefly note what was prioritized and why:

  • Which insights from notes were selected
  • Why certain details were emphasized
  • What was intentionally left out

3.4 Save Approved Posts

When the user approves a post, save it to the drafts file (create if missing).

File location (resolve before saving):

  1. Run echo "$X_DRAFTS_FILE" to check the env var
  2. If set, append to that file path
  3. If not set, default to .x/posts.md (top-level, create if missing)

Markdown format:

---

**Category:** Learning
**Date:** 2026-01-01

WordPress.com AI adds conversation alongside block editing.


People who couldn't navigate the UI before are shipping sites now. Others still use blocks for fine-tuning.

Both work. The conversation path just removes the skill barrier.

---

For threads, use [Tweet N] markers:

---

**Category:** Learning
**Date:** 2026-01-01

[Tweet 1]
WordPress.com AI changes how people build sites.


[Tweet 2]
People who couldn't navigate block editing are shipping now.

[Tweet 3]
The UI is still there for fine-tuning. But conversation removes the skill barrier.

[Tweet 4]
Ask or click. Both paths work.

---

Categories:

  • Learning - Insights, shipped updates with learnings
  • Update - Project progress
  • Tool - Recommendations
  • Observation - Industry takes

Workflow:

  1. Present the post(s) to the user
  2. When approved, append to X_DRAFTS_FILE or .x/posts.md
  3. User can copy-paste directly into X (text is ready with proper line breaks)
  4. User removes the section after posting, or asks you to remove it

Output Format

After creating social content, provide:

📱 Post 1 (Single Tweet, 210 chars)
─────────────────────────────────
[Actual tweet text ready to copy/paste]

Pattern: "Shipped X, learned Y"
Specifics: agents.foo, conversational context matching
Engagement: Specific question

─────────────────────────────────

From your notes, I prioritized:
✓ The discovery insight (most shareable)
✓ Why traditional search failed (specific learning)
✗ Timeline details (not core value)

Alternative angles:
• Focus on the technical implementation
• Thread breaking down the 3 attempts

Example Interaction

User: "Help me create a post from these notes about building the curation feature"

Response:

Let me analyze your notes and create X content.

[Phase 1: Loads references/x-strategy.md and writing style guide]
[Reads the notes, identifies key insights and specific details]

─────────────────────────────────
📱 Post (Single Tweet, 218 chars)
─────────────────────────────────

Shipped curation v1 for agents.foo today.

Discovery is way harder than app stores. Agents are conversations, not static features.

Had to rebuild around context matching instead of keyword search.

Pattern: "Shipped X, learned Y"
Key specifics: agents.foo, context matching vs keyword search
Engagement: Implicit (landing the insight)

─────────────────────────────────

From your notes, I selected:
✓ Core insight: agent discovery is different
✓ Specific solution: context matching
✓ Concrete detail: agents.foo
✗ Number of rebuild attempts (not essential to the insight)

Would you like me to:
• Save this approved post for tracking
• Create a thread version breaking down why search patterns failed
• Add a question ending for more engagement
• Draft additional posts from other insights in your notes

Tips for Best Results

  1. Provide context: "Notes from building curation feature" vs just pasting notes
  2. Mention specific parts: "Focus on the learning about context matching" helps prioritize
  3. Indicate quantity: "Create 3 posts from these notes" vs "create posts"
  4. Specify format preference: "Single tweets only" or "open to threads"
  5. Request variations: "Show me a few angles" gives options to choose from
  6. Iterate: After the draft, request adjustments: "Make it more specific" or "Add a question ending"

Environment Variables

VariableRequiredDescription
WRITING_STYLE_GUIDE_PATHNoPath to shared writing style guide. Loaded in Phase 1.1
WRITING_ANTI_PATTERNS_PATHNoPath to shared anti-patterns. Overrides references/anti-patterns.md
X_DRAFTS_FILENoFile path for saving approved posts. Default: .x/posts.md
X_SOURCE_FILENoPath to a markdown file containing post ideas. Read when the user asks to check ideas.
X_NOTES_APP_SOURCENomacOS Notes note name to fetch ideas from (e.g. "Tweets"). Uses scripts/fetch-notes.sh.
X_CASE_STYLENo"standard" (default) or "lowercase"

Sponsors

Details

Marketplace
richtabor/agent-skills
Author
Rich Tabor
Category
Productivity
Keywords
accessibility, writing, motion-design, code-review, product, prd, wordpress