{
  "markdown": "# q-skills\n\nEnd-to-end skills for academic writing, data analysis, teaching, and research communication.\n\n## Prerequisites\n\n- [Claude Code](https://claude.ai/code) or compatible AI coding assistant\n- Python 3.8+ (for script-based skills)\n- pandas, openpyxl (for data processing skills)\n- [Node.js](https://nodejs.org/) (for `npx`-based installation)\n\n## Installation\n\nChoose **one** of the methods below.\n\n| Method | Best for |\n| ------ | -------- |\n| [Ask the Agent](#option-1-ask-the-agent-beginner-friendly) | **No coding experience needed** — just talk to Claude |\n| [Quick Install](#option-2-quick-install) | Command-line users — installs all skills at once |\n| [Plugin Marketplace](#option-3-plugin-marketplace) | Register once, then install all or specific skills |\n| [Manual](#option-4-manual-clone-and-copy) | Offline or restricted environments |\n\n---\n\n### Option 1: Ask the Agent (Beginner-Friendly)\n\n> **No coding experience required.** If you are new to Claude Code or not comfortable with the command line, this is the easiest way to get started. Just open Claude Code and type:\n\n```\nPlease install skills from github.com/TyrealQ/q-skills\n```\n\nClaude will handle the installation for you — no terminal, no commands.\n\n---\n\n### Option 2: Quick Install\n\nRequires [Node.js](https://nodejs.org/) for `npx`:\n\n```bash\nnpx skills add TyrealQ/q-skills\n```\n\n---\n\n### Option 3: Plugin Marketplace\n\nRegister q-skills as a plugin source in Claude Code, then install all or selected skills.\n\n**Step 1 — Register** (run once inside Claude Code):\n\n```\n/plugin marketplace add TyrealQ/q-skills\n```\n\n**Step 2 — Install:**\n\n```\n/plugin install q-skills@q-skills\n```\n\n> **Migrating from older installs?** If you previously installed `academic-skills@q-skills`, `visual-content-skills@q-skills`, or `utility-skills@q-skills`, uninstall them first, then install the unified `q-skills@q-skills` plugin above.\n\n---\n\n### Option 4: Manual (Clone and Copy)\n\n```bash\ngit clone https://github.com/TyrealQ/q-skills.git\n```\n\n**Windows (PowerShell):**\n\n```powershell\nCopy-Item -Recurse -Force q-skills\\skills\\* $env:USERPROFILE\\.claude\\skills\\\n```\n\n**macOS/Linux:**\n\n```bash\ncp -r q-skills/skills/* ~/.claude/skills/\n```\n\n> **Note:** The exact skills path depends on your AI assistant. Common locations: `~/.claude/skills/`, `~/.gemini/skills/`\n\n## Update Skills\n\n### Via Plugin UI (Recommended)\n\n1. Run `/plugin` in Claude Code\n2. Switch to the **Marketplaces** tab (arrow keys or Tab)\n3. Select **q-skills**\n4. Choose **Update marketplace**\n\nYou can also enable **auto-update** to receive the latest versions automatically.\n\n### Force Reinstall\n\n```bash\nnpx skills add TyrealQ/q-skills --force\n```\n\n### Manual Update\n\n```bash\ncd q-skills\ngit pull\n```\n\nThen re-copy the skills to your skills directory (see Manual install above).\n\n---\n\n## Available Skills\n\n### Academic Skills\n\n| Skill                         | Description                                                                 |\n| ----------------------------- | --------------------------------------------------------------------------- |\n| [q-scholar](#q-scholar)       | Academic manuscript writing suite (exploratory data analysis, intro, literature review, methods, multimodal feature extraction, results, topic modeling) |\n| [q-educator](#q-educator)     | Course content development for lectures, demos, assignments, and feedback   |\n\n### Visual Content Skills\n\n| Skill                               | Description                                              |\n| ----------------------------------- | -------------------------------------------------------- |\n| [q-infographics](#q-infographics)   | Convert documents into business stories and infographics |\n| [q-presentations](#q-presentations) | Convert content into branded slide decks with style presets |\n\n### Utility Skills\n\n| Skill                   | Description                                                              |\n| ----------------------- | ------------------------------------------------------------------------ |\n| [commit](#commit)       | Stage and commit with smart file grouping and conventional commits       |\n| [handoff](#handoff)     | Wrap up a session into plan files, memory, and CLAUDE.md for clean resume |\n| [learn](#learn)         | Persist user preferences and styles across sessions                      |\n| [organize](#organize)   | Audit structure and documentation, align to conventions                  |\n| [ship](#ship)           | Full ship cycle: update docs, commit, and push to remote                 |\n\n---\n\n## Skill Details\n\n### q-scholar\n\nAcademic manuscript writing suite for drafting journal-ready prose following APA 7th edition standards. Orchestrates specialized sub-skills for complete manuscript preparation workflows.\n\n**Sub-Skills:**\n\n| Sub-Skill | Description |\n| --------- | ----------- |\n| q-eda | Universal exploratory data analysis with user-confirmed column types and measurement-appropriate statistics |\n| q-intro | Introduction drafting and refinement with argumentative architecture guidance |\n| q-litreview | Literature review drafting with progressive-argument architecture and cross-section coordination |\n| q-methods | Methods section drafting in clear, narrative style |\n| q-multimodal | Multimodal feature extraction: pixel/video/audio features and Gemini visual semantic analysis |\n| q-results | Results section drafting with APA-compliant tables |\n| q-tf | Topic finetuning to consolidate topic modeling outputs (BERTopic, LDA, NMF) into theory-driven classification frameworks |\n\n**Triggers:**\n\n- \"Help me write the methods and results for my study\"\n- \"Draft a results section for this analysis\"\n- \"Analyze this dataset and generate descriptive statistics\"\n\n**Features:**\n\n- End-to-end manuscript support (exploratory data analysis -> methods -> results)\n- APA 7th edition formatting (tables, statistics, notation)\n- Narrative prose style (no bullet points or em-dashes)\n- Shared style guides and templates\n- Appendix strategies for technical details\n\n**Folder Structure:**\n\n```text\nq-scholar/\n|-- SKILL.md                              # Orchestration skill\n|-- references/                           # Shared style guides\n|   |-- apa_style_guide.md                # Numbers, statistics, notation, formulas\n|   |-- table_formatting.md               # APA 7th table examples\n|   `-- appendix_template.md              # Shared appendix structure (methods + results)\n|-- q-eda/\n|   |-- SKILL.md                          # Data exploration skill\n|   |-- scripts/                          # run_eda.py\n|   `-- references/                       # Interview protocol, invocation guide, summary template + instructions\n|-- q-intro/\n|   |-- SKILL.md                          # Introduction drafting skill\n|   `-- references/                       # Template and interview questions\n|-- q-litreview/\n|   |-- SKILL.md                          # Literature review drafting skill\n|   `-- references/                       # Template and interview questions\n|-- q-methods/\n|   |-- SKILL.md                          # Methods drafting skill\n|   `-- references/                       # Methods template\n|-- q-multimodal/\n|   |-- SKILL.md                          # Multimodal feature extraction skill\n|   |-- scripts/                          # pillow/, opensmile/, librosa/, gemini/ (batch + standard)\n|   `-- references/                       # Feature definitions, Gemini workflows, checkpoint format\n|-- q-results/\n|   |-- SKILL.md                          # Results drafting skill\n|   `-- references/                       # Results template\n`-- q-tf/\n    |-- SKILL.md                          # Topic finetuning skill\n    |-- scripts/                          # classify_outliers.py, plan & Excel updaters\n    `-- references/                       # Code patterns, preservation rules, outlier workflow, worked example\n```\n\n**Example:**\n\n```\nHelp me write the methods and results sections for my topic modeling study on esports discourse\n```\n\n---\n\n### q-infographics\n\nConvert documents into compelling business stories and cartoon-style infographics. Image generation defaults to OpenAI GPT Image 2 with a Gemini fallback; story generation uses Gemini.\n\n**Triggers:**\n\n- \"Create an infographic from this document...\"\n- \"Convert this paper to a visual summary...\"\n- \"Generate a business story from...\"\n\n**Features:**\n\n- Two-stage pipeline: Document -> Story -> Infographic\n- Business story style (36Kr/Huxiu format) with \"golden sentences\"\n- Hand-drawn cartoon-style infographics (16:9)\n- Automatic logo branding on generated infographics\n- Review checkpoints at each stage\n- Supports PDF, DOCX, and text input (via markitdown)\n\n**Requirements:**\n\n- `pip install openai google-genai Pillow python-dotenv markitdown`\n- `OPENAI_API_KEY` (for default `gpt-image-2` image generation) and `GEMINI_API_KEY` (for story generation; also for the Gemini image fallback). Select the image backend via `IMAGE_MODEL=gpt|gemini` or `--model gpt|gemini`. See [Environment Configuration](#environment-configuration).\n\n**Folder Structure:**\n\n```text\nq-infographics/\n|-- SKILL.md                              # Main skill file\n|-- assets/\n|   `-- Logo_Q.png                        # Brand logo, auto-overlaid on infographics\n|-- references/\n|   |-- story.txt                         # Story generation prompt\n|   |-- image.txt                         # Infographic generation prompt\n|   `-- prompts_reference.md              # Prompt descriptions and key elements\n|-- scripts/\n|   |-- gen_story.py                      # Story generator script\n|   `-- gen_image.py                      # Image generator script\n# Sample outputs → see illustrations/q-infographics/ at repo root\n```\n\n**Example:**\n\n```\nCreate an infographic from my research paper on gamification in esports\n```\n\n**Sample Outputs:**\n\n![DIGITAL_ENTREPRENEURSHIP_INFO1](illustrations/q-infographics/DIGITAL_ENTREPRENEURSHIP_INFO1.png)\n\n![DIGITAL_ENTREPRENEURSHIP_INFO2](illustrations/q-infographics/DIGITAL_ENTREPRENEURSHIP_INFO2.png)\n\n---\n\n### q-presentations\n\nConvert content into branded slide decks with 16 visual style presets, layout-driven overlay safety, and automatic logo branding. Fork of [baoyu-slide-deck](https://github.com/JimLiu/baoyu-skills) with video-overlay-aware layout.\n\n**Triggers:**\n\n- \"Create a slide deck from this content...\"\n- \"Make a presentation about...\"\n- \"Generate slides for my talk...\"\n\n**Features:**\n\n- 16 style presets (blueprint, chalkboard, corporate, minimal, sketch-notes, watercolor, etc.)\n- Composable dimension system (texture + mood + typography + density)\n- Video-overlay-aware layout: internal layout-driven overlay-safe selection\n- Automatic Dr. Q logo branding with configurable placement and auto-invert for dark styles\n- Image generation via OpenAI GPT Image 2 by default, with Gemini (`gemini-3-pro-image-preview`) available as a fallback\n- PPTX and PDF export\n- Partial workflows (outline-only, prompts-only, regenerate specific slides)\n\n**Requirements:**\n\n- `pip install openai google-genai Pillow python-dotenv`\n- `OPENAI_API_KEY` (for default `gpt-image-2`) or `GEMINI_API_KEY` (when `IMAGE_MODEL=gemini` / `--model gemini`)\n- Bun available for PPTX/PDF merge scripts (`npx -y bun ...`)\n\n**Folder Structure:**\n\n```text\nq-presentations/\n|-- SKILL.md                              # Main skill file\n|-- assets/\n|   `-- Logo_Q.png                        # Brand logo, auto-overlaid on slides\n|-- references/\n|   |-- base-prompt.md                    # Image generation base prompt\n|   |-- design-guidelines.md              # Typography, colors, visual hierarchy\n|   |-- layouts.md                        # 28 layout types\n|   |-- outline-template.md               # Outline structure template\n|   |-- config/preferences-schema.md      # EXTEND.md user preferences\n|   |-- dimensions/                       # Composable style dimensions (5 files)\n|   `-- styles/                           # 22 style definitions\n`-- scripts/\n    |-- gen_slide.py                      # Image generation (GPT Image 2 default; Gemini via --model gemini)\n    |-- overlay_logo.py                   # Logo overlay with auto-invert\n    |-- merge-to-pptx.ts                  # PPTX merge (Bun/TS)\n    `-- merge-to-pdf.ts                   # PDF merge (Bun/TS)\n# Sample outputs → see illustrations/q-presentations/ at repo root\n```\n\n**Example:**\n\n```\nCreate a chalkboard-style slide deck from my research paper on AI agents\n```\n\n**Sample Outputs:**\n\n![01-slide-cover](illustrations/q-presentations/01-slide-cover.png)\n\n![02-slide-authenticity-trap](illustrations/q-presentations/02-slide-authenticity-trap.png)\n\n![03-slide-two-playbooks](illustrations/q-presentations/03-slide-two-playbooks.png)\n\n---\n\n### q-educator\n\nCourse content development skill for university teaching workflows. Produces interview-driven lecture outlines, demo plans, follow-up emails, assignment prompts, and per-group feedback.\n\n**Triggers:**\n\n- \"Help me design next week's lecture...\"\n- \"Draft an assignment prompt for this module...\"\n- \"Write feedback for each student group...\"\n\n**Features:**\n\n- Interview-first planning workflow before drafting\n- Projects-first teaching philosophy with domain-specific analogies\n- Structured deliverables for lecture, demo, email, assignment, and feedback\n- Iterative review checkpoints after each deliverable\n- Reference examples for assignments, lectures, emails, demos, and feedback\n\n**Folder Structure:**\n\n```text\nq-educator/\n|-- SKILL.md\n`-- references/\n    |-- teaching_philosophy.md            # Six governing principles\n    |-- interview_protocol.md             # Six-question interview sequence\n    |-- lecture_template.md               # Lecture outline structure + design rules\n    |-- demo_template.md                  # Demo outline structure + design rules\n    |-- email_guidelines.md               # Follow-up email style rules\n    |-- assignment_template.md            # Assignment prompt structure + design rules\n    |-- feedback_template.md              # Per-group feedback structure + design rules\n    |-- key_phrases.md                    # Philosophy catchphrases\n    |-- lecture_example.md                # Example lecture outline\n    |-- demo_example.md                   # Example demo outline\n    |-- email_example.md                  # Example follow-up email\n    |-- assignment_example.md             # Example assignment prompt\n    `-- feedback_example.md               # Example per-group feedback\n```\n\n**Example:**\n\n```\nHelp me build a week 6 lecture + demo + assignment plan for a graduate analytics course\n```\n\n---\n\n### commit\n\nStage and commit all uncommitted changes with smart file grouping and conventional commit messages. Analyzes changed files, groups by topic (content, skills, code, config), and generates descriptive commit messages.\n\n**Triggers:**\n\n- `/commit`\n- \"Commit my changes\"\n\n**Features:**\n\n- Automatic file classification by path pattern\n- Smart grouping: one commit per topic when changes span multiple areas\n- Conventional commit format (`feat:`, `fix:`, `docs:`, etc.)\n- Explicit file staging (never `git add .`)\n- Auto-cleanup of editor/build temp files after each commit\n\n---\n\n### handoff\n\nCapture the load-bearing outcomes of a session, route them to the right durable location (plan file, auto-memory, project CLAUDE.md, user CLAUDE.md), and produce a copy-pasteable resume prompt for a fresh session. Use before `/compact` or at the end of a working session.\n\n**Triggers:**\n\n- `/handoff`\n- \"Hand off this session\" / \"Wrap up\"\n- \"Update docs for next session\"\n- Before running `/compact`\n\n**Features:**\n\n- Four-step workflow: survey the session → locate destinations → apply updates → produce resume prompt\n- Destination routing table that places each outcome (decisions, conventions, lessons, banned terms) in its single durable home, never duplicated\n- Self-contained resume prompt under ~250 words with required sections (Context, Read first, Where we left off, Conventions to honor, Next task, Known gotchas)\n- Anti-patterns guardrail: no session logs in project files, no new doc locations without asking, no extracting unvalidated lessons\n\n---\n\n### learn\n\nPersist user preferences, styles, and behavioral patterns to `~/CLAUDE.md`, `~/.claude/rules/`, or project memory. Extracts corrections, explicit rules, and positive reinforcement from the current conversation, and answers read-only queries about what has already been remembered.\n\n**Triggers:**\n\n- `/learn`\n- \"Remember this preference\" / \"Save this to CLAUDE.md\" / \"Update CM\"\n- \"Always do X\" / \"Never do Y\" / \"From now on…\"\n- \"Forget X\" / \"What do you remember about me?\"\n\n**Features:**\n\n- Three-tier persistence: user instructions, user rules, project memory\n- Inline trigger taxonomy (explicit rules, corrections, positive reinforcement, domain context, style edits)\n- Repetition threshold: single off-hand corrections stay tentative until repeated\n- Conflict detection: contradicting preferences surface side-by-side for explicit approval\n- Query mode: read-only lookup, section-level quoting, and confirmed forgetting\n- Anti-patterns guardrail: never infers from silence, hypotheticals, or third-party preferences\n- Keeps `~/CLAUDE.md` under 200 lines, migrating overflow to rule files\n\n---\n\n### organize\n\nAudit a project's layout and its project documentation (READMEs, `CLAUDE.md`, `AGENTS.md`, indexes) against one set of conventions. Works on any project type (research, content, software, data). Writes a plan file, asks on ambiguous calls, applies approved groups, and hands off to `/commit` or `/ship`.\n\n**Triggers:**\n\n- `/organize`\n- \"Clean up this repo\"\n- \"Standardize folder structure\"\n- \"Fix stale docs\"\n- \"Streamline the READMEs\"\n\n**Features:**\n\n- Nine detectors: name drift, superseded generations, orphan files, tracked per-machine state, stale facts, history clauses, duplication, document structure, and prose\n- Conventions reference: snake_case names with acronym capitals and owner files in capitals, dated `YYYY-MM-DD_slug` items, a root map with one README per folder, five document types, and documentation that states the current state only\n- Superseded content split by tracking: tracked files are deleted and left to git history; untracked files move to `_archive/`\n- Plan-first workflow with approval by group, where a rule written in the project's docs takes precedence over the conventions, and an `audit` argument that stops at the plan; project documentation only, never deliverable prose\n- Sync-safe moves for cloud-synced paths; never commits directly\n\n---\n\n### ship\n\nFull ship cycle: update documentation, stage, commit, and push to remote. Automatically updates CHANGELOG.md, CLAUDE.md, and READMEs affected by the current changes.\n\n**Triggers:**\n\n- `/ship`\n- \"Ship my changes\"\n\n**Features:**\n\n- Auto-updates CHANGELOG.md, CLAUDE.md, and relevant READMEs\n- Stale reference detection for deleted/renamed files\n- Smart commit grouping (same as commit skill)\n- Pushes to remote with upstream tracking\n- Auto-cleanup of editor/build temp files after push\n\n---\n\n## Environment Configuration\n\nSome skills need API keys:\n\n- **OpenAI** (`OPENAI_API_KEY`) — default image generation backend (`gpt-image-2`) used by `q-presentations` and `q-infographics`.\n- **Google Gemini** (`GEMINI_API_KEY`) — story generation in `q-infographics`, topic classification in `q-tf`, multimodal analysis in `q-multimodal`, and the image-generation fallback (`gemini-3-pro-image-preview`) when `IMAGE_MODEL=gemini` or `--model gemini`.\n\n### Getting Your API Keys\n\n- OpenAI: [platform.openai.com/api-keys](https://platform.openai.com/api-keys)\n- Google Gemini: [Google AI Studio](https://aistudio.google.com/apikey)\n\n### Setting the API Keys\n\nCreate a `.env` file in your project's working directory:\n\n```\nOPENAI_API_KEY=your-openai-key-here\nGEMINI_API_KEY=your-gemini-key-here\n```\n\n> **Important:** Add `.env` to your `.gitignore` so you don't accidentally commit your key:\n> ```bash\n> echo \".env\" >> .gitignore\n> ```\n\nAll skills that use the Gemini API load this file automatically via `python-dotenv`. Alternatively, set the variable directly in your terminal:\n\n**macOS / Linux:**\n```bash\nexport GEMINI_API_KEY=your-api-key-here\n```\n\n**Windows (PowerShell):**\n```powershell\n$env:GEMINI_API_KEY = \"your-api-key-here\"\n```\n\n**Windows (Command Prompt):**\n```cmd\nset GEMINI_API_KEY=your-api-key-here\n```\n\nTo make it permanent, add the export line to your shell profile (`~/.bashrc`, `~/.zshrc`) or set it as a system environment variable on Windows.\n\n### Optional Variables\n\n| Variable | Purpose | Default |\n| -------- | ------- | ------- |\n| `IMAGE_MODEL` | Image backend for q-presentations / q-infographics (`gpt` or `gemini`) | `gpt` |\n| `GEMINI_MODEL` | Override the model used by q-tf | `gemini-3-flash-preview` |\n\n---\n\n## Acknowledgments\n\n- Inspired by [baoyu-skills](https://github.com/JimLiu/baoyu-skills) by Jim Liu\n- Built for use with Claude Code and compatible AI assistants\n\n## License\n\nMIT License - see [LICENSE](LICENSE) for details.\n\n## Contributing\n\nContributions welcome! Please submit issues or pull requests.\n\n",
  "bytes": 21116,
  "sha": "a62411a5a4fee10eb23c5cec9c0831448673d3f7473eabc321ba29800380072a",
  "repo_slug": "tyrealq/q-skills",
  "fonte": "repo",
  "truncated": false,
  "api": "https://api.agentalog.com/api/listings/skl_tyrealq_q_skills_q_scholar_200b3574/readme"
}