Skip to content

Claude Workflow

Build multi-fallback matching for human-touched workflows

From legacy section: External API Integration

Why: Built the YouTube sync script (2026-05-18) assuming Joe would upload videos with the spec filename as the title (e.g. GMT20260518-113754_Recording). First real run matched 0/9 — turns out Joe had renamed 5 to the proper YT title, 4 had Zoom-default formats (GMT20260518 113754 Recording 640x360 with spaces and a resolution suffix), and Jim had even renamed one to the LESSON title (not the YT title from col I). The script's single exact-match strategy was too brittle. Fixed by adding 3-tier fallback: (1) exact filename, (2) exact YT title from spec, (3) timestamp substring after normalizing punctuation. Recovered 8/9 automatically; the 9th needed a one-off direct-update. The takeaway: if humans are typing titles between system steps, ALWAYS build the matching as a tiered fallback. The "intended workflow" never survives contact with reality. How to apply: Any script that matches user-generated identifiers (titles, filenames, slugs) → build 3+ fallback strategies before giving up. Order them by strictness (most strict first → most lenient last). Extract canonical keys (timestamps, IDs) from human-readable formats so partial matches still work. Always print which strategy matched so debugging is fast. Date: 2026-05-18

Skills Must Be Global (User-Level)

From legacy section: Competitive Audit Pipeline

Pattern: Skills in .claude/commands/ (project-level) only load from that project directory. Rule: After creating/updating any skill, ensure it's symlinked to ~/.claude/commands/ for global access. A PostToolUse hook automates this, but manual fallback: ln -sf "$CLAUDE_PROJECT_DIR/.claude/commands/SKILL.md" ~/.claude/commands/ Date: 2026-03-01

Follow Skill Steps Completely — Don't Ask Permission for Explicit Instructions

From legacy section: Competitive Audit Pipeline

Pattern: /session-cleanup Step 5 explicitly says to stage, commit, push, and verify. Instead of executing, asked Jim "Want me to commit and push?" — adding an unnecessary confirmation step for something the skill already authorized. Rule: When a skill's steps contain explicit actions (commit, push, update file, etc.), execute them. The skill IS the authorization. Only ask for confirmation when the skill says to ask, or when the action is destructive/ambiguous. Don't second-guess clear instructions. Date: 2026-03-20

Chunk Multi-Deliverable Skill Outputs to Survive Session Timeouts

From legacy section: Competitive Audit Pipeline

Pattern: Jim reported session-timed-out errors on previous SEO NEO sessions when a single skill (e.g., /neo-campaign) generated 5+ files at once. Long-running skill outputs in cloud sessions risk losing all work if the session dies mid-execution. Rule: When a skill produces multiple deliverables (3+ files), propose a chunking plan FIRST and get Jim's confirmation. Then execute each chunk as: (1) generate the files, (2) commit with descriptive message, (3) push to remote, (4) report status before starting next chunk. Each chunk = independent commit so a timeout only loses one chunk, not all of it. Pattern used successfully for Mid Ohio MBS SEO NEO buildout (3 chunks: HTML embeds → campaign core → supporting deliverables). Date: 2026-04-20

Subagent CDATA Wrapper in Blog Posts

From legacy section: WordPress MCP — Blog Scheduling

Pattern: One subagent wrapped its entire blog post content in <![CDATA[...]]> causing WordPress to render raw HTML as text instead of parsing it. Rule: After any subagent creates a WordPress post, check the rendered content for CDATA wrappers. If found, re-save the content with clean HTML via update_post. Date: 2026-04-07

/competitive-analysis skill: check for existing slug BEFORE create_page

From legacy section: Competitive Audit Automation (v1.1/v1.2)

Pattern: Ran a Medium-tier /competitive-analysis on Ianniello Anderson (ialawny.com) on 2026-05-20. Skill spec said POST /wp-json/wp/v2/pages with slug: "ianniello-anderson", parent 2304. There was already a published page at that exact slug from a May 18 auto-pipeline batch (page 2762). WP REST silently appended -2 to make the new slug unique, so the new audit landed at /audits/ianniello-anderson-2/ while /audits/ianniello-anderson/ still served the stale May 18 content. Had to manually update 2762 in place and trash 2968 to consolidate. The /audits/ index still pointed at the canonical URL — would have ended up with TWO IA entries if not caught. Why: Re-audits are common (Light → Medium upgrade, refreshed data, design system rebuilds). The skill's WordPress publishing step assumes new-slug-every-time and doesn't probe for the existing slug. Result: the canonical URL drifts stale while a -2-suffixed duplicate gets created. How to apply: In the skill's WordPress publishing step (and any future skill that publishes child pages under /audits/), ALWAYS do this sequence: (1) GET /wp-json/wp/v2/pages?slug=<slug>&status=publish,private,draft to check for an existing page; (2) if 1 result, prompt Jim to update-in-place or create-new-suffixed; (3) only POST a fresh create_page if confirmed no-existing-slug or user chooses fresh. Same goes for the /audits/ index update: re-find-and-update the existing row instead of unconditionally inserting at top. Date: 2026-05-20

Skill + VPS sharing a canonical spec eliminates drift, but only if the consumers actually inherit

From legacy section: Competitive Audit Automation (v1.1/v1.2)

Pattern: Pre-Plan 6, the competitive-analysis skill duplicated all tier content (sections, scoring, style rules) inline — 784 lines of skill, ~500 of which restated what was in docs/competitive-analysis-tier-spec.md. The VPS already had its own runtime spec-loading mechanism. When the spec changed (Section 4 schema rubric, Section 3.2 strategic scoring), the skill drifted because nobody manually updated it. Plan 6 made the skill READ the spec at runtime, same pattern the VPS uses — skill dropped to 322 lines. Rule: When two consumers should produce comparable output (same scoring, same sections, same style), they must inherit from one source. Inline duplication is a drift accelerator. The cost of "consumer reads a spec file at runtime" is one extra Read tool call; the cost of drift is reports that grade the same business differently depending on which consumer ran. Date: 2026-04-24

Local-only skill consumers can't use VPS webhook patterns

From legacy section: Competitive Audit Automation (v1.1/v1.2)

Pattern: The VPS LD heatmap integration uses webhook_url + preschedule_analysis: true — LD POSTs the completion callback to the VPS's /api/ld/webhook endpoint. The Claude Code skill runs locally; there's no public URL to give LD. Plan 6 had to use poll-based heatmap completion instead. Rule: When porting an integration from a server-with-public-URL to a local CLI, replace webhook delivery with polling. The skill's heatmap branch polls GET /v1/scans/{uuid} every 30s until the response includes share_links + coverage data. Slower than webhook (3–5 min wait vs. instant) but the only viable pattern locally. Same rule applies to any future migration of a webhook-driven server integration to a CLI-side equivalent. Date: 2026-04-24

NEO project location: ALWAYS clients/_active/<slug>/seoneo/, NEVER the skill spec's external path

From legacy section: SEO NEO / Workbook

Pattern: Built the entire Black Square Roofing NEO project (23 files: workbook, embeds, articles, citations) at ~/Downloads/Evolve-Tools/SEO_Tools/SEO_NEO_Projects/Black_Square_Roofing/ because that's the literal path in the /neo-project-setup skill spec — and the spec also pointed at a _CLIENT_TEMPLATE/ that didn't exist on the machine. When Jim caught it, the migration was 23 files + 31 path-reference fixes. The work was outside the repo, not in GitHub backup, split off from the rest of the client's docs (NAP.md, competitive-analysis.md, call transcripts). Rule: Before invoking any /neo-* skill, check Tali Kogan's structure as the working precedent: clients/_active/tali-kogan/seoneo/. That's where NEO work goes — INSIDE the client folder, not in an external Evolve-Tools/ tree. Folder names are lowercase-hyphen (excel-workbook, html-embeds, campaign-strategy, reference-documents, website-content), root files are lowercase (start-here.txt, readme.md, project-summary.md, quick-reference.md, campaign-timeline.md, file-index.md). Workbook xlsx names use Mixed_Case_Underscore (<Client>_SEO_NEO.xlsx, <Client>_Citations.xlsx). The /neo-project-setup skill spec's ~/Downloads/Evolve-Tools/... path is misleading legacy — IGNORE it. If the skill output references that path, override with the in-repo location. This rule applies to: /neo-project-setup, /neo-onboard, /neo-gbp-targets, /neo-nap-embed, /neo-semantic-triples, /neo-citations, /neo-keywords, /neo-content-bucket — every skill that writes a NEO artifact. Elevate to CLAUDE.md if it ever happens again — this should be a hard rule, not a lesson. Date: 2026-05-05