@skill-graph/cli 0.5.6

package/marketplace/skills/intent-recognition/SKILL.md

@@ -0,0 +1,136 @@
+---
+name: intent-recognition
+description: "Use BEFORE any tool call that could modify state, touch sensitive targets, rewrite history, install dependencies, publish packages, or expose credentials/environment data. Classifies intent into Passive/Read, Reconnaissance, Modification, or Destructive/Irreversible using operation type plus target sensitivity, then runs Identify / Confirm / Verify before action. Do NOT use for deciding what code to write, executing already-classified work, reactive post-execution guardrails, or defining upstream governance policy."
+license: MIT
+compatibility: "Runtime-agnostic. The four-tier classification, target-content rule, and Identify/Confirm/Verify sequence apply to any agent harness with tool execution — Claude Code, OpenCode, Cursor, Aider, Copilot Workspace, custom MCP-based agents, or any LLM with shell access."
+allowed-tools: Read Grep
+metadata:
+  metadata: "{\"schema_version\":6,\"version\":\"1.0.0\",\"type\":\"capability\",\"category\":\"engineering\",\"domain\":\"ai-engineering/safety\",\"scope\":\"portable\",\"owner\":\"skill-graph-maintainer\",\"freshness\":\"2026-05-06\",\"drift_check\":\"{\\\\\\\"last_verified\\\\\\\":\\\\\\\"2026-05-06\\\\\\\"}\",\"eval_artifacts\":\"planned\",\"eval_state\":\"unverified\",\"routing_eval\":\"absent\",\"stability\":\"experimental\",\"keywords\":\"[\\\\\\\"intent recognition\\\\\\\",\\\\\\\"pre-execution risk classification\\\\\\\",\\\\\\\"four tier action taxonomy\\\\\\\",\\\\\\\"passive read reconnaissance modification destructive\\\\\\\",\\\\\\\"identify confirm verify sequence\\\\\\\",\\\\\\\"destructive operation classification\\\\\\\",\\\\\\\"credential read is reconnaissance\\\\\\\",\\\\\\\"git reset hard is destructive\\\\\\\",\\\\\\\"force push is destructive\\\\\\\",\\\\\\\"lockfile install is high impact\\\\\\\",\\\\\\\"non-destructive alternative\\\\\\\",\\\\\\\"agent action risk assessment\\\\\\\",\\\\\\\"tool call pre-execution gate\\\\\\\",\\\\\\\"reading dotenv is not passive\\\\\\\",\\\\\\\"history rewriting is irreversible\\\\\\\",\\\\\\\"state-changing tool call\\\\\\\",\\\\\\\"agent safety pre-execution\\\\\\\",\\\\\\\"target content elevates tier\\\\\\\"]\",\"examples\":\"[\\\\\\\"the agent is about to run `git reset --hard` — what tier is this and what's the safer alternative?\\\\\\\",\\\\\\\"is reading the `.env` file a Passive operation since nothing mutates?\\\\\\\",\\\\\\\"I'm about to install a new package — what tier does that fit and why?\\\\\\\",\\\\\\\"force-push to main looks like 'just a push' — should I classify it as Modification?\\\\\\\",\\\\\\\"before running `DELETE FROM orders WHERE …`, what's the verification sequence?\\\\\\\",\\\\\\\"the agent classified everything as Modification because there's no exception for credentials\\\\\\\",\\\\\\\"what trigger phrases should activate this skill in our harness?\\\\\\\"]\",\"anti_examples\":\"[\\\\\\\"design the deterministic safety hook that blocks destructive commands\\\\\\\",\\\\\\\"decide whether to use a switch or a chain of ifs\\\\\\\",\\\\\\\"actually execute the migration after we've classified the risk\\\\\\\",\\\\\\\"scan this repo for OWASP top 10 vulnerabilities\\\\\\\",\\\\\\\"review this AI-generated PR for correctness\\\\\\\",\\\\\\\"the loop is stalling — what's the steering signal\\\\\\\"]\",\"relations\":\"{\\\\\\\"boundary\\\\\\\":[{\\\\\\\"skill\\\\\\\":\\\\\\\"owasp-security\\\\\\\",\\\\\\\"reason\\\\\\\":\\\\\\\"owasp-security is a domain audit against a known threat list; intent-recognition is the per-action risk classification that runs immediately before a tool call regardless of domain\\\\\\\"},{\\\\\\\"skill\\\\\\\":\\\\\\\"debugging\\\\\\\",\\\\\\\"reason\\\\\\\":\\\\\\\"debugging investigates a failure that has already happened; intent-recognition prevents one class of failure (destructive action mis-classification) from happening at all\\\\\\\"},{\\\\\\\"skill\\\\\\\":\\\\\\\"code-review\\\\\\\",\\\\\\\"reason\\\\\\\":\\\\\\\"code-review evaluates code-quality of an artefact; intent-recognition evaluates risk of an action about to be performed by a tool\\\\\\\"},{\\\\\\\"skill\\\\\\\":\\\\\\\"version-control\\\\\\\",\\\\\\\"reason\\\\\\\":\\\\\\\"version-control owns the discipline of using git well; intent-recognition specifically classifies which git commands are safe vs destructive at the moment of execution\\\\\\\"},{\\\\\\\"skill\\\\\\\":\\\\\\\"testing-strategy\\\\\\\",\\\\\\\"reason\\\\\\\":\\\\\\\"testing-strategy decides what to test proactively; intent-recognition gates one specific tool call from firing without classification\\\\\\\"}],\\\\\\\"related\\\\\\\":[\\\\\\\"owasp-security\\\\\\\",\\\\\\\"version-control\\\\\\\",\\\\\\\"debugging\\\\\\\"],\\\\\\\"verify_with\\\\\\\":[\\\\\\\"owasp-security\\\\\\\"]}\",\"portability\":\"{\\\\\\\"readiness\\\\\\\":\\\\\\\"scripted\\\\\\\",\\\\\\\"targets\\\\\\\":[\\\\\\\"skill-md\\\\\\\"]}\",\"lifecycle\":\"{\\\\\\\"stale_after_days\\\\\\\":365,\\\\\\\"review_cadence\\\\\\\":\\\\\\\"quarterly\\\\\\\"}\",\"skill_graph_source_repo\":\"https://github.com/jacob-balslev/skill-graph\",\"skill_graph_protocol\":\"Skill Metadata Protocol v5\",\"skill_graph_project\":\"Skill Graph\",\"skill_graph_canonical_skill\":\"skills/intent-recognition/SKILL.md\"}"
+  skill_graph_source_repo: "https://github.com/jacob-balslev/skill-graph"
+  skill_graph_protocol: Skill Metadata Protocol v4
+  skill_graph_project: Skill Graph
+  skill_graph_canonical_skill: skills/intent-recognition/SKILL.md
+---
+
+# Intent Recognition
+
+## Coverage
+
+Pre-execution action classification for any agent that can call tools with side effects. Defines four tiers — Passive/Read, Reconnaissance, Modification, Destructive/Irreversible — with the operation-and-target rule that determines tier (the target's sensitivity can elevate the tier above what the operation alone implies; reading a `.env` file is Reconnaissance even though no state changes). Specifies the three-step verification sequence (Identify the action and its tier, Confirm the rationale against the active plan, Verify whether a non-destructive alternative exists) that runs before any tier-3 or tier-4 action fires. Names the trigger phrases that should activate the skill. Catalogs the anti-patterns: classifying credential reads as Passive, treating package installs as Passive, skipping classification for familiar commands, classifying force-push as Modification, proceeding with Destructive actions without checking alternatives.
+
+## Philosophy
+
+Agents execute tool calls at machine speed with no undo. Without an explicit pre-execution classification step, `git reset --hard` runs with the same ease as `cat README.md`. The cost of a single misclassified destructive action — wiped uncommitted work, dropped database, force-pushed branch — exceeds the cost of _every_ classification step the agent will ever run. The math is simple: classification is cheap, regret is expensive.
+
+The most subtle failure mode is _target-content elevation_. Reading a file is a Passive operation in the abstract. Reading a `.env` file is Reconnaissance because the _target_ is sensitive — credentials, connection strings, API keys. The tier comes from the combination of operation _and_ target, not the operation alone. A classifier that looks only at the verb misses half the risk surface.
+
+The Identify / Confirm / Verify sequence is the second non-negotiable. _Identify_ surfaces the agent's own reasoning about the action; if the agent can't state the tier and the rationale, it shouldn't fire the tool. _Confirm_ tests the action against the agreed plan — drift between "what we agreed to do" and "what the next tool call will do" is itself a signal. _Verify_ asks whether a safer alternative exists and is the step where most preventable destructive actions get caught.
+
+## 1. The Four-Tier Taxonomy
+
+| Tier | Name                           | Examples                                                                                                                                                                       | Risk                                                      |
+| ---- | ------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------- |
+| 1    | **Passive / Read**             | View a non-sensitive file, list a directory, grep for a string                                                                                                                 | Low                                                       |
+| 2    | **Reconnaissance**             | Read `.env`, view a `credentials.*` file, run a SQL `SELECT` against a sensitive table, list installed packages and versions                                                   | Moderate (information exposure even without state change) |
+| 3    | **Modification**               | Write or edit a source file, run a routine `git commit`, run a non-destructive `INSERT` or `UPDATE` with a `WHERE` clause                                                      | Standard                                                  |
+| 4    | **Destructive / Irreversible** | `git reset --hard`, `git push --force`, `DROP TABLE`, `TRUNCATE`, `DELETE FROM ...` without `WHERE`, `rm -rf`, `npm publish`, credential rotation, dependency lockfile rewrite | Critical — requires explicit justification                |
+
+Every tool call gets a tier before it fires. No exceptions, including for "familiar" commands.
+
+## 2. Operation-vs-Target Rule
+
+The tier comes from the combination of _operation_ and _target_. The same operation has a different tier depending on what it touches.
+
+| Operation | Generic target              | Sensitive target                                        | Tier shift                                   |
+| --------- | --------------------------- | ------------------------------------------------------- | -------------------------------------------- |
+| Read      | Source file                 | `.env`, `credentials.*`, private key                    | Passive → Reconnaissance                     |
+| Read      | Local DB                    | Production DB or secrets table                          | Passive → Reconnaissance                     |
+| Write     | Source file                 | Lockfile, environment config, public-key registry       | Modification → Modification (still standard) |
+| Run       | Script with no side effects | Script with side effects (install, deploy, mutate prod) | Passive → Modification or Destructive        |
+| Git push  | Topic branch                | Main / master, force-push                               | Modification → Destructive (force-push)      |
+
+When in doubt about the target, classify _up_, not down.
+
+## 3. The Identify / Confirm / Verify Sequence
+
+Before executing any tier-3 or tier-4 tool call:
+
+### Identify
+
+State explicitly:
+
+- The exact action (full command, full target path)
+- The classified tier
+- The reason this action is needed
+
+If the agent cannot complete this sentence — "I'm about to run X (tier Y) because Z" — it shouldn't fire the tool. Inability to articulate is itself a stop signal.
+
+### Confirm
+
+Check the action against the active plan or task spec:
+
+- Was this action agreed to?
+- Does the spec name the same target?
+- If the action escalates a previously-agreed tier (e.g., the spec said "modify"; the proposed action is "destroy"), is the escalation explicitly authorized?
+
+Drift between agreed action and proposed action is the signal. The right response to drift is to _re-confirm with the human_, not to proceed.
+
+### Verify
+
+Ask: is there a non-destructive alternative that achieves the same goal?
+
+| Destructive                     | Non-destructive alternative                                        |
+| ------------------------------- | ------------------------------------------------------------------ |
+| `git reset --hard`              | `git revert` (preserves history) or `git stash` (preserves work)   |
+| `git push --force`              | `git push --force-with-lease` (fails if remote moved unexpectedly) |
+| `DROP TABLE x`                  | `ALTER TABLE x RENAME TO x_archived_<date>` (reversible)           |
+| `DELETE FROM x WHERE condition` | `UPDATE x SET deleted_at = now() WHERE condition` (soft delete)    |
+| `rm -rf <dir>`                  | `mv <dir> <dir>.archived.<date>` (still on disk; recoverable)      |
+| `npm publish`                   | `npm publish --dry-run` first (sees the package; doesn't push)     |
+| Lockfile rewrite                | Smaller dependency change scoped to one package                    |
+
+If a non-destructive alternative exists and the destructive form was not specifically requested, prefer the non-destructive form.
+
+## 4. Trigger Phrases
+
+The skill should activate before any tool call where the agent is about to:
+
+- Modify or write a file (`Write`, `Edit`, `MultiEdit`, `replace_file_content`, …)
+- Run a git command that mutates state (`commit`, `push`, `reset`, `rebase`, `merge`, `cherry-pick`, `branch -D`, `tag`, `stash drop`)
+- Run a database query that mutates state (`INSERT`, `UPDATE`, `DELETE`, `DROP`, `TRUNCATE`, `ALTER`, `CREATE`)
+- Run an install / publish / deploy command (`npm/pnpm/yarn install`, `npm publish`, `vercel deploy`, `cargo publish`, `pip install`, `apt install`, `gh repo edit`)
+- Run a shell command with `&&`, `||`, `;`, `|` chains that include any of the above
+- Read any file matching `.env*`, `credentials*`, `id_rsa*`, `*.pem`, `*.key`, `secrets.*`, `keystore*`
+
+These triggers are deliberately broad. False positives (classifying a Passive action as needing a tier check) are cheap; false negatives (firing a Destructive command without classification) are the failure mode this skill exists to prevent.
+
+## 5. Anti-Patterns
+
+| Anti-pattern                                                      | Why it fails                                                                                                                          | Correct approach                                                    |
+| ----------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------- |
+| Classifying _all_ reads as Passive                                | A read of `.env` is Reconnaissance — credential exposure is the risk even with no state change                                        | Check operation _and_ target type                                   |
+| Treating `npm install` / `pnpm install` as Passive                | Lockfile rewrites and node_modules churn affect reproducibility and can pull in compromised packages                                  | Classify any environment-affecting command as at least Modification |
+| Skipping classification for "familiar" commands                   | `git push` is routine; `git push --force origin main` is Destructive — flags change tier                                              | Classify every tool call regardless of familiarity                  |
+| Classifying force-push as Modification                            | Force-push rewrites remote history and cannot be `git checkout`-ed back                                                               | Any history-rewriting or unrecoverable action is Destructive        |
+| Proceeding with Destructive without checking alternatives         | `git reset --hard` instead of `git revert` is the single most common preventable loss                                                 | Run the Verify step every time                                      |
+| Conflating Reconnaissance with Passive because "no state changes" | Information exposure (logging credentials, leaking connection strings into chat history) is itself a state change at the system level | Reconnaissance is its own tier for a reason                         |
+
+## Verification
+
+- [ ] Before any tier-3 or tier-4 tool call, the agent has stated the action, the tier, and the reason in plain text
+- [ ] Operation-and-target rule was applied — sensitive targets elevated the tier above what the operation alone would suggest
+- [ ] The Confirm step checked the action against the agreed plan; any drift was re-confirmed with the human, not proceeded past
+- [ ] The Verify step considered at least one non-destructive alternative and either chose it or named why the destructive form is required
+- [ ] No tool call fired without an explicit tier classification — no exceptions for "familiar" commands
+- [ ] The trigger-phrase list is the activation contract, not a suggestion: any matching command runs through the sequence
+
+## Do NOT Use When
+
+| Use instead                                                                         | When                                                                                                                                                                              |
+| ----------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| A hook-based guardrail (deterministic blocker, e.g. PreToolUse hook in Claude Code) | Setting up _reactive_ / _structural_ enforcement that fires on a pattern match in the harness — that is hook-pattern territory; this skill is the agent-side cognitive classifier |
+| A code-quality / code-logic skill                                                   | Deciding _what_ the code should do — implementation correctness rather than action risk                                                                                           |
+| Task execution                                                                      | Actually doing the work after classification has cleared the action                                                                                                               |
+| `owasp-security`                                                                    | A domain audit against a known threat catalog (Top 10) — that is a class of investigation, not per-action classification                                                          |
+| `code-review`                                                                       | Reviewing an artefact for quality — orthogonal to action-risk classification                                                                                                      |
+| `version-control`                                                                   | The general discipline of using git well — this skill is the moment-of-execution gate on specific git commands                                                                    |

package/marketplace/skills/interaction-feedback/SKILL.md

@@ -0,0 +1,59 @@
+---
+name: interaction-feedback
+description: "Use when designing UI feedback around user actions and system state: loading, skeletons, optimistic updates, progress, success, errors, empty states, retries, disabled/pending states, autosave, undo, and perceived latency. Do NOT use for the words inside feedback (use `microcopy`), accessibility announcement mechanics (use `a11y`), business lifecycle modeling (use `state-machine-modeling`), or performance optimization (use `performance-engineering`)."
+license: MIT
+compatibility: Portable feedback-state design for web and app UI. Applies before framework-specific implementation and after task or interaction pattern selection.
+allowed-tools: Read Grep
+metadata:
+  metadata: "{\"schema_version\":6,\"version\":\"1.0.0\",\"type\":\"capability\",\"category\":\"design\",\"domain\":\"design/interaction\",\"scope\":\"portable\",\"owner\":\"skill-graph-maintainer\",\"freshness\":\"2026-05-11\",\"drift_check\":\"{\\\\\\\"last_verified\\\\\\\":\\\\\\\"2026-05-11\\\\\\\"}\",\"eval_artifacts\":\"present\",\"eval_state\":\"unverified\",\"routing_eval\":\"absent\",\"stability\":\"experimental\",\"keywords\":\"[\\\\\\\"interaction-feedback\\\\\\\",\\\\\\\"feedback-state staging\\\\\\\",\\\\\\\"optimistic ui\\\\\\\",\\\\\\\"pending state\\\\\\\",\\\\\\\"retry feedback\\\\\\\",\\\\\\\"undo feedback\\\\\\\",\\\\\\\"perceived latency\\\\\\\",\\\\\\\"long-running action feedback\\\\\\\",\\\\\\\"skeleton loading\\\\\\\"]\",\"examples\":\"[\\\\\\\"design loading, success, error, and retry feedback for this async action\\\\\\\",\\\\\\\"should this save be optimistic, pending, blocked, or undoable?\\\\\\\",\\\\\\\"the sync takes 30 seconds - what should users see at each stage?\\\\\\\",\\\\\\\"add feedback states so the UI does not feel frozen after clicking Export\\\\\\\"]\",\"anti_examples\":\"[\\\\\\\"rewrite the toast and validation text\\\\\\\",\\\\\\\"make sure the status update is announced to screen readers\\\\\\\",\\\\\\\"model the order lifecycle and legal transitions\\\\\\\",\\\\\\\"profile the endpoint that makes this action slow\\\\\\\"]\",\"relations\":\"{\\\\\\\"boundary\\\\\\\":[{\\\\\\\"skill\\\\\\\":\\\\\\\"microcopy\\\\\\\",\\\\\\\"reason\\\\\\\":\\\\\\\"microcopy owns the words inside feedback states; interaction-feedback owns timing, placement, persistence, and recovery behavior\\\\\\\"},{\\\\\\\"skill\\\\\\\":\\\\\\\"a11y\\\\\\\",\\\\\\\"reason\\\\\\\":\\\\\\\"a11y owns assistive-technology announcement mechanics; interaction-feedback owns the visible and behavioral feedback model\\\\\\\"},{\\\\\\\"skill\\\\\\\":\\\\\\\"state-machine-modeling\\\\\\\",\\\\\\\"reason\\\\\\\":\\\\\\\"state-machine-modeling owns business lifecycle legality; interaction-feedback owns the UI representation of pending, success, failure, and recovery\\\\\\\"},{\\\\\\\"skill\\\\\\\":\\\\\\\"performance-engineering\\\\\\\",\\\\\\\"reason\\\\\\\":\\\\\\\"performance-engineering reduces measured latency; interaction-feedback communicates latency and state honestly\\\\\\\"}],\\\\\\\"related\\\\\\\":[\\\\\\\"interaction-patterns\\\\\\\",\\\\\\\"microcopy\\\\\\\",\\\\\\\"task-analysis\\\\\\\",\\\\\\\"a11y\\\\\\\",\\\\\\\"performance-engineering\\\\\\\"],\\\\\\\"verify_with\\\\\\\":[\\\\\\\"a11y\\\\\\\",\\\\\\\"microcopy\\\\\\\"]}\",\"portability\":\"{\\\\\\\"readiness\\\\\\\":\\\\\\\"scripted\\\\\\\",\\\\\\\"targets\\\\\\\":[\\\\\\\"skill-md\\\\\\\"]}\",\"lifecycle\":\"{\\\\\\\"stale_after_days\\\\\\\":365,\\\\\\\"review_cadence\\\\\\\":\\\\\\\"quarterly\\\\\\\"}\",\"skill_graph_source_repo\":\"https://github.com/jacob-balslev/skill-graph\",\"skill_graph_protocol\":\"Skill Metadata Protocol v5\",\"skill_graph_project\":\"Skill Graph\",\"skill_graph_canonical_skill\":\"skills/interaction-feedback/SKILL.md\"}"
+  skill_graph_source_repo: "https://github.com/jacob-balslev/skill-graph"
+  skill_graph_protocol: Skill Metadata Protocol v4
+  skill_graph_project: Skill Graph
+  skill_graph_canonical_skill: skills/interaction-feedback/SKILL.md
+---
+
+# Interaction Feedback
+
+## Coverage
+
+Design feedback states for user actions and system changes. Covers immediate click feedback, loading indicators, skeletons, optimistic UI, pending and disabled states, progress, success confirmation, persistent errors, retry, undo, autosave, long-running jobs, empty and low-data states, and perceived-latency staging.
+
+## Philosophy
+
+Feedback is the user's proof that the system heard them. Without it, users repeat actions, abandon flows, or assume data was lost. Good feedback is honest about uncertainty and gives recovery paths when the system cannot complete the action.
+
+Feedback is not the same as performance. A fast system still needs confirmation, and a slow system still needs staged truth.
+
+## Method
+
+1. Name the action or state change that needs feedback.
+2. Classify expected duration: instant, short, medium, long, background, or unknown.
+3. Decide the feedback surface: inline state, button state, skeleton, banner, toast, progress row, modal, or job history.
+4. Define transitions: idle, pending, partial, success, failure, retrying, cancelled, and undoable.
+5. Preserve user control for long or destructive actions: cancel, retry, undo, leave-and-return.
+6. Hand off wording to `microcopy` and announcement mechanics to `a11y`.
+7. Verify the user can tell whether work is still happening, done, failed, or recoverable.
+
+## Evals
+
+This skill ships a comprehension-eval artifact at [`examples/evals/interaction-feedback.json`](https://github.com/jacob-balslev/skill-graph/blob/main/examples/evals/interaction-feedback.json). The checklist below is the authoring gate for feedback-state design; the eval file is the grader surface.
+
+## Verification
+
+- [ ] Every async action has an immediate observable response
+- [ ] Long-running work has progress, backgrounding, or return-later behavior
+- [ ] Optimistic updates define rollback and conflict behavior
+- [ ] Success states are visible without being noisy
+- [ ] Errors are persistent enough to recover from
+- [ ] Retry, cancel, undo, or support paths exist when relevant
+- [ ] Screen-reader announcement and wording are verified by `a11y` and `microcopy`
+
+## Do NOT Use When
+
+| Use instead | When |
+|---|---|
+| `microcopy` | The task is writing button labels, toast text, empty-state text, or validation copy. |
+| `a11y` | The task is live regions, screen-reader announcements, focus management, or WCAG compliance. |
+| `state-machine-modeling` | The task is defining legal lifecycle states, guards, and transitions. |
+| `performance-engineering` | The task is measuring and reducing latency, bundle size, query cost, or throughput. |
+| `interaction-patterns` | The task is selecting the primary control or interaction pattern. |

package/marketplace/skills/interaction-patterns/SKILL.md

@@ -0,0 +1,59 @@
+---
+name: interaction-patterns
+description: "Use when choosing or auditing UI interaction patterns and controls: tabs vs pages, dropdown vs combobox, stepper vs wizard, modal vs inline edit, disclosure, command menus, selection, filtering, and gesture alternatives. Do NOT use for accessibility compliance (use `a11y`), task decomposition (use `task-analysis`), feedback-state staging (use `interaction-feedback`), or reusable component API design (use `design-system-architecture`)."
+license: MIT
+compatibility: Portable interaction-pattern guidance for web and app UI. Pattern choices should be checked against platform conventions and accessible-widget guidance before implementation.
+allowed-tools: Read Grep
+metadata:
+  metadata: "{\"schema_version\":6,\"version\":\"1.0.0\",\"type\":\"capability\",\"category\":\"design\",\"domain\":\"design/interaction\",\"scope\":\"portable\",\"owner\":\"skill-graph-maintainer\",\"freshness\":\"2026-05-11\",\"drift_check\":\"{\\\\\\\"last_verified\\\\\\\":\\\\\\\"2026-05-11\\\\\\\"}\",\"eval_artifacts\":\"present\",\"eval_state\":\"unverified\",\"routing_eval\":\"present\",\"stability\":\"experimental\",\"keywords\":\"[\\\\\\\"interaction-patterns\\\\\\\",\\\\\\\"control pattern selection\\\\\\\",\\\\\\\"dropdown combobox choice\\\\\\\",\\\\\\\"modal inline edit choice\\\\\\\",\\\\\\\"tabs accordion choice\\\\\\\",\\\\\\\"bulk selection pattern\\\\\\\",\\\\\\\"command menu pattern\\\\\\\",\\\\\\\"disclosure pattern\\\\\\\",\\\\\\\"gesture alternative\\\\\\\",\\\\\\\"modal vs panel choice\\\\\\\",\\\\\\\"pagination vs infinite scroll\\\\\\\",\\\\\\\"tooltip vs popover\\\\\\\"]\",\"examples\":\"[\\\\\\\"should this control be a dropdown, combobox, radio group, or stepper?\\\\\\\",\\\\\\\"choose the interaction pattern for bulk editing rows in this table\\\\\\\",\\\\\\\"this modal interrupts the flow - should the edit be inline instead?\\\\\\\",\\\\\\\"decide whether these settings belong in tabs, accordion sections, or separate pages\\\\\\\"]\",\"anti_examples\":\"[\\\\\\\"audit this combobox for ARIA roles and keyboard support\\\\\\\",\\\\\\\"define the user's top task before choosing controls\\\\\\\",\\\\\\\"add skeleton loading and optimistic feedback to this action\\\\\\\",\\\\\\\"define the component props, variants, slots, and token contract\\\\\\\"]\",\"relations\":\"{\\\\\\\"boundary\\\\\\\":[{\\\\\\\"skill\\\\\\\":\\\\\\\"a11y\\\\\\\",\\\\\\\"reason\\\\\\\":\\\\\\\"a11y verifies accessibility semantics and keyboard behavior; interaction-patterns chooses the user-facing pattern before implementation\\\\\\\"},{\\\\\\\"skill\\\\\\\":\\\\\\\"task-analysis\\\\\\\",\\\\\\\"reason\\\\\\\":\\\\\\\"task-analysis identifies what the user is trying to accomplish; interaction-patterns chooses the control pattern that supports it\\\\\\\"},{\\\\\\\"skill\\\\\\\":\\\\\\\"interaction-feedback\\\\\\\",\\\\\\\"reason\\\\\\\":\\\\\\\"interaction-feedback owns feedback states after an action; interaction-patterns owns the primary control and flow shape\\\\\\\"},{\\\\\\\"skill\\\\\\\":\\\\\\\"design-system-architecture\\\\\\\",\\\\\\\"reason\\\\\\\":\\\\\\\"design-system-architecture owns reusable component APIs; interaction-patterns decides which pattern is appropriate for a surface\\\\\\\"},{\\\\\\\"skill\\\\\\\":\\\\\\\"design-module-composition\\\\\\\",\\\\\\\"reason\\\\\\\":\\\\\\\"design-module-composition owns component props, variants, slots, and token contracts; interaction-patterns owns choosing the user-facing control pattern\\\\\\\"},{\\\\\\\"skill\\\\\\\":\\\\\\\"component-architecture\\\\\\\",\\\\\\\"reason\\\\\\\":\\\\\\\"component-architecture owns the component-library layering question (primitives, composites, product-specific) and headless/styled, controlled/uncontrolled splits; interaction-patterns owns choosing the user-facing control pattern before any component is designed\\\\\\\"}],\\\\\\\"related\\\\\\\":[\\\\\\\"layout-composition\\\\\\\",\\\\\\\"form-ux-architecture\\\\\\\",\\\\\\\"microcopy\\\\\\\",\\\\\\\"semiotics\\\\\\\",\\\\\\\"a11y\\\\\\\"],\\\\\\\"verify_with\\\\\\\":[\\\\\\\"a11y\\\\\\\",\\\\\\\"task-analysis\\\\\\\"]}\",\"portability\":\"{\\\\\\\"readiness\\\\\\\":\\\\\\\"scripted\\\\\\\",\\\\\\\"targets\\\\\\\":[\\\\\\\"skill-md\\\\\\\"]}\",\"lifecycle\":\"{\\\\\\\"stale_after_days\\\\\\\":365,\\\\\\\"review_cadence\\\\\\\":\\\\\\\"quarterly\\\\\\\"}\",\"skill_graph_source_repo\":\"https://github.com/jacob-balslev/skill-graph\",\"skill_graph_protocol\":\"Skill Metadata Protocol v5\",\"skill_graph_project\":\"Skill Graph\",\"skill_graph_canonical_skill\":\"skills/interaction-patterns/SKILL.md\"}"
+  skill_graph_source_repo: "https://github.com/jacob-balslev/skill-graph"
+  skill_graph_protocol: Skill Metadata Protocol v4
+  skill_graph_project: Skill Graph
+  skill_graph_canonical_skill: skills/interaction-patterns/SKILL.md
+---
+
+# Interaction Patterns
+
+## Coverage
+
+Choose and audit interaction patterns before implementation. Covers control selection, mode switching, progressive disclosure, modals, drawers, tabs, accordions, command menus, comboboxes, steppers, wizards, inline edit, bulk selection, filters, sorting, gestures, keyboard alternatives, and pattern fit under task pressure.
+
+## Philosophy
+
+Most confusing interfaces are not missing components; they chose the wrong pattern for the decision the user has to make. A dropdown hides options that need comparison. A modal blocks context the user needs. A wizard adds ceremony to a task that only needed one form.
+
+Choose the pattern from the user's decision shape: compare, choose one, choose many, sequence, search, edit, confirm, or recover.
+
+## Method
+
+1. Name the user decision or action the control must support.
+2. Classify the choice set: small, large, searchable, hierarchical, ordered, destructive, reversible, or repeated.
+3. Choose the simplest known pattern that keeps needed context visible.
+4. Preserve alternatives for keyboard and non-pointer users before handoff to `a11y`.
+5. Define what happens on selection, cancel, escape, undo, and invalid action.
+6. Check whether the pattern works with loading, empty, error, and permission-limited states.
+7. Hand off component API concerns to `design-system-architecture`.
+
+## Evals
+
+This skill ships a comprehension-eval artifact at [`examples/evals/interaction-patterns.json`](https://github.com/jacob-balslev/skill-graph/blob/main/examples/evals/interaction-patterns.json). The checklist below is the authoring gate for pattern choice; the eval file is the grader surface.
+
+## Verification
+
+- [ ] The pattern matches the user's decision type
+- [ ] Hidden options are acceptable only when comparison is not required
+- [ ] Context needed to decide is visible or intentionally preserved
+- [ ] Cancel, escape, undo, and invalid-action behavior are defined
+- [ ] Pointer-only gestures have a keyboard or explicit control alternative
+- [ ] Loading, empty, error, and disabled states fit the pattern
+- [ ] Accessibility implementation is handed off to `a11y`
+
+## Do NOT Use When
+
+| Use instead | When |
+|---|---|
+| `a11y` | The task is ARIA roles, keyboard behavior, focus management, labels, or WCAG compliance. |
+| `task-analysis` | The user goal, top task, or flow breakpoint is still unknown. |
+| `interaction-feedback` | The pattern is chosen and the task is feedback timing, progress, optimistic UI, or state visibility. |
+| `design-system-architecture` | The task is reusable component APIs, variants, slots, tokens, or governance. |
+| `form-ux-architecture` | The surface is primarily a form with validation, field grouping, and submission lifecycle concerns. |

package/marketplace/skills/journey-mapping/SKILL.md

@@ -0,0 +1,41 @@
+---
+name: journey-mapping
+description: "Use when mapping a user's experience across multiple touchpoints and time, surfacing emotional peaks and troughs, identifying opportunity moments in a cross-channel flow, or aligning a team on the end-to-end experience including back-stage support processes. Do NOT use for decomposing a single screen into UI steps (use task-analysis) or for drawing back-end service architecture diagrams — journey maps describe human experience, not system topology."
+license: CC-BY-4.0
+metadata:
+  metadata: "{\"schema_version\":6,\"version\":\"1.0.0\",\"type\":\"capability\",\"category\":\"design\",\"scope\":\"portable\",\"owner\":\"skill-graph-maintainer\",\"freshness\":\"2026-05-12\",\"drift_check\":\"{\\\\\\\"last_verified\\\\\\\":\\\\\\\"2026-05-12\\\\\\\"}\",\"eval_artifacts\":\"planned\",\"eval_state\":\"unverified\",\"routing_eval\":\"absent\",\"stability\":\"experimental\",\"keywords\":\"[\\\\\\\"customer journey map\\\\\\\",\\\\\\\"user journey\\\\\\\",\\\\\\\"service blueprint\\\\\\\",\\\\\\\"touchpoint\\\\\\\",\\\\\\\"moments of truth\\\\\\\",\\\\\\\"experience map\\\\\\\",\\\\\\\"front-stage back-stage\\\\\\\",\\\\\\\"emotional curve\\\\\\\",\\\\\\\"opportunity areas\\\\\\\",\\\\\\\"pain points\\\\\\\",\\\\\\\"cross-channel experience\\\\\\\",\\\\\\\"end-to-end journey\\\\\\\",\\\\\\\"onboarding journey\\\\\\\"]\",\"triggers\":\"[\\\\\\\"journey map\\\\\\\",\\\\\\\"service blueprint\\\\\\\",\\\\\\\"map the user experience\\\\\\\",\\\\\\\"customer journey\\\\\\\",\\\\\\\"touchpoints\\\\\\\"]\",\"examples\":\"[\\\\\\\"Build a journey map for first-time tax filers from awareness through filing to refund.\\\\\\\",\\\\\\\"Add a service-blueprint layer below this journey map showing the back-stage support steps.\\\\\\\",\\\\\\\"Identify the emotional low points in this onboarding journey and the opportunities at each.\\\\\\\",\\\\\\\"Map the cross-channel experience of returning an online order to a physical store.\\\\\\\"]\",\"anti_examples\":\"[\\\\\\\"Break down the steps a user takes inside the upload modal.\\\\\\\",\\\\\\\"Draw the microservice call graph for the checkout API.\\\\\\\",\\\\\\\"Diagram the database schema for the order entity.\\\\\\\"]\",\"relations\":\"{\\\\\\\"related\\\\\\\":[\\\\\\\"research-synthesis\\\\\\\",\\\\\\\"information-architecture\\\\\\\",\\\\\\\"design-thinking\\\\\\\",\\\\\\\"problem-framing\\\\\\\"],\\\\\\\"boundary\\\\\\\":[{\\\\\\\"skill\\\\\\\":\\\\\\\"task-analysis\\\\\\\",\\\\\\\"reason\\\\\\\":\\\\\\\"task-analysis decomposes a single goal-directed task into ordered steps within one interface or session. journey-mapping spans many sessions, channels, and days, and includes emotional and contextual layers task-analysis does not.\\\\\\\"},{\\\\\\\"skill\\\\\\\":\\\\\\\"bounded-context-mapping\\\\\\\",\\\\\\\"reason\\\\\\\":\\\\\\\"bounded-context-mapping is an engineering practice for modeling DDD context boundaries. journey-mapping describes human experience across touchpoints — a similar diagrammatic instinct but unrelated output.\\\\\\\"}]}\",\"skill_graph_source_repo\":\"https://github.com/jacob-balslev/skill-graph\",\"skill_graph_protocol\":\"Skill Metadata Protocol v5\",\"skill_graph_project\":\"Skill Graph\",\"skill_graph_canonical_skill\":\"skills/journey-mapping/SKILL.md\"}"
+  skill_graph_source_repo: "https://github.com/jacob-balslev/skill-graph"
+  skill_graph_protocol: Skill Metadata Protocol v4
+  skill_graph_project: Skill Graph
+  skill_graph_canonical_skill: skills/journey-mapping/SKILL.md
+---
+
+# Journey Mapping
+
+## Coverage
+Journey mapping covers the family of visualizations that lay out a user's experience as a timeline across stages, actions, thoughts, feelings, and touchpoints. The classic **customer journey map** (Jeff Patton's writing on story mapping is an adjacent influence; NN/g has codified the canonical structure) typically has a horizontal axis of stages (e.g., Awareness → Consideration → Purchase → Onboarding → Use → Renew/Churn) and vertical lanes for what the user is doing, thinking, feeling, and which touchpoint they are interacting with. An **emotional curve** rendered along the timeline highlights peaks and troughs — the "moments of truth" that disproportionately shape the overall impression.
+
+A **service blueprint** (Lynn Shostack, 1984) extends the journey map downward with **front-stage** elements (what the user sees), the **line of visibility**, and **back-stage** elements (what employees, systems, and processes do that the user does not see). Below those, **support processes** show the infrastructure that enables back-stage work. Service blueprints are appropriate when the experience involves human or system handoffs that the user never sees but that determine whether the experience succeeds.
+
+The skill also covers **current-state vs future-state** maps (current documents reality and surfaces pain points; future proposes a redesigned experience and is used to align stakeholders), and the choice of **scope** — a single transaction, an entire lifecycle, or a specific moment-of-truth blown up in detail. Granularity matches the decision the map will inform; a board-level alignment map is coarser than a redesign brief.
+
+## Philosophy
+Journey maps exist because experience is temporal and cross-channel, and most artifacts a team produces are neither. A screen design captures one moment; an architecture diagram captures one cross-section; a backlog captures one project. The journey map is the only artifact that asks "what does the user actually live through, end to end, including the parts that happen on phone calls, in physical mail, in the gap between sessions, and in the moments when they think about us and then put it down?"
+
+The practice resists two failure modes. The first is the **anodyne happy-path map**, where every stage is labeled with a positive verb and the emotional curve is a gentle wave — these maps describe what the team hopes is true rather than what research showed. The second is the **everything-everywhere map**, where ambition outruns research and the map sprouts lanes for every possible channel without evidence. A journey map's credibility comes from being grounded in synthesis output; without that grounding it is decoration.
+
+## Verification
+- The map is grounded in specific research evidence — each pain point and emotional trough cites at least one source (interview quote, observation, support log) rather than being asserted.
+- Stages on the horizontal axis are named from the user's perspective ("trying to understand what I owe") rather than the business's ("acquisition funnel stage 2").
+- The emotional curve has actual lows, not only highs and neutrals — a curve with no dips usually means the map omits the hard parts.
+- For service blueprints, the line of visibility is drawn explicitly and the back-stage steps include both human and system actors.
+- The map identifies named **opportunity areas** at specific stages, not a generic "improve onboarding" annotation.
+- A stakeholder who did not attend the mapping session can read the map and explain back the journey's overall arc, including where it goes wrong.
+
+## Do NOT Use When
+- The scope is a single screen or single task within one session — use **task-analysis** for goal-directed step decomposition.
+- The team has not yet done qualitative research on the journey — run **user-research** and **research-synthesis** first; an unresearched journey map is fiction.
+- The diagram needed is a system architecture, microservice topology, or data flow — those are engineering artifacts, not journey maps.
+- The output should be a navigation structure or content taxonomy — use **information-architecture**.
+- The task is modeling engineering domain events across bounded contexts — use **event-storming** or **bounded-context-mapping**.
+- The team is in solutioning mode and needs to generate concept variants — use **ideation**; journey mapping clarifies experience, it does not invent new ones.

package/marketplace/skills/keywords/SKILL.md

@@ -0,0 +1,213 @@
+---
+name: keywords
+description: "Use when performing keyword research, building keyword strategy, optimizing product or marketplace listings, selecting terms for content, detecting cannibalization, or planning topical clusters. Covers seed expansion, intent mapping, topical clustering, marketplace keyword limits, long-tail POD/merch strategy, and tracking methodology. Do NOT use for full SEO implementation strategy (use `seo-strategy`), product copywriting (use `writing-humanizer`), or information architecture (use `information-architecture`)."
+license: MIT
+compatibility: "Markdown, Git, agent-skill runtimes"
+allowed-tools: Read Grep Bash
+metadata:
+  metadata: "{\"schema_version\":6,\"version\":\"1.0.0\",\"type\":\"capability\",\"category\":\"product\",\"domain\":\"product/overlay\",\"scope\":\"portable\",\"owner\":\"skill-graph-maintainer\",\"freshness\":\"2026-03-28\",\"drift_check\":\"{\\\\\\\"last_verified\\\\\\\":\\\\\\\"2026-03-28\\\\\\\"}\",\"eval_artifacts\":\"planned\",\"eval_state\":\"unverified\",\"routing_eval\":\"absent\",\"stability\":\"experimental\",\"keywords\":\"[\\\\\\\"keyword research\\\\\\\",\\\\\\\"keyword strategy\\\\\\\",\\\\\\\"keyword clustering\\\\\\\",\\\\\\\"long-tail keywords\\\\\\\",\\\\\\\"etsy tags\\\\\\\",\\\\\\\"amazon keywords\\\\\\\",\\\\\\\"keyword cannibalization\\\\\\\",\\\\\\\"search intent\\\\\\\",\\\\\\\"topical authority\\\\\\\",\\\\\\\"keyword tracking\\\\\\\",\\\\\\\"rank tracking\\\\\\\",\\\\\\\"SERP\\\\\\\",\\\\\\\"seed keywords\\\\\\\",\\\\\\\"keyword mapping\\\\\\\"]\",\"triggers\":\"[\\\\\\\"keyword-skill\\\\\\\",\\\\\\\"keyword-research-skill\\\\\\\"]\",\"relations\":\"{\\\\\\\"related\\\\\\\":[\\\\\\\"seo-strategy\\\\\\\"]}\",\"portability\":\"{\\\\\\\"readiness\\\\\\\":\\\\\\\"scripted\\\\\\\",\\\\\\\"targets\\\\\\\":[\\\\\\\"skill-md\\\\\\\"]}\",\"lifecycle\":\"{\\\\\\\"stale_after_days\\\\\\\":90,\\\\\\\"review_cadence\\\\\\\":\\\\\\\"quarterly\\\\\\\"}\",\"skill_graph_source_repo\":\"https://github.com/jacob-balslev/skill-graph\",\"skill_graph_protocol\":\"Skill Metadata Protocol v5\",\"skill_graph_project\":\"Skill Graph\",\"skill_graph_canonical_skill\":\"skills/keywords/SKILL.md\"}"
+  skill_graph_source_repo: "https://github.com/jacob-balslev/skill-graph"
+  skill_graph_protocol: Skill Metadata Protocol v4
+  skill_graph_project: Skill Graph
+  skill_graph_canonical_skill: skills/keywords/SKILL.md
+---
+# Keyword Research & Strategy Skill
+
+## Domain Context
+
+**What is this skill?** This skill provides keyword research, clustering, and platform-specific keyword optimization for e-commerce and SaaS. Covers seed keyword expansion, search intent mapping (informational/navigational/transactional/commercial), keyword clustering for topical authority, marketplace-specific keyword rules (Etsy 13-tag limit and 140-char title priority, Amazon backend keywords and 250-byte limit, Shopify product/collection meta fields), long-tail strategy for POD/merch businesses, cannibalization detection, and keyword tracking methodology. Use when performing keyword research, building a keyword strategy, optimizing product listings for marketplace search, choosing keywords for new content, detecting keyword cannibalization, or planning topical clusters. Do NOT use for diagnosing existing SEO problems (use seo-audit), building optimized pages at scale (use seo-strategy), content writing (use copywriting), or site page hierarchy (use site-architecture).
+## Key Files
+
+| File | Purpose |
+|---|---|
+| `skills/keywords/references/marketplace-keyword-rules.md` | See for detailed per-platform rules. |
+## Project-Specific Rules
+
+This skill captures project-local rules and constraints that narrow or refine a broader pattern. Treat the repo-specific guidance and key files below as authoritative for this project.
+
+## Coverage
+
+Seed keyword expansion, search intent mapping (informational/navigational/transactional/commercial investigation), keyword clustering for topical authority (pillar-cluster model), marketplace-specific keyword rules (Etsy 13-tag limit and 140-char title priority, Amazon backend keywords and 250-byte limit, Shopify collection-page SEO priority), long-tail strategy for POD/merch businesses, cannibalization detection and resolution, keyword tracking methodology and tool selection by platform, and tracking cadence for rank monitoring.
+
+## Philosophy
+
+Keywords are the bridge between what a seller creates and what a buyer searches for. Without systematic keyword research, product listings and content pages either target terms that are too competitive (impossible to rank) or too generic (no buyer intent). For POD sellers in particular, each design is a unique product that must match a specific long-tail query. This skill exists because agents repeatedly make three mistakes without it: (1) suggesting single-word Etsy tags instead of multi-word phrases, (2) repeating title words in Amazon backend keywords (wasting the 250-byte limit), and (3) targeting head terms on Shopify product pages instead of routing generic keywords to collection pages.
+
+> Research the right keywords before building pages or writing content.
+
+## When to Use This Skill
+
+Load this skill when:
+- Performing keyword research for new products, pages, or content
+- Building a keyword strategy for a Shopify store, Etsy shop, or Amazon listing
+- Optimizing product listing titles and tags for marketplace search
+- Planning topical clusters for a blog or content hub
+- Detecting and resolving keyword cannibalization
+- Setting up keyword rank tracking
+
+Do NOT use for:
+- Diagnosing why pages aren't ranking (use **seo-audit**)
+- Building or optimizing pages at scale (use **seo-strategy**)
+- Writing the actual content (use **copywriting**)
+- Planning site page hierarchy (use **site-architecture**)
+
+---
+
+## 1. Keyword Research Process
+
+### Seed -> Expansion -> Clustering -> Intent Mapping
+
+| Phase | Goal | Method |
+|-------|------|--------|
+| **Seed** | Identify 5-15 core terms | Product names, competitor analysis, niche vocabulary |
+| **Expansion** | Grow to 100-500 candidates | Tool-assisted: related terms, questions, long-tail variations |
+| **Clustering** | Group by topic/intent | Semantic similarity, shared SERP overlap, parent-child relationships |
+| **Intent Mapping** | Classify each cluster | Informational / Navigational / Transactional / Commercial Investigation |
+
+### Search Intent Types
+
+| Intent | Signal Words | Page Type | Example |
+|--------|-------------|-----------|---------|
+| **Informational** | how, what, why, guide, tutorial | Blog post, guide | "how to start a merch business" |
+| **Navigational** | brand name, login, app | Homepage, product page | "printify dashboard" |
+| **Transactional** | buy, order, price, discount, cheap | Product page, collection | "anti-trump t-shirt buy" |
+| **Commercial Investigation** | best, vs, review, comparison, alternative | Comparison page, listicle | "printify vs printful for t-shirts" |
+
+### Long-Tail Strategy for POD/Merch
+
+POD sellers benefit disproportionately from long-tail keywords because:
+1. Head terms ("t-shirt") are impossible to rank for
+2. Long-tail captures buyer intent ("funny anti-trump gift for dad")
+3. Each design is a unique product — match keyword to design theme
+4. Lower competition = faster ranking on marketplace search
+
+**Pattern:** `[adjective] + [topic/theme] + [product type] + [audience/occasion]`
+Example: "sarcastic political humor coffee mug gift"
+
+---
+
+## 2. Platform-Specific Keyword Rules
+
+See `references/marketplace-keyword-rules.md` for detailed per-platform rules.
+
+### Quick Reference
+
+| Platform | Title Limit | Tags/Keywords | Priority Rule |
+|----------|------------|---------------|---------------|
+| **Etsy** | 140 chars | 13 tags (multi-word phrases, no single words) | First 40 chars most visible in search |
+| **Amazon** | 200 chars (80 optimal) | 250-byte backend keywords | Primary keyword at title start; backend = synonyms only |
+| **Shopify** | 70 chars (SEO title) | Meta description + collection page copy | Google SEO rules apply; collection pages rank higher than products |
+| **SaaS** | 50-60 chars | N/A (Google organic) | Target one primary keyword per page; use related terms naturally |
+
+### Critical Platform Gotchas
+
+- **Etsy:** Tags are multi-word phrases, NOT single words. "vintage coffee mug" is one tag. All 13 tag slots must be used.
+- **Amazon:** Backend keywords have a 250-byte (not character) limit. No punctuation, no brand names, no ASINs. Only add synonyms — don't repeat title words.
+- **Shopify:** Product pages are hard to rank on Google. Prioritize collection pages for generic keywords. Product pages target specific long-tail.
+
+---
+
+## 3. Keyword Clustering & Topical Authority
+
+### Pillar-Cluster Model
+
+```
+Pillar Page: "Print on Demand Guide" (head term, 3000+ words)
+  ├── Cluster: "POD Pricing Strategy" (commercial intent)
+  ├── Cluster: "How to Design for POD" (informational)
+  ├── Cluster: "Best POD Providers Compared" (commercial investigation)
+  ├── Cluster: "POD Profit Margins Explained" (informational)
+  └── Cluster: "Start POD Business on Etsy" (transactional)
+```
+
+**Rules:**
+1. Each cluster targets one keyword group with shared intent
+2. Every cluster page links back to the pillar
+3. Pillar links out to all clusters
+4. No two clusters should target the same primary keyword (cannibalization)
+
+### Cluster Types
+
+| Type | Purpose | Example |
+|------|---------|---------|
+| **Topic cluster** | Build authority on a broad subject | "e-commerce analytics" pillar |
+| **Product cluster** | Cover variations of one product type | "custom mugs" with design/printing/shipping sub-topics |
+| **Comparison cluster** | Own the "X vs Y" search space | "Printify vs Printful vs Gelato" |
+| **Question cluster** | Capture informational queries | "How does POD work?" FAQ hub |
+
+---
+
+## 4. Cannibalization Detection
+
+Keyword cannibalization: two or more pages on the same site compete for the same keyword, splitting authority and harming both.
+
+### Detection Protocol
+
+1. **Search Console check:** Export queries, sort by page. If 2+ URLs appear for the same query with similar impressions, it's cannibalized.
+2. **SERP check:** Search `site:yourdomain.com "target keyword"` — if multiple results appear, confirm overlap.
+3. **Intent check:** Do the two pages serve the same search intent? If yes = cannibalization. If different intents (one informational, one transactional) = acceptable.
+
+### Resolution Options
+
+| Strategy | When to Use |
+|----------|------------|
+| **Merge** | Two thin pages on the same topic — combine into one authoritative page |
+| **Redirect** | One page is clearly weaker — 301 redirect to the stronger one |
+| **Differentiate** | Both pages serve different intents — sharpen each page's keyword focus |
+| **Canonical** | Duplicate content from variants/parameters — canonical tag to the primary |
+| **Noindex** | Low-value duplicate (tag page, filter page) — noindex to remove from competition |
+
+---
+
+## 5. Keyword Tracking
+
+### Tool Selection by Platform
+
+| Platform | Recommended Tool | What It Tracks |
+|----------|-----------------|----------------|
+| **Etsy** | eRank, Marmalead, Alura | Tag performance, listing quality score, search rank |
+| **Amazon** | Helium 10, Jungle Scout | Keyword rank, search volume, competitor keywords |
+| **Shopify/SaaS** | Ahrefs, SEMrush, Google Search Console | Google rank, SERP features, CTR, impressions |
+| **Cross-platform** | Google Trends | Relative demand, seasonality, geographic distribution |
+
+### Tracking Cadence
+
+- **Weekly:** Check rank movement for top 20 target keywords
+- **Monthly:** Full keyword portfolio review (new opportunities, declining terms)
+- **Quarterly:** Competitive keyword gap analysis
+- **After changes:** Re-check ranks 2-4 weeks after title/tag optimizations (Etsy re-indexes in 4-6 weeks)
+
+---
+
+## Related Skills
+
+- **seo-audit** — Diagnose why pages aren't ranking (technical + on-page audit)
+- **seo-strategy** — Build optimized pages, programmatic SEO, schema markup, AI search
+- **site-architecture** — Plan page hierarchy, navigation, URL structure
+- **copywriting** — Write the actual content once keywords are chosen
+- **seller-persona** — Understand which keywords matter for POD vs dropship vs inventory sellers
+
+---
+
+## Verification
+
+After applying this skill, verify:
+- [ ] Each keyword is mapped to a specific search intent (informational/navigational/transactional/commercial)
+- [ ] Etsy tags are multi-word phrases (not single words) and all 13 slots are used
+- [ ] Amazon backend keywords do not repeat title words and stay within 250-byte limit
+- [ ] No two pages/listings target the same primary keyword (cannibalization check)
+- [ ] Keyword clusters link back to their pillar page and pillar links to all clusters
+- [ ] Platform-specific limits respected (Etsy 140-char title, Amazon 200-char title, Shopify 70-char SEO title)
+- [ ] Long-tail keywords follow the `[adjective] + [topic/theme] + [product type] + [audience/occasion]` pattern
+
+## Do NOT Use When
+
+| Instead of this skill | Use | Why |
+|---|---|---|
+| Diagnosing why pages are not ranking | `seo-audit` | SEO audit covers technical SEO, crawlability, indexation, Core Web Vitals -- diagnostic problems, not keyword selection |
+| Building optimized pages at scale | `seo-strategy` | SEO strategy owns page construction, schema markup, and programmatic SEO patterns |
+| Writing the actual content for pages | `copywriting` | Copywriting owns tone, messaging, and content creation once keywords are chosen |
+| Planning site page hierarchy and navigation | `site-architecture` | Site architecture owns URL structure, navigation taxonomy, and page-to-page relationships |
+| Understanding the target buyer persona | `seller-persona` | Seller persona owns the business context that informs which keywords matter |
+
+*Version 1.1.0 — 2026-03-28*