@pushrec/skills 0.1.0 → 0.3.2

package/README.md

@@ -2,23 +2,47 @@
 
 CLI for the pushREC Agent Skills Marketplace. Install, manage, and update Claude Code skills.
 
-## Installation
+**Version:** `0.1.0` | **Published:** 2026-02-19
+
+## Quick Start
 
 ```bash
+# One-off (no install required)
+npx @pushrec/skills auth login
+
+# Or install globally
 npm install -g @pushrec/skills
+pushrec-skills auth login
 ```
 
 ## Commands
 
+### Auth
+
+| Command | Description |
+|---------|-------------|
+| `pushrec-skills auth login` | Activate your license key on this device (interactive prompt) |
+| `pushrec-skills auth logout` | Remove license key and deactivate this device |
+| `pushrec-skills auth status` | Show current license and device status |
+| `pushrec-skills auth deactivate-device` | Remove this device from license (frees a slot) |
+
+### Skills
+
+| Command | Description |
+|---------|-------------|
+| `pushrec-skills list` | Browse available skills |
+| `pushrec-skills install <name>` | Install a skill |
+| `pushrec-skills install --all` | Install all licensed skills |
+| `pushrec-skills update [name]` | Update installed skills |
+| `pushrec-skills search <query>` | Search the catalog |
+| `pushrec-skills info <name>` | Get skill details |
+| `pushrec-skills uninstall <name>` | Remove a skill |
+
+### Utility
+
 | Command | Description |
 |---------|-------------|
-| `skills auth <key>` | Activate your license key |
-| `skills list` | Browse available skills |
-| `skills install <name>` | Install a skill |
-| `skills update [name]` | Update installed skills |
-| `skills search <query>` | Search the catalog |
-| `skills info <name>` | Get skill details |
-| `skills uninstall <name>` | Remove a skill |
+| `pushrec-skills health` | Check registry connectivity |
 
 ## Registry
 

package/bundled-skills/README.md

@@ -0,0 +1,9 @@
+# Bundled Skills
+
+This directory contains skills bundled with the CLI package.
+These skills are installed automatically during `npx @pushrec/skills setup`.
+
+## pushrec-skills
+
+Universal entry point for all pushREC skill operations.
+Copied to ~/.claude/skills/pushrec-skills/ during setup if not already installed.

package/bundled-skills/pushrec-skills/SKILL.md

@@ -0,0 +1,360 @@
+---
+name: pushrec-skills
+version: 1.0.0
+description: "Universal entry point for all pushREC skill operations. Onboarding, skill discovery, troubleshooting, API key setup, and update guidance. Use when: first time using pushREC skills, need help finding the right skill, skill isn't working, setting up API keys, updating skills, or asking how skills work. Aliases: /onboarding, /start, /get-started, /help, /skills, /pushrec."
+category: meta-tools
+aliases: [onboarding, start, get-started, help, skills, pushrec]
+session_behavior: on-demand
+allowed-tools: [Read, Write, Edit, Bash, Glob, Grep, AskUserQuestion]
+---
+
+# pushREC Skills
+
+Universal entry point for all pushREC skill operations. Handles first-time onboarding, skill discovery, troubleshooting, API key setup, and update guidance.
+
+## Capabilities
+
+| Mode | Trigger | What It Does |
+|------|---------|-------------|
+| **Onboarding** | First-time user (no profile.json) | Diagnostic, profiling, CC 101, first win, skill map, unlock guide |
+| **Recommendation** | "Which skill for X?" | Scan loaded skill descriptions, rank matches, explain WHY |
+| **Troubleshooting** | "X not working" | Run diagnostic, decision tree, escalation path |
+| **API Key Setup** | "Set up API keys" | Read prerequisites.yaml, guide step-by-step by level |
+| **Update Guidance** | "Update skills" | CLI commands for update, list, install new |
+| **System Info** | General questions | Explain how skills work, architecture, concepts |
+
+### Paradigm: LLM-Native Recommendations
+
+Claude Code auto-loads ALL installed skill names and descriptions into every session context. You already know what every skill does. No catalog file or recommendation script needed. You ARE the recommendation engine. The only hardcoded data is `references/prerequisites.yaml` (API key requirements cannot be inferred from descriptions).
+
+---
+
+## Intent Detection Protocol
+
+Think step by step. Before responding, determine the user's mode.
+
+### Step 1: Check State Files
+
+```bash
+ls ~/.claude/skills/pushrec-skills/state/profile.json 2>/dev/null
+ls ~/.claude/skills/pushrec-skills/state/progress.json 2>/dev/null
+```
+
+### Step 2: Route Based on State + Input
+
+| State | User Signal | Route To |
+|-------|-------------|----------|
+| No profile.json | Any | First-Time Onboarding |
+| Profile exists, onboarding incomplete | Any | Resume Onboarding (pick up where they left off) |
+| Profile exists | "X not working", error messages | Troubleshooting Protocol |
+| Profile exists | "update", "new skills" | Update Guidance |
+| Profile exists | "API key", "set up Google", credential terms | API Key Setup |
+| Profile exists | Skill-related question | Recommendation Protocol |
+| Profile exists | General system question | System Info (explain concepts) |
+| Any | "reset", "start over" | Delete state/ directory, restart onboarding |
+| Ambiguous | Cannot determine intent | Ask ONE clarifying question |
+
+---
+
+## First-Time Onboarding
+
+Six phases, executed sequentially. Track progress in `state/progress.json`.
+
+### Phase 0: Diagnostic
+
+Run the system readiness check:
+
+```bash
+python3 ~/.claude/skills/pushrec-skills/scripts/diagnostic.py
+```
+
+Parse the JSON output. Present results as a checklist:
+- PASS items: brief confirmation
+- FAIL items (exit code 1): STOP. Guide the user to fix critical prerequisites before continuing.
+- WARN items (exit code 2): note but continue
+
+If Claude Code, Node.js, or npm are missing, provide platform-specific install instructions and STOP. Do not proceed with onboarding until critical prerequisites pass.
+
+Write `state/progress.json` with `diagnostic: {status: "completed"}`.
+
+### Phase 1: Adaptive Profiling
+
+Gather business context to personalize skill recommendations. Use conversational questions, not a rigid form. Write answers to `state/profile.json`.
+
+**Round 1 (always ask -- 3 questions):**
+1. What type of business do you run? (agency, coaching, SaaS, e-commerce, freelance, creator, other)
+2. What is your primary content platform? (LinkedIn, X/Twitter, YouTube, Instagram, email, podcast, blog, other)
+3. What is your biggest challenge right now? (not enough content, low engagement, no leads, poor conversion, time management, scaling, other)
+
+**Round 2 (ask if user seems engaged and responsive -- 3 questions):**
+4. Who is your target audience? (open text)
+5. What is your approximate monthly revenue range? (pre-revenue, <$10K, $10-50K, $50-100K, $100K+)
+6. How much experience do you have with AI tools? (never used, tried a few times, use weekly, use daily)
+
+**Round 3 (ask if terminal comfort or CC experience is NOT obvious from prior answers -- 2 questions):**
+7. How comfortable are you with the terminal/command line? (never used, basic, comfortable, advanced)
+8. How much experience do you have with Claude Code specifically? (never, barely, sometimes, regularly, daily)
+
+**Adaptive rules:**
+- If the user gives short or impatient answers, skip remaining rounds
+- If diagnostic shows many installed skills and API keys, skip Round 3 (infer advanced user)
+- Write profile.json after each round completes (progressive save)
+
+**profile.json schema:** `{"version":"1.0.0", "created_at":"ISO", "business_type":"agency", "content_platform":"linkedin", "biggest_challenge":"not-enough-content", "target_audience":"B2B SaaS founders", "revenue_range":"$50-100K", "ai_experience":"use-daily", "terminal_comfort":"comfortable", "cc_experience":"barely"}`
+
+Write `progress.json` with `profiling: {status: "completed"}`.
+
+### Phase 2: Claude Code 101
+
+**Conditional:** Skip if `cc_experience` is "regularly" or "daily". Mark as `skipped` with reason in progress.json.
+
+Deliver a 60-second overview covering ONLY these basics:
+- Skills are invoked by typing `/skill-name` (for example, `/hormozi`, `/linkedin-copywriting`)
+- Claude Code already sees all your installed skill descriptions -- just describe what you need and it finds the right skill
+- Skills produce real output: copy, strategies, images, automations
+- You can chain skills together in a single conversation
+
+Do NOT cover: hooks, sub-agents, settings files, MCP servers, teams, or advanced orchestration. Those are Level 5 concepts.
+
+Write `progress.json` with `cc101: {status: "completed"}` or `{status: "skipped", reason: "cc_experience=regularly"}`.
+
+### Phase 3: First Win
+
+This is the most important phase. Generate a real, valuable output using ONE skill.
+
+**Protocol:**
+1. Read `state/profile.json`
+2. Consider ALL loaded skill descriptions in your context
+3. Select the single best Level 0 skill (NO API keys required) that matches their profile
+4. Explain your choice: "Based on your profile -- [business_type] focused on [content_platform] with [biggest_challenge] -- I recommend starting with `/[skill-name]` because [specific reason]."
+5. Generate a custom context prompt they can use with that skill. For example: "Try typing: `/linkedin-copywriting` and then describe your business and target audience."
+6. WAIT for the user to try it and confirm before proceeding. Ask: "Go ahead and try it now. Let me know when you're ready to continue."
+
+**Selection criteria:**
+- Must be Level 0 (no API keys required)
+- Must directly address their biggest_challenge or content_platform
+- Prefer specific skills over general ones (e.g., `/linkedin-copywriting` over `/copywriting` for LinkedIn users)
+- Never fabricate skill names -- only recommend skills that exist in your loaded context
+
+Write `progress.json` with `first_win: {status: "completed", skill_recommended: "skill-name"}`.
+
+### Phase 4: Skill Map
+
+Present a personalized overview of available skills organized by level. Show only levels relevant to their profile.
+
+**Structure:**
+- **Level 0 -- Foundation (available now):** Group by category relevant to their profile. Highlight 5-8 most relevant skills with one-line descriptions. Mention total count (80+ skills).
+- **Level 1 -- Google Workspace:** List capabilities unlocked (Gmail, Sheets, Docs, Calendar, Drive, Contacts, Slides). Note: "~15 minutes one-time setup."
+- **Level 2 -- Creative and Data:** List key capabilities (AI image generation, voice synthesis, vision analysis, CRM). Note per-service setup time.
+- **Level 3 -- Communication:** List capabilities (SMS, AI phone agents, web scraping). Note KYC requirements.
+- **Level 4 -- Knowledge Management:** Mention Obsidian vault integration. Only highlight if user shows interest in knowledge management.
+- **Level 5 -- Advanced:** Custom agents, multi-skill workflows, hook automation, custom skill creation. Mention for power users only.
+
+Write `progress.json` with `skill_map: {status: "completed"}`.
+
+### Phase 5: Progressive Unlock
+
+Recommend the NEXT level to unlock based on their profile. One level only -- do not overwhelm.
+
+**Selection logic:**
+- If they work with Google Workspace tools: recommend Level 1
+- If they create visual content: recommend Level 2 (fal-ai, gemini-vision)
+- If they need outreach automation: recommend Level 3 (twilio)
+- Default: recommend Level 1 (broadest utility)
+
+Provide the specific setup steps for that one level. Reference `/pushrec-skills` for future API key setup help.
+
+Write `progress.json` with `unlock_guide: {status: "completed"}` and `completed_at: ISO-8601`.
+
+**progress.json schema:** `{"version":"1.0.0", "started_at":"ISO", "completed_at":null, "phases":{"diagnostic":{"status":"completed"}, "profiling":{"status":"completed"}, "cc101":{"status":"skipped","reason":"cc_experience=regularly"}, "first_win":{"status":"completed","skill_recommended":"linkedin-copywriting"}, "skill_map":{"status":"completed"}, "unlock_guide":{"status":"completed"}}, "current_level":"L0", "skills_invoked":["linkedin-copywriting"], "api_keys_configured":[], "last_session_at":"ISO"}`
+
+---
+
+## Returning User Flow
+
+If `state/profile.json` exists and `state/progress.json` shows incomplete onboarding:
+1. Read progress.json to find the last completed phase
+2. Greet: "Welcome back. You left off at [phase]. Ready to continue?"
+3. Resume from the next incomplete phase
+
+If onboarding is complete, route based on their input signal (see Intent Detection).
+
+If the user returns after a long gap (check `last_session_at`), offer a brief refresher:
+- "It has been a while. Want a quick recap of your skill map, or do you have a specific question?"
+
+Update `last_session_at` in progress.json at every session.
+
+---
+
+## Recommendation Protocol
+
+When a user asks "which skill should I use for X?" or describes a need:
+
+1. **Parse the request** into: domain (marketing, sales, content, automation, research), platform (LinkedIn, YouTube, email), and output type (copy, strategy, image, automation)
+2. **Scan ALL skill descriptions** loaded in your context. You already have them -- do not read registry.json or any catalog file.
+3. **Select top 1-3 matches.** For each match, provide:
+   - Skill name (invocable as `/name`)
+   - WHY it matches their request (one sentence)
+   - API key requirement: "No setup needed" (L0) or "Requires [KEY_NAME]" (L1-L4)
+4. **Rank by specificity:** specific skills beat general ones. Single-purpose skills beat orchestrators unless the user explicitly needs a workflow.
+5. **If uncertain,** read the candidate skill's SKILL.md before recommending to verify fit.
+6. **Never fabricate skill names.** Only recommend skills that exist in your loaded context. If no skill matches, say so honestly.
+
+Example: "For LinkedIn carousel posts, I recommend: 1. `/linkedin-copywriting` -- designed for LinkedIn content with proven copywriting psychology. No setup needed. 2. `/copywriting` -- broader foundations that work across platforms. No setup needed."
+
+---
+
+## Troubleshooting Protocol
+
+When a user reports a problem ("X is not working", errors, unexpected behavior):
+
+### Step 1: Gather Information
+
+Ask: Which skill? What command triggered the error? What error message? (Ask them to paste it.)
+
+### Step 2: Run Diagnostic
+
+```bash
+python3 ~/.claude/skills/pushrec-skills/scripts/diagnostic.py
+```
+
+Check for missing prerequisites, missing API keys, or license issues.
+
+### Step 3: Decision Tree
+
+| Symptom | Likely Cause | Fix |
+|---------|-------------|-----|
+| "command not found: claude" | Claude Code not installed | Install from anthropic.com |
+| "command not found: node" | Node.js not installed | Install from nodejs.org (v20+) |
+| "ENOENT" or file not found | Skill not installed | Run `npx @pushrec/skills install --all` |
+| Authentication/401 errors | Missing or expired API key | Guide through API key setup for that skill |
+| "Permission denied" | File permission issue | `chmod +x` the script, or check directory permissions |
+| Skill produces no output | Skill invocation issue | Verify skill name, try `/skill-name` syntax |
+| Import errors in scripts | Missing Python dependencies | Check skill's requirements, run `pip install` or `uv run --with` |
+| License validation fails | License issue | Run `npx @pushrec/skills auth login` to re-authenticate |
+
+### Step 4: Escalation
+
+If the issue cannot be resolved through troubleshooting:
+1. Suggest posting in the community: **skool.com/pushrec-2909**
+2. Include in their post: skill name, error message, diagnostic output, steps already tried
+3. Mention live Q&A sessions in Skool for real-time help
+
+---
+
+## API Key Setup
+
+When a user asks about setting up API keys or unlocking a specific level:
+
+### Step 1: Identify What They Need
+
+Read `references/prerequisites.yaml` to check requirements for the requested skill or level.
+
+### Step 2: Guide by Level
+
+**Level 1 -- Google OAuth2 (one-time, ~15 minutes):**
+1. Go to Google Cloud Console (console.cloud.google.com)
+2. Create a new project (or use existing)
+3. Enable required APIs: Gmail, Sheets, Docs, Calendar, Drive, Contacts, Slides
+4. Create OAuth 2.0 credentials (Desktop app type)
+5. Download the JSON credentials file
+6. Place it in the location specified by each skill (varies per skill -- check prerequisites.yaml)
+7. Run the skill's authenticate.py script to complete the OAuth consent flow
+
+**Level 2 -- Individual API Keys (~2-5 minutes each):**
+Walk through each service's signup:
+- Provide the setup_url from prerequisites.yaml
+- Tell them which env var to set in `~/.claude/.env`
+- Format: `echo 'KEY_NAME=your-key-here' >> ~/.claude/.env`
+
+**Level 3 -- Service Accounts (~10 minutes each):**
+- Note KYC or billing requirements upfront
+- Guide through account creation and credential setup
+- Warn about usage-based billing where applicable
+
+**Level 4 -- Obsidian:**
+- Download from obsidian.md (free)
+- Create or open a vault
+- Run `/vault-manager` for guided vault setup
+
+After setup, update `progress.json` with new entries in `api_keys_configured`.
+
+---
+
+## Update Guidance
+
+When a user asks about updating skills or finding new ones:
+
+### Update Existing Skills
+```bash
+npx @pushrec/skills update          # Update all installed skills
+npx @pushrec/skills update [name]   # Update a specific skill
+```
+
+### Install New Skills
+```bash
+npx @pushrec/skills install --all   # Install any skills added since last install
+npx @pushrec/skills list            # See all available vs. installed
+```
+
+### Check System Health
+```bash
+python3 ~/.claude/skills/pushrec-skills/scripts/diagnostic.py
+```
+
+Note: `install --all` skips already-installed skills (no duplicates). Running it again after new skills are published picks up the new ones automatically. The `update` command handles version bumps for already-installed skills.
+
+---
+
+## Anti-Patterns
+
+| Anti-Pattern | Correct Behavior |
+|-------------|-----------------|
+| Recommending skills not in loaded context | Only recommend skills you can see in the system context |
+| Hardcoding skill-to-profile mappings | Read profile + scan descriptions dynamically every time |
+| Dumping the full skill catalog | Show only relevant skills, grouped by the user's needs |
+| Skipping the diagnostic on first run | Always run diagnostic.py in Phase 0 |
+| Proceeding after critical failures | STOP and help fix prerequisites before continuing |
+| Recommending L1+ skills without mentioning API key requirements | Always state the setup requirement alongside the recommendation |
+
+### Verification Checklist
+
+Before finishing any response, verify:
+- Think step by step: Did I follow the correct protocol for this mode?
+- Before you finish: Are all skill names I mentioned real skills in my loaded context?
+- If you don't know: Am I certain about API key requirements, or should I check prerequisites.yaml?
+- Did I update state files (profile.json, progress.json) if the user completed a phase?
+- Did I provide clear next steps the user can act on?
+
+---
+
+## Quick Reference
+
+| Need | Command or Action |
+|------|-------------------|
+| Start onboarding | Type `/pushrec-skills` |
+| Find a skill | Describe what you need -- the LLM matches automatically |
+| Set up API keys | Type `/pushrec-skills` and ask about API key setup |
+| Update skills | `npx @pushrec/skills update` |
+| Install new skills | `npx @pushrec/skills install --all` |
+| List all skills | `npx @pushrec/skills list` |
+| Get help | Post in skool.com/pushrec-2909 |
+| Reset onboarding | Type `/pushrec-skills` and say "reset" |
+
+### Prerequisites
+
+- **Claude Code subscription:** Pro ($20/mo) or Max ($100/mo) from anthropic.com
+- **Node.js:** v20 or higher (nodejs.org)
+- **npm:** included with Node.js
+
+### State Files
+
+| File | Purpose |
+|------|---------|
+| `state/profile.json` | Business profile from adaptive profiling |
+| `state/progress.json` | Completed phases, unlocked levels, skills invoked |
+
+### Community
+
+- **Skool:** skool.com/pushrec-2909
+- **Live Q&A:** check Skool for scheduled sessions