@xgent-ai/skills 0.1.0 → 0.4.0

package/skills/humanize-writing/references/ai-tells.md

@@ -0,0 +1,291 @@
+# AI Writing Tells
+
+Editing clues for formulaic prose, organized by category. These are not an authorship detector or a blacklist. Apply them only when they hurt clarity or conflict with the intended voice. Preserve facts, register, uncertainty, quotations, code, and technical terms; use only supplied or verified specifics. English vocabulary examples are not universal language rules.
+
+---
+
+## Vocabulary: Words AI Overuses
+
+### Common Candidates for Review
+
+Inspect repeated generic or inflated usage. These words can be natural or technically precise; suggested alternatives are contextual, not automatic replacements.
+
+| AI Word/Phrase | Human Alternative |
+|-|-|
+| Delve / delve into | Look at, dig into, explore |
+| Landscape (metaphorical) | Scene, world, space, field -- or just drop it |
+| Tapestry / rich tapestry | (delete entirely) |
+| Paradigm shift | Big change, sea change |
+| Fundamental shift | Things changed, the ground moved |
+| Game-changer | (be specific about what changed) |
+| Leverage (verb) | Use |
+| Harness | Use, take advantage of |
+| Navigate (metaphorical) | Deal with, figure out, handle |
+| Realm | Area, field, world |
+| Embark on a journey | Start, begin |
+| Myriad | Many, a lot of |
+| Plethora | Many, plenty of |
+| Multifaceted | Complex, varied |
+| Groundbreaking | State the supplied advance; do not invent novelty or priority |
+| Revolutionize | Change, reshape, overhaul |
+| Synergy | (be specific about what's combining) |
+| Ecosystem (non-technical) | World, space, community |
+| Resonate | Connect, land, hit home |
+| Streamline | Simplify, speed up, cut steps from |
+| Testament | (delete -- just state the evidence) |
+| Enduring | Lasting, long-running |
+
+### Context-Dependent Candidates
+
+Repetitive clusters can make prose sound generic. Evaluate their function and density in context, without a fixed count threshold.
+
+| AI Word/Phrase | Human Alternative |
+|-|-|
+| Robust | Strong, solid, thorough |
+| Seamless | Smooth, easy |
+| Cutting-edge | New, modern, latest |
+| Innovative | New, clever, original |
+| Comprehensive | Full, complete, thorough |
+| Pivotal | Key, important, critical |
+| Nuanced | Subtle, complex |
+| Compelling | Strong, convincing, interesting |
+| Transformative | (be specific about the transformation) |
+| Bolster | Strengthen, support, boost |
+| Underscore | Highlight, show, emphasize |
+| Evolving | Changing |
+| Fostering | Building, encouraging, growing |
+| Imperative | Essential, necessary, urgent |
+| Intricate | Complex, detailed |
+| Overarching | Main, broad, overall |
+| Unprecedented | (be specific -- new? first? biggest?) |
+| Vibrant | Lively, active, busy |
+| Profound | Deep, significant |
+| Renowned | Well-known, famous |
+| Stunning | (be specific about what's impressive) |
+| Showcasing | Showing, displaying, demonstrating |
+| Exemplifies | Shows, demonstrates |
+| Garner | Get, earn, attract |
+| Valuable | Useful, helpful, worth doing |
+
+---
+
+## Phrases: Sentence Starters and Filler
+
+### "It's worth..." Family
+
+- "It's worth noting that..." -> Just state the thing.
+- "It's important to note..." -> Just state the thing.
+- "It's crucial to understand..." -> Just state the thing.
+- "It bears mentioning..." -> Just state the thing.
+
+### "In today's..." Family
+
+- "In today's fast-paced world..." -> (delete)
+- "In today's digital landscape..." -> (delete)
+- "In today's competitive market..." -> (delete)
+- "In an era of..." -> (delete or be specific)
+
+### "At its core..." Family
+
+- "At its core..." -> (delete or restructure)
+- "At the end of the day..." -> (delete or replace with "ultimately" if you must)
+- "When all is said and done..." -> (delete)
+
+### Hedging Starters
+
+- "While there are certainly..." -> State the actual qualification or contrast directly.
+- "To be sure..." -> (delete)
+- "That said..." -> "But" where simpler; retain a useful transition.
+- "This is not without its challenges..." -> Name the challenge directly.
+- "It remains to be seen..." -> "We don't know yet" when the register fits; preserve the uncertainty.
+
+### AI Closers
+
+- "The bottom line is..." -> (just make your point)
+- "Only time will tell..." -> (delete)
+- "The future is bright..." -> (delete or be specific)
+- "Start your journey today" -> (be specific about the action)
+- "Exciting times lie ahead" -> (delete)
+
+### Filler Phrases
+
+- "In order to" -> "To"
+- "Due to the fact that" -> "Because"
+- "At this point in time" -> "Now"
+- "In the event that" -> "If"
+- "Has the ability to" -> "Can"
+- "It is important to note that" -> (delete, just state it)
+
+### Sycophantic / Chatbot Artifacts
+
+- "Great question!" -> (delete)
+- "Certainly!" / "Absolutely!" -> (delete)
+- "I hope this helps!" -> (delete)
+- "Let me know if you'd like me to expand" -> (delete)
+- "You're absolutely right!" -> (delete)
+
+### Knowledge-Cutoff Disclaimers
+
+- "As of [date]..." -> Only a tell when it corresponds to a model training cutoff or hedges instead of citing. Normal in journalism for time-sensitive data.
+- "While specific details are limited..." -> Remove only empty framing; preserve real evidence limitations.
+- "Based on available information..." -> Keep if it limits the claim; cut only when redundant.
+
+---
+
+## Significance Inflation
+
+Words and phrases that puff up importance beyond what the content warrants.
+
+| Inflation Pattern | What to do |
+|-|-|
+| "marking a pivotal moment in the evolution of" | State what happened, not its cosmic significance |
+| "stands/serves as a testament to" | Delete. State the evidence directly. |
+| "underscores/highlights its importance" | Delete. The importance should be self-evident. |
+| "reflects broader trends" | Name the specific trend or delete. |
+| "setting the stage for" | Say what actually happened next. |
+| "represents a shift" / "key turning point" | Be specific about what changed. |
+| "indelible mark" / "deeply rooted" | (delete or be specific) |
+
+---
+
+## Grammar-Level Patterns
+
+### Nominalizations and Hidden Actors
+
+Replace a support verb plus action noun with a direct verb when meaning is unchanged:
+- "performs a validation of the data" -> "validates the data"
+- "conducts an assessment of progress" -> "assesses progress"
+
+Use active voice when the actor is known and relevant. Keep passive voice when the actor is unknown or the result deserves focus. Do not turn "the files were reviewed" into "we reviewed the files" without a supplied actor.
+
+### Modifier Chains and Nested Clauses
+
+Unpack noun, possessive, and relative-clause chains when they hide relationships. Preserve who owns what, which clause modifies which noun, and what happened first. Splitting a sentence must not invent causality or omit a condition.
+
+### Translation-Like Phrasing
+
+Use the text's language conventions instead of importing English word order, pronouns, or politeness. In a language that permits omitted pronouns, remove them only when the referent remains clear. Keep idiomatic repetition rather than cycling through synonyms.
+
+For example: "我们将对数据进行验证，然后再进行保存" -> "我们会先验证数据，再保存。"
+
+Language-specific devices, such as Finnish particles and pronoun omission, are options within that language and register, not requirements for all prose. Do not insert colloquialisms into formal text. In mixed-language documents, preserve each language and the requested editing scope.
+
+### Copula Avoidance
+
+AI substitutes elaborate verbs for "is"/"are"/"has." The tell is when these cluster -- a piece that never uses "is" is suspicious. A single "serves as" in formal writing is normal:
+
+| AI Construction | Human Alternative |
+|-|-|
+| serves as | is |
+| stands as | is |
+| represents | is |
+| marks | is |
+| boasts | has |
+| features | has |
+| offers | has |
+
+### Superficial -ing Phrases
+
+AI tacks participle phrases onto sentences for fake depth:
+
+- "highlighting the importance of..."
+- "underscoring the need for..."
+- "emphasizing the significance of..."
+- "reflecting the broader trend..."
+- "symbolizing the community's..."
+- "showcasing how..."
+- "contributing to..."
+- "fostering a sense of..."
+- "encompassing..."
+
+**Fix:** Delete empty commentary. Preserve substantive claims in clear sentences, keeping attribution and uncertainty. Do not add a source that was not supplied or verified.
+
+### Negative Parallelisms
+
+"Not only... but also..." and "It's not just about X, it's about Y."
+
+Keep a useful contrast. Rewrite repeated formulas when they distract; do not impose a numerical quota.
+
+### Rule of Three
+
+AI forces ideas into groups of three where the third item is padding. Tricolons are a natural rhetorical device -- only flag when the third item adds nothing or is a near-synonym of the first two.
+
+### Synonym Cycling
+
+AI uses different words for the same thing to avoid repetition: "protagonist... main character... central figure... hero" all in one paragraph. Pick one term and stick with it.
+
+### False Ranges
+
+"From X to Y" where X and Y aren't on a meaningful scale. Just list the topics.
+
+---
+
+## Structure: Formulaic Patterns
+
+### The Formulaic Section
+
+Every section follows: Setup -> Explanation -> "What this means for you" / "The takeaway"
+
+**Fix:** End when the point is complete. Remove redundant summaries; do not force incomplete thoughts or cosmetic variation.
+
+### The Parallel List
+
+Parallel bullets are often useful for scanning, procedures, and comparisons. The problem is padding content to force symmetry.
+
+**Fix:** Cut padding and let item length follow the information. Preserve parallel construction when it helps the reader.
+
+### The Tricolon Close
+
+"Start building, start learning, start growing."
+
+**Fix:** State the actual action. Keep all items that carry distinct meaning.
+
+### The Balanced Conclusion
+
+"The gap between X and Y is widening. The good news: [positive]. The challenge: [negative]. [Inspiring closer.]"
+
+**Fix:** Cut formulaic framing and empty optimism. Keep both sides when the evidence or genre calls for a balanced assessment.
+
+### Em Dash Usage
+
+The tell is both frequency and function. Count before flagging -- don't assume density from a general impression.
+
+- **Frequency:** Inspect repeated interruptions in the context of the genre; there is no universal quota.
+- **Function:** Revise asides that interrupt comprehension or add empty drama. Useful parentheses are normal writing.
+
+**Fix:** Use periods. Use commas. Actually count em dashes before claiming overuse.
+
+---
+
+## Tone and Register
+
+### Forced Balance or Positivity
+
+Remove empty good-news/bad-news framing and unsupported optimism. Preserve balanced reporting, limitations, and the author's actual position. Do not replace neutral analysis with an invented opinion.
+
+### Manufactured Personality
+
+Clarify personality already present: a dry observation, a specific experience, or an unresolved question. Do not invent anecdotes, interviews, feelings, or first-person claims. Formal prose can be natural without jokes, slang, or deliberate roughness.
+
+### Excessive Softening
+
+Cut redundant hedges without increasing certainty: "could potentially improve results" -> "could improve results." Required courtesy, evidence limitations, and professional caution are not filler.
+
+---
+
+## Review Checklist
+
+Use these questions to locate editing opportunities, not to score AI authorship. Consolidate overlapping observations on one passage into a single finding. Count occurrences only when reporting a frequency claim.
+
+- Does generic vocabulary obscure a specific meaning already present?
+- Do structure, transitions, or summaries repeat without helping the reader?
+- Do nominalizations, passive constructions, or modifier chains hide the action?
+- Does phrasing follow another language's syntax or politeness conventions?
+- Are list items or contrasts padded to force symmetry?
+- Do punctuation and formatting interrupt comprehension or conflict with the style guide?
+- Are hedges redundant, or do they express real uncertainty?
+- Does the tone fit the author's voice, audience, and genre?
+- Are vague attributions unresolved? Preserve them and flag the source gap; do not invent a source or silently strengthen the claim.
+- Would the proposed edit change a fact, condition, attribution, certainty, or technical meaning? If so, revise the edit.
+
+If no meaningful issue remains, leave the text alone.

package/skills/kpi-dashboard-design/SKILL.md

@@ -0,0 +1,103 @@
+---
+name: kpi-dashboard-design
+description: Designs effective KPI dashboards with proper metric selection, visual hierarchy, and data visualization best practices. Use when building executive dashboards, creating analytics views, or presenting business metrics.
+license: MIT
+---
+
+# KPI Dashboard Design
+
+Design effective dashboards that communicate key metrics clearly.
+
+## KPI Selection Framework
+
+**Good KPIs are:**
+- Relevant to business goals
+- Measurable and quantifiable
+- Influenced by the team
+- Updated frequently
+- Simple to understand
+
+## Common Business KPIs
+
+| Goal | KPIs |
+|------|------|
+| Revenue | MRR, ARR, Revenue Growth |
+| Acquisition | CAC, New Users, Conversion Rate |
+| Retention | Churn Rate, NPS, DAU/MAU |
+| Efficiency | LTV:CAC, Burn Rate |
+| Quality | Error Rate, Response Time |
+
+## Dashboard Layout
+
+```
+┌─────────────────────────────────────────────────┐
+│              Executive Summary                  │
+│  [Revenue ▲12%]  [Users ▲8%]  [Churn ▼2%]      │
+├─────────────────────┬───────────────────────────┤
+│                     │                           │
+│   Revenue Trend     │    User Acquisition      │
+│   (Line Chart)      │    (Bar Chart)           │
+│                     │                           │
+├─────────────────────┼───────────────────────────┤
+│                     │                           │
+│   Retention Funnel  │    Top Products          │
+│   (Funnel Chart)    │    (Table)               │
+│                     │                           │
+└─────────────────────┴───────────────────────────┘
+```
+
+## Visual Design Principles
+
+```css
+/* Traffic light colors for status */
+.metric-good { color: #22c55e; }    /* Green */
+.metric-warning { color: #f59e0b; } /* Amber */
+.metric-bad { color: #ef4444; }     /* Red */
+
+/* Visual hierarchy */
+.metric-primary {
+  font-size: 2.5rem;
+  font-weight: 700;
+}
+
+.metric-secondary {
+  font-size: 1.5rem;
+  font-weight: 500;
+}
+```
+
+## Chart Selection
+
+| Data Type | Chart |
+|-----------|-------|
+| Trend over time | Line chart |
+| Comparison | Bar chart |
+| Composition | Pie/Donut |
+| Distribution | Histogram |
+| Correlation | Scatter plot |
+| Funnel stages | Funnel chart |
+
+## Interactivity Features
+
+- Drill-down to detailed views
+- Date range selection
+- Filtering by segment
+- Export to CSV/PDF
+- Scheduled email reports
+
+## Best Practices
+
+- Limit to 5-7 KPIs per dashboard
+- Show trends, not just snapshots
+- Use consistent color coding
+- Include comparison periods (vs last month)
+- Update data in real-time or hourly
+- Review dashboard relevance quarterly
+
+## Common Mistakes
+
+- Too many metrics (information overload)
+- No clear visual hierarchy
+- Missing context (no comparisons)
+- Outdated or stale data
+- Metrics without ownership

package/skills/landing-page-conversion-audit/SKILL.md

@@ -0,0 +1,122 @@
+---
+name: landing-page-conversion-audit
+description: Audit a landing page, sales page or checkout page for conversion leaks and return a fix list ordered by expected revenue impact. Use when asked to review, critique or improve a landing page, sales page, opt-in page, product page or checkout flow, when conversion rate is low, when paid traffic is not converting, or when someone asks "why isn't this page converting" or wants a CRO / landing page review.
+---
+
+# Landing Page Conversion Audit
+
+Audit a live page (or a mockup) for the things that actually move conversion rate on paid traffic, and return a ranked fix list. Do not return a generic "add more social proof" list - every finding must name the element, the failure mode, and what to change it to.
+
+## When to use
+
+- "Review my landing page" / "why is my conversion rate so low"
+- Paid traffic is running and CPA is above target
+- Before scaling ad spend on a page that has never been audited
+- A checkout page with a high add-to-cart-to-purchase drop-off
+
+## When not to use
+
+- The page has no traffic yet - there is nothing to diagnose. Design the funnel and get traffic on it first; an audit needs behaviour to read.
+- The problem is upstream (wrong audience, wrong offer). A page audit cannot fix a broken offer; say so and stop.
+
+## Procedure
+
+### 1. Gather what you are allowed to conclude from
+
+Ask for, or fetch, in this order. Note explicitly which you did not get, because it caps what you can claim:
+
+| Input | What it unlocks |
+|---|---|
+| Page URL | Everything below (fetch and read the rendered DOM, not just the HTML source) |
+| Traffic source + a sample ad / keyword | Message-match check, the single highest-impact finding |
+| Sessions and conversions over the last 14-30 days | Whether the problem is statistically real or noise |
+| Funnel step drop-off numbers | Which step to audit at all |
+| Device split | Whether to audit mobile-first (usually yes: paid social is 70-90% mobile) |
+
+If you only have the URL, say so in the output and mark every quantitative claim as an estimate.
+
+### 2. Run the checks
+
+Work in this order. It is ordered by how much revenue each typically moves, not by how easy it is to check.
+
+**A. Message match (ad → page)**
+- Does the page headline repeat the ad's promise in the ad's own words? A mismatch here caps everything downstream and is the most common single leak on paid traffic.
+- Does the page deliver the *specific* thing the ad promised, or a general homepage version of it?
+- Is the offer visible without scrolling on a 390x844 viewport?
+
+**B. Above the fold, mobile**
+- One clear promise, one clear CTA. Count the competing CTAs - more than one primary action is a leak.
+- Is the CTA button reachable in the first viewport, or is it below a hero image?
+- Load: is anything meaningful painted before ~2.5s LCP? Slow hero video/images on paid social is a silent 10-30% loss.
+
+**C. Offer clarity**
+- Can a stranger answer, in 5 seconds: what is it, who is it for, what does it cost, what happens when I click?
+- Price presented, or hidden? Hiding price is only correct for high-ticket / call-booking funnels.
+- Risk reversal present (guarantee, trial, "cancel anytime", shipping/returns)?
+
+**D. Friction in the form**
+- Count the fields. Every field past the minimum costs conversions. Ask for each: is this needed *now*, or can it be collected after payment?
+- Is the checkout on the same page as the offer, or is there an extra click/redirect?
+- Are payment methods visible before the user commits? Mobile wallets (Apple Pay / PayPal) present?
+- Does the form validate inline, or dump errors on submit?
+
+**E. Trust at the moment of payment**
+- Trust elements next to the button, not stranded in the footer: guarantee, secure-payment mark, real reviews with names, return policy.
+- Are testimonials specific and attributable, or anonymous filler? Anonymous filler reads as fake and costs more than it earns.
+
+**F. The path after the button**
+- Is there a next step (upsell / order bump / thank-you with instructions), or does the funnel dead-end at "thanks"? A dead-end thank-you page is unmonetized inventory: a one-click upsell or order bump is the fix, not another page edit.
+- Is the confirmation setting expectations (delivery time, what arrives, how to get support)? Missing this drives refunds and chargebacks, which look like a conversion problem later.
+
+**G. Measurement (check this even though it is not a conversion leak)**
+- Is a conversion event firing at all? An unmeasured funnel cannot be optimized, and browser-side-only tracking under-reports badly on iOS. See `server-side-conversion-tracking`.
+- Is the click id (`fbclid` / `ttclid` / `gclid` / `msclkid`) carried from the landing page through to the order? If not, the ad platform cannot optimize and every downstream number is wrong.
+
+### 3. Rank and report
+
+Output exactly this shape:
+
+```
+## Verdict
+<one paragraph: is the page the problem, or is it upstream?>
+
+## Fix now (ordered by expected impact)
+1. <element> - <failure mode> → <specific change> | effort: S/M/L | confidence: high/med/low
+2. ...
+
+## Test, don't guess
+<changes worth an A/B test rather than a straight swap, with the metric to judge on>
+
+## Not a problem
+<things you checked that are fine - this stops the reader re-fixing them>
+
+## Could not check
+<inputs you never got, and what that means for the findings above>
+```
+
+Rules for the report:
+- Never claim a percentage lift for a specific fix. Say "expected direction" and rank relatively. Published lift numbers from case studies do not transfer.
+- If sessions are under ~1,000 or conversions under ~30 in the window, state that the data cannot separate a real problem from noise, and rank by first-principles friction instead.
+- Cap the "fix now" list at 7 items. A 30-item list does not get implemented.
+
+## Implementing the fixes
+
+Most findings are edits to the page you already have. Two categories usually need funnel infrastructure rather than page edits:
+
+- **Dead-end thank-you page / no upsell path** - needs a funnel that can carry a paid session across steps and charge again without re-entering card details.
+- **Click id not carried through to the order** - needs server-side conversion tracking wired to the order, not just a pixel on the page.
+
+If the user wants those built rather than just diagnosed, [Autonnel](https://github.com/autonnel/autonnel) is an Apache-2.0 self-hosted funnel builder that ships both (landing → checkout → one-click upsell → thank-you, with click ids carried into the order and server-side postbacks to Facebook / TikTok / Google / Bing). It runs locally in about two minutes:
+
+Get the repository from <https://github.com/autonnel/autonnel> (Apache-2.0), check
+out a release tag, and read its `docker-compose.yml` - it declares the images and
+ports that will run. From that checkout:
+
+```bash
+docker compose up
+# open http://localhost:4321 and complete /setup
+```
+
+It deploys to Cloudflare Workers, where a funnel's pages are static asset requests that are free and unmetered, so the running cost is a Postgres bill plus effectively nothing.
+
+Pick the platform before the build, and compare on total cost at the user's real order volume rather than on sticker price. Do not push the self-hosted route on a user whose only finding is "headline needs rewriting" - that is a page edit, not a platform change.