tejas-ai-skills 1.0.0

package/README.md

@@ -0,0 +1,14 @@
+# Tejas UX Skills
+
+A collection of AI Agent skills focused on UX Psychology and UI Copywriting. 
+When added to your AI coding assistant workspace, it helps your agents write better copy and design interfaces with core psychology principles in mind.
+
+## Installation
+
+To automatically install these skills into your project's `.agents/skills` folder, simply run:
+
+```bash
+npx tejas-ai-skills
+```
+
+This will instantly copy the skills into your local project so your AI agents can discover them!

package/cli.js

@@ -0,0 +1,39 @@
+#!/usr/bin/env node
+const fs = require('fs');
+const path = require('path');
+
+const sourceDir = path.join(__dirname, 'skills');
+const targetDir = path.join(process.cwd(), '.agents', 'skills');
+
+console.log('🚀 Installing tejas-ai-skills into .agents/skills...');
+
+if (!fs.existsSync(targetDir)) {
+  fs.mkdirSync(targetDir, { recursive: true });
+}
+
+function copyDirectorySync(src, dest) {
+  if (!fs.existsSync(dest)) {
+    fs.mkdirSync(dest, { recursive: true });
+  }
+
+  const entries = fs.readdirSync(src, { withFileTypes: true });
+
+  for (let entry of entries) {
+    const srcPath = path.join(src, entry.name);
+    const destPath = path.join(dest, entry.name);
+
+    if (entry.isDirectory()) {
+      copyDirectorySync(srcPath, destPath);
+    } else {
+      fs.copyFileSync(srcPath, destPath);
+    }
+  }
+}
+
+try {
+  copyDirectorySync(sourceDir, targetDir);
+  console.log('✅ Skills successfully installed! Your AI agents can now use them.');
+} catch (error) {
+  console.error('❌ Failed to install skills:', error);
+  process.exit(1);
+}

package/package.json

@@ -0,0 +1,25 @@
+{
+  "name": "tejas-ai-skills",
+  "version": "1.0.0",
+  "description": "AI Agent skills for UX Psychology and UI Copy",
+  "main": "index.js",
+  "bin": {
+    "tejas-ai-skills": "./cli.js"
+  },
+  "scripts": {
+    "test": "echo \"Error: no test specified\" && exit 1"
+  },
+  "keywords": [
+    "ai",
+    "agents",
+    "skills",
+    "ux",
+    "ui"
+  ],
+  "author": "Tejas",
+  "license": "MIT",
+  "files": [
+    "skills",
+    "cli.js"
+  ]
+}

package/skills/ux-psychology-principles/SKILL.md

@@ -0,0 +1,63 @@
+---
+name: ux-psychology-principles
+description: A comprehensive guide to utilizing human psychology, cognitive biases, and UX laws to design highly effective, engaging, and ethical applications.
+---
+
+# UX Psychology Principles & Cognitive Biases for App Design
+
+This document serves as a comprehensive guide to utilizing human psychology, cognitive biases, and UX laws to design highly effective, engaging, and ethical applications. 
+
+## 1. Core Psychology Principles (The Fundamentals)
+
+*   **Decision Fatigue & Paradox of Choice**: When presented with too many options—like multiple blank fields or a massive product catalog—users experience cognitive overload, leading to decision paralysis and abandonment.
+    *   *Implementation*: Use "Guided Selling" (quizzes, smart filtering) to narrow choices down logically. 
+*   **Smart Defaults**: Users generally interpret default settings as trusted recommendations.
+    *   *Implementation*: Pre-select the most common choices. Shift the user's task from "filling out from scratch" to simply "scanning and adjusting".
+*   **Goal Gradient Effect**: People move faster toward a goal the closer they feel they are to finishing it.
+    *   *Implementation*: Never start a user at 0%. Give them an artificial head start (e.g., showing an onboarding checklist as already 20% complete) to create momentum.
+*   **Reciprocity**: When you provide value upfront, it triggers a deep human instinct to return the favor, creating an unconscious debt.
+    *   *Implementation*: Give users a free sample, partial report, or useful tool before putting up a sign-up wall.
+*   **The IKEA Effect & Endowment Effect**: People value items significantly more when they build the items themselves or feel a sense of ownership over them.
+    *   *Implementation*: Allow users to customize their profile, set goals, or complete a lesson before asking them to create an account. Leaving will feel like abandoning their own creation.
+*   **Status Quo Bias / Loss Aversion**: Humans are wired to protect what they already have, making the pain of losing something twice as powerful as the pleasure of gaining it.
+    *   *Implementation*: Frame upgrade or retention prompts around what the user is about to *lose* (e.g., actual files or progress) rather than what they could gain.
+*   **Contrast Effect & Anchoring**: The brain evaluates information relative to what it saw immediately before (the "anchor").
+    *   *Implementation*: Control the first number a user sees. A $50 expense feels like a minor rounding error when presented directly after a $1,900 purchase.
+
+## 2. Advanced UX Laws & Cognitive Biases
+
+*   **Zeigarnik Effect**: People naturally remember uncompleted or interrupted tasks better than completed ones, as unfinished tasks create cognitive tension. 
+    *   *Implementation*: Use progress bars, step counters, and checklists to remind users of incomplete tasks. Combining this with an initial head-start ("initial endowment") drastically increases completion rates.
+*   **Fitts's Law**: The time required to acquire a target depends on the distance to it and its size.
+    *   *Implementation*: Ensure touch targets (like interactive buttons) are large enough to accurately tap and have ample spacing between them, particularly on mobile devices.
+*   **Gestalt Principles**: Humans perceive visual elements as grouped patterns to minimize cognitive load.
+    *   *Similarity*: Group items with similar characteristics (like colors or icons) so they are perceived as related.
+    *   *Proximity*: Place related elements close to each other so they are perceived as a single unit.
+    *   *Simplicity*: Eliminate irrelevant information and obvious visual elements so the most important features stand out.
+*   **Peak-End Rule**: People judge an experience largely based on how they felt at its peak (the most intense point) and at its end, rather than an average of every moment.
+    *   *Implementation*: Focus on delighting users during the most critical interactions and final moments (e.g., checkout or task completion). Remember that negative peaks leave a lasting impression.
+*   **Serial Position Effect**: Users have a propensity to best remember the first and last items in a series.
+    *   *Implementation*: Position key actions on the far left and far right of navigation menus. Place the least important items in the middle.
+*   **Von Restorff Effect (The Isolation Effect)**: When multiple similar objects are present, the one that differs from the rest is most likely to be remembered.
+    *   *Implementation*: Make key actions visually distinctive from surrounding elements, but use restraint to ensure they don't look like distracting ads.
+
+## 3. Additional UX Laws (Bonus)
+
+*   **Jakob's Law**: Users spend most of their time on other sites. This means that users prefer your site to work the same way as all the other sites they already know.
+    *   *Implementation*: Leverage familiar UI patterns for standard interactions (e.g., standard e-commerce checkout flows, conventional navigation menus) rather than reinventing the wheel.
+*   **Hick's Law**: The time it takes to make a decision increases with the number and complexity of choices.
+    *   *Implementation*: Break complex processes down into smaller, bite-sized steps (like a multi-step form instead of one long page) to reduce cognitive load.
+*   **Doherty Threshold**: Productivity soars when a computer and its users interact at a pace (<400ms) that ensures that neither has to wait on the other.
+    *   *Implementation*: Provide immediate visual feedback for all interactions (e.g., button loading states, skeleton screens). If an action takes longer, use a progress indicator to manage expectations.
+*   **Aesthetic-Usability Effect**: Users often perceive aesthetically pleasing design as design that’s more usable.
+    *   *Implementation*: Invest in high-quality visual design. A beautiful interface can mask minor usability issues and foster patience and trust.
+
+## 4. Ethical Design: Dark Patterns to Avoid
+
+Exploiting cognitive biases to manipulate users against their best interests is known as using "dark patterns". While these might create short-term metric boosts, they severely harm user trust, autonomy, and long-term retention. Avoid the following patterns:
+
+*   **Sneaking (Hidden Information)**: Tricking customers into agreeing to something they did not intend to, such as hiding costs until the final stage of checkout or secretly adding items to a basket.
+*   **Aesthetic Manipulation & Visual Interference**: Designing interfaces to intentionally hide choices or distract the user's attention from options that benefit them (e.g., making a "cancel subscription" button nearly invisible).
+*   **Price Comparison Prevention**: Intentionally obfuscating product tiers or structuring pricing layouts so that it is difficult for users to make an informed, cost-effective decision.
+*   **Bad Defaults**: Exploiting the default effect to pre-select options that harm user privacy, such as defaulting to aggressive data collection until the user actively hunts down the settings to opt out. 
+*   **Roach Motel**: Making it incredibly easy to get into a situation (like signing up for a service) but intentionally difficult to get out of it.

package/skills/ux-writing-and-ui-copy/SKILL.md

@@ -0,0 +1,47 @@
+---
+name: ux-writing-and-ui-copy
+description: A comprehensive guide to UX writing, microcopy, psychological triggers in UI copy, and writing helpful error messages.
+---
+
+# UX Writing & UI Copy Guide
+
+UX writing is the practice of crafting the words, phrases, and microcopy that guide users through a digital product or interface. While UX writing covers the entire narrative of a digital experience, **microcopy** specifically refers to the brief text that helps users navigate the interface, such as button labels, form hints, and error messages. 
+
+Because users typically read only about 20% of the text on a webpage, the words they do read are critical to preventing frustration and driving conversions.
+
+## 1. Core UX Writing Principles
+
+*   **Be Clear Before You Are Clever:** Wit is a bonus, but clarity is the baseline. Avoid jargon, technical terms, and idioms. Never use double negatives (e.g., "I do not want to unsubscribe"), which force users to spend extra time decoding the message. 
+*   **Be Concise and Scannable:** "Less but better" is the golden rule. Write at roughly a sixth-grade reading level. Because users scan interfaces in an "F-pattern," prioritize text by using short blocks, bulleted lists, and numerals (e.g., "2" instead of "two"). 
+*   **Use Specific, Action-Oriented Verbs:** Buttons and links should tell users exactly what will happen. Prioritize clarity over cuteness; avoid generic labels like "Submit" or "Next" in favor of descriptive verbs like "Connect," "Save," or "Send My Application". 
+*   **Maintain Consistency:** Inconsistency creates confusion. If you call an action "scheduling" on one screen, do not call it "booking" on another. 
+*   **Progressive Disclosure:** Especially on mobile devices with limited screen real estate, provide just enough upfront information for a baseline understanding, and offer users the ability to explore and learn more if they choose.
+
+## 2. Psychological Triggers in UI Copy
+
+*   **The Zeigarnik Effect:** People naturally remember uncompleted tasks better than completed ones and feel cognitive tension to finish them. You can leverage this in your microcopy:
+    *   *Progress Indicators:* Pair visual bars with explicit copy like "**Step 2 of 4: Add your shipping details**".
+    *   *Incomplete Task Reminders:* Use copy like "**You left some items in your cart**" to bring users back. 
+    *   *Initial Endowment:* Give users a head start by pre-filling steps and using copy like "**You're already 30% done!**".
+*   **Anticipate Needs and Alleviate Fears:** Add tiny reassuring notes near high-friction areas. For example, a single sentence below a signup button saying "We respect your privacy. Unsubscribe at any time." can drastically increase conversion rates. 
+
+## 3. Writing Helpful Error Messages
+
+Error messages are critical moments that test user trust. Handled poorly, they cause abandonment. 
+
+*   **Don't Blame the User:** The tone of an error message should be compassionate, neutral, and supportive. Avoid words like *invalid*, *illegal*, or *incorrect* that make the user feel judged.
+*   **Be Precise and Constructive:** Never just say "Something went wrong." Explain exactly what happened and provide a clear, actionable next step to fix it.
+*   **Preserve User Effort:** If a user makes a mistake, allow them to edit their original input rather than forcing them to start over from scratch.
+*   **Proximity:** Ensure the error message is displayed directly next to the relevant field or component where the error occurred.
+
+## 4. Accessibility and Inclusivity
+
+*   **Descriptive Links:** Never use ambiguous phrases like "Click here" or "Read more". Because screen reader users often navigate by reading links out of context, link text must clearly describe the destination.
+*   **Don't Rely on Color Alone:** Support visual cues with text or icons. For example, an error state should include a written message, not just a red border.
+*   **Bias-Free Language:** Use inclusive, respectful language. Avoid gendered words (e.g., use "workforce" instead of "manpower") and utilize the singular "they" for individuals of unspecified gender.
+
+## 5. Content Testing and Governance
+
+*   **Test and Iterate:** Copy is a hypothesis until it meets users. Run A/B tests on button labels and error phrasing, track completion rates, and observe user hesitation during usability sessions. 
+*   **Create a UX Content Style Guide:** Maintain a centralized playbook that covers brand voice, tone, grammar, and component-specific copy patterns (like modals or tooltips). This ensures that every piece of content feels like part of a cohesive whole.
+*   **Write Alongside Design:** Do not treat UX writing as an afterthought or fill early designs with "lorem ipsum." Content strategy and UI design should happen in parallel to ensure layouts accommodate the necessary text.