gin-skills 1.0.0

package/DEVELOPMENT.md

@@ -0,0 +1,510 @@
+# GinStudio Skills — Development Guide
+
+Everything you need to contribute skills, release new versions, and manage the CLI.
+
+---
+
+## Table of Contents
+
+1. [Project Structure](#project-structure)
+2. [How to Add a New Skill](#how-to-add-a-new-skill)
+3. [How to Add a New Agent](#how-to-add-a-new-agent)
+4. [How to Release (Publish to npm)](#how-to-release-publish-to-npm)
+5. [CLI Reference](#cli-reference)
+6. [How Users Install Skills](#how-users-install-skills)
+7. [How to Upgrade Installed Skills](#how-to-upgrade-installed-skills)
+8. [How to Uninstall](#how-to-uninstall)
+9. [Local Development & Testing](#local-development--testing)
+10. [Troubleshooting](#troubleshooting)
+
+---
+
+## Project Structure
+
+```
+ginstudio-skills/
+├── bin/
+│   └── cli.js              # npm CLI entrypoint (gin-skills)
+├── skills/
+│   └── my-skill/           # One directory per skill
+│       ├── SKILL.md        # Main skill file (required)
+│       ├── docs/           # Supporting docs loaded at runtime
+│       └── scripts/        # Shell scripts used by the skill
+├── agents/
+│   ├── my-agent.md         # Single-file agent (simple)
+│   └── my-agent/           # Directory agent (with supporting files)
+│       └── agent.md
+├── package.json            # npm package config
+├── .npmignore              # Files excluded from npm publish
+├── .gitignore
+├── README.md
+└── DEVELOPMENT.md          # This file
+```
+
+---
+
+## How to Add a New Skill
+
+### 1. Create the skill directory
+
+```bash
+mkdir -p skills/my-skill/docs
+mkdir -p skills/my-skill/scripts
+```
+
+### 2. Write `SKILL.md` (required)
+
+Every skill needs a `SKILL.md` at `skills/my-skill/SKILL.md`.
+
+**Minimal template:**
+
+```markdown
+---
+name: my-skill
+description: |
+  Short description visible to Claude when deciding to load this skill.
+  - MANDATORY TRIGGERS: keyword1, keyword2, keyword3
+  - Use this skill when the user wants to: do X, Y, Z
+argument-hint: "[optional | args | here]"
+disable-model-invocation: false
+---
+
+# My Skill Title
+
+You are an expert in [domain]. Help the user [goal].
+
+## Step 1 — Do Something
+
+...instructions...
+
+## Step 2 — Do Something Else
+
+...
+```
+
+**SKILL.md frontmatter fields:**
+
+| Field | Required | Description |
+|-------|----------|-------------|
+| `name` | yes | Identifier, must match the directory name |
+| `description` | yes | Shown to Claude; include `MANDATORY TRIGGERS` keywords |
+| `argument-hint` | no | Shown in `/skill-name [hint]` |
+| `disable-model-invocation` | no | Set `true` to block Claude from calling models inside the skill |
+| `user-invocable` | no | Set `false` for domain-knowledge skills that auto-load but aren't called directly |
+
+**Rules:**
+- Keep `SKILL.md` under **500 lines**. Move excess content to `docs/`.
+- Put reusable deep-dives in `docs/*.md` and load them via a script or inline reference.
+- Scripts go in `scripts/` and are invoked with `` !`bash skills/my-skill/scripts/my-script.sh $ARGUMENTS` ``.
+
+### 3. Load docs dynamically (optional)
+
+Create `scripts/load-tutorial.sh` if your skill routes to different docs based on arguments:
+
+```bash
+#!/bin/bash
+TOPIC="${1:-overview}"
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+DOCS_DIR="$SCRIPT_DIR/../docs"
+
+case "$TOPIC" in
+  intro)   cat "$DOCS_DIR/intro.md" ;;
+  advanced) cat "$DOCS_DIR/advanced.md" ;;
+  *)       cat "$DOCS_DIR/overview.md" ;;
+esac
+```
+
+Then in `SKILL.md`:
+
+```markdown
+!`bash skills/my-skill/scripts/load-tutorial.sh $ARGUMENTS`
+```
+
+### 4. Register the skill's auto-triggers
+
+The `description` field in the frontmatter is used by Claude to decide when to auto-load the skill. Include:
+
+```yaml
+description: |
+  Brief one-liner.
+  - MANDATORY TRIGGERS: the exact words or phrases that should trigger it
+  - Use this skill when the user wants to: create X, build Y, fix Z
+```
+
+### 5. Test the skill locally
+
+```bash
+# Install from local repo to a test .claude directory
+node bin/cli.js --skills my-skill -t /tmp/test-project
+
+# Verify it's there
+ls /tmp/test-project/.claude/skills/my-skill/
+
+# In Claude Code, invoke directly
+/my-skill
+# Or let it auto-trigger by describing your goal
+```
+
+---
+
+## How to Add a New Agent
+
+Agents live in `agents/` and are copied to `.claude/agents/` during install.
+
+### Simple agent (single `.md` file)
+
+Create `agents/my-agent.md`:
+
+```markdown
+---
+name: my-agent
+description: Use this agent to do X. TRIGGER when user asks about Y.
+tools: Read, Grep, Glob, Bash
+model: claude-haiku-4-5-20251001
+---
+
+You are a specialized agent for [domain].
+
+## Capabilities
+...
+
+## Instructions
+...
+```
+
+### Directory agent (with supporting files)
+
+Create `agents/my-agent/` directory with an `agent.md` (or any `.md`) and supporting scripts/configs.
+
+### Agent frontmatter fields
+
+| Field | Description |
+|-------|-------------|
+| `name` | Agent identifier |
+| `description` | When to invoke; visible in `/agents` list |
+| `tools` | Comma-separated tool allowlist (restricts what the agent can call) |
+| `model` | Override the model (e.g., `claude-haiku-4-5-20251001` for speed) |
+
+### Test the agent
+
+```bash
+node bin/cli.js --agents my-agent -t /tmp/test-project
+# In Claude Code: "Use the my-agent agent to [task]"
+# Or: /agents  to verify it appears
+```
+
+---
+
+## How to Release (Publish to npm)
+
+### Prerequisites
+
+- npm account with access to the `gin-skills` package
+- `npm login` completed
+
+### Step 1 — Bump the version
+
+```bash
+# patch: 1.0.0 → 1.0.1  (bug fixes, content updates)
+npm version patch
+
+# minor: 1.0.0 → 1.1.0  (new skills/agents added)
+npm version minor
+
+# major: 1.0.0 → 2.0.0  (breaking changes to CLI or skill format)
+npm version major
+```
+
+This updates `package.json` and creates a git tag automatically.
+
+### Step 2 — Preview what will be published
+
+```bash
+npm pack --dry-run
+```
+
+Check that:
+- No `node_modules/` is included
+- No `screenshots/`, `evals/`, or large media files
+- All `skills/` and `agents/` directories are present
+- Total size is reasonable (< 2MB target)
+
+### Step 3 — Publish
+
+```bash
+npm publish
+```
+
+For a pre-release (beta):
+
+```bash
+npm version prerelease --preid=beta   # 1.1.0-beta.0
+npm publish --tag beta
+# Users install with: npx gin-skills@beta
+```
+
+### Step 4 — Push the tag
+
+```bash
+git push && git push --tags
+```
+
+### What `.npmignore` excludes
+
+The `.npmignore` file keeps the package small by excluding:
+
+```
+**/screenshots/    # demo images
+**/evals/          # evaluation files
+**/*.mov, *.mp4    # video files
+node_modules/
+install.py, install.js   # legacy installers
+*.local.json
+**/.env*
+```
+
+To add more exclusions, edit `.npmignore`. **Do not add a `files` field to `package.json`** — it overrides `.npmignore` and can accidentally include everything.
+
+---
+
+## CLI Reference
+
+```
+gin-skills [command] [options]
+```
+
+### Default: `install`
+
+```bash
+gin-skills                           # Interactive TUI — select skills/agents
+gin-skills --all                     # Install everything, no prompts
+gin-skills --skills react-query,mongodb
+gin-skills --agents developer,tester
+gin-skills -g                        # Install to ~/.claude (global)
+gin-skills -t /path/to/project       # Install to specific project
+```
+
+### `upgrade`
+
+Re-copies installed skills/agents from the bundled version.
+
+```bash
+gin-skills upgrade                   # Interactive — choose what to upgrade
+gin-skills upgrade --all             # Upgrade everything
+gin-skills upgrade -t /path/to/project
+gin-skills upgrade -g
+```
+
+### `uninstall` (alias: `remove`)
+
+Removes installed skills/agents from the target `.claude/` directory.
+
+```bash
+gin-skills uninstall                 # Interactive — choose what to remove
+gin-skills uninstall -t /path/to/project
+gin-skills uninstall -g
+```
+
+### `status` (alias: `info`)
+
+Shows which skills/agents are installed vs available.
+
+```bash
+gin-skills status
+gin-skills status -t /path/to/project
+gin-skills status -g
+```
+
+### `list` (alias: `ls`)
+
+Lists all skills and agents bundled in this package (not what's installed).
+
+```bash
+gin-skills list
+```
+
+### `versions` (alias: `ver`)
+
+Fetches all published versions from the npm registry.
+
+```bash
+gin-skills versions
+```
+
+### Global flags (work on all commands)
+
+| Flag | Short | Description |
+|------|-------|-------------|
+| `--global` | `-g` | Target `~/.claude/` (available in all projects) |
+| `--target <path>` | `-t` | Target a specific project directory |
+| `--version` | `-V` | Print CLI version |
+| `--help` | `-h` | Print help |
+
+---
+
+## How Users Install Skills
+
+### One-time install (recommended)
+
+```bash
+npx gin-skills
+```
+
+Runs the interactive TUI to select skills and agents.
+
+### Install to a specific project
+
+```bash
+cd /path/to/my-project
+npx gin-skills
+# or
+npx gin-skills -t /path/to/my-project
+```
+
+### Install globally (all projects)
+
+```bash
+npx gin-skills -g
+# or
+npx gin-skills --global
+```
+
+### Non-interactive (CI/scripts)
+
+```bash
+npx gin-skills --all                         # all skills + agents
+npx gin-skills --skills react-query,mongodb  # specific skills only
+npx gin-skills --agents developer            # specific agent only
+npx gin-skills --all -g                      # everything, globally
+```
+
+---
+
+## How to Upgrade Installed Skills
+
+When a new version of `gin-skills` is published, users upgrade their installed skills by running:
+
+```bash
+# Interactive — choose which skills/agents to upgrade
+npx gin-skills@latest upgrade
+
+# Upgrade everything silently
+npx gin-skills@latest upgrade --all
+
+# Upgrade in a specific project
+npx gin-skills@latest upgrade -t /path/to/project
+```
+
+The `upgrade` command re-copies skills/agents from the npm package, overwriting the existing files. Only skills/agents already installed are shown.
+
+---
+
+## How to Uninstall
+
+### Remove specific skills/agents interactively
+
+```bash
+gin-skills uninstall
+# or from any version:
+npx gin-skills uninstall
+```
+
+### Remove from a specific project
+
+```bash
+gin-skills uninstall -t /path/to/project
+```
+
+### Remove globally installed skills
+
+```bash
+gin-skills uninstall -g
+```
+
+### Manual removal
+
+Skills are plain directories — you can also delete them manually:
+
+```bash
+# Remove a specific skill
+rm -rf .claude/skills/my-skill
+
+# Remove a specific agent
+rm .claude/agents/my-agent.md
+# or
+rm -rf .claude/agents/my-agent/
+```
+
+---
+
+## Local Development & Testing
+
+### Setup
+
+```bash
+cd ginstudio-skills
+npm install
+```
+
+### Run CLI locally
+
+```bash
+node bin/cli.js --help
+node bin/cli.js list
+node bin/cli.js status -t /tmp/test
+node bin/cli.js --all -t /tmp/test
+node bin/cli.js upgrade --all -t /tmp/test
+node bin/cli.js uninstall -t /tmp/test
+```
+
+### Link globally for testing
+
+```bash
+npm link
+# Now you can run: gin-skills --help
+npm unlink gin-skills   # when done
+```
+
+### Test pack before publishing
+
+```bash
+npm pack --dry-run         # preview what's included
+npm pack                   # creates gin-skills-x.x.x.tgz
+# Test install from the tgz:
+npx ./gin-skills-x.x.x.tgz
+```
+
+---
+
+## Troubleshooting
+
+### Skills not appearing in Claude Code
+
+Run `/agents` or restart Claude Code after installing. Skills are picked up on session start.
+
+### `npx gin-skills` installs an old version
+
+Force the latest:
+
+```bash
+npx gin-skills@latest
+# or clear npx cache:
+npx --yes gin-skills@latest
+```
+
+### Target not recognized
+
+If `-t /path/to/project` seems to be ignored, make sure you're passing it **after** the command:
+
+```bash
+gin-skills upgrade -t /path/to/project   ✓
+gin-skills -t /path/to/project upgrade   ✗  (flag consumed by parent)
+```
+
+### Package is too large
+
+Check `.npmignore` is present and `package.json` has no `files` field. Run `npm pack --dry-run` to inspect.
+
+### Skill doesn't auto-trigger
+
+Verify the `description` frontmatter in `SKILL.md` includes `MANDATORY TRIGGERS` with the exact words the user would say.

package/README.md

@@ -0,0 +1,103 @@
+# GinStudio Skills
+
+Claude Code skills and agents — install with one command, select what you need.
+
+## Quick Start
+
+```bash
+npx gin-skills
+```
+
+Interactive TUI — use **Space** to select, **A** to toggle all, **Enter** to confirm.
+
+## Install
+
+```bash
+# Interactive — pick what you need
+npx gin-skills
+
+# Install specific skills
+npx gin-skills --skills react-query,mongodb
+
+# Install specific agents
+npx gin-skills --agents developer,tester
+
+# Install everything
+npx gin-skills --all
+
+# Install globally (available in all projects)
+npx gin-skills -g
+
+# Install to a specific project
+npx gin-skills -t /path/to/project
+```
+
+## Upgrade
+
+```bash
+# Upgrade all installed skills & agents to latest
+npx gin-skills@latest upgrade --all
+
+# Interactive — choose what to upgrade
+npx gin-skills@latest upgrade
+```
+
+## Uninstall
+
+```bash
+# Interactive — choose what to remove
+npx gin-skills uninstall
+
+# Remove from a specific project
+npx gin-skills uninstall -t /path/to/project
+
+# Remove globally installed
+npx gin-skills uninstall -g
+```
+
+## Other Commands
+
+```bash
+gin-skills status     # Show installed vs available
+gin-skills list       # List all bundled skills & agents
+gin-skills versions   # Show all published npm versions
+```
+
+**Flags:** `-g` global, `-t <path>` target project, `--all` skip prompts
+
+## Available Skills
+
+| Skill | Install | Description |
+|-------|---------|-------------|
+| `active-life-dev` | `--skills active-life-dev` | Active Life Backend Dev Guide: Comprehensive development guide for the Active Life Global Store NestJS backend (be-store-active-life-global). |
+| `ai-asset-generator` | `--skills ai-asset-generator` | AI Asset Generator: Generate production-ready images, icons, videos, and visual assets using KIE AI and background removal APIs. |
+| `ai-build-ai` | `--skills ai-build-ai` | AI Build AI: Master guide for extending Claude Code — creating skills, custom subagents (agents), MCP servers, hooks, plugins, agent teams, running... |
+| `ant-design` | `--skills ant-design` | Ant Design (antd) Expert: Production patterns for building React UIs with Ant Design v5/v6 — components, theming, Form, Table, Modal, layout, icons... |
+| `flutter-performance` | `--skills flutter-performance` | Flutter Performance Optimization: Comprehensive guide for optimizing Flutter app performance — widget rebuilds, jank reduction, memory leaks, Dart ... |
+| `icon-generator` | `--skills icon-generator` | SVG Icon Generator: Generate beautiful, clean SVG icon components (.tsx) for React Native apps using react-native-svg. |
+| `mobile-app-review` | `--skills mobile-app-review` | Mobile App Store Review Checklist: Comprehensive pre-submission audit for Apple App Store and Google Play Store. |
+| `mongodb` | `--skills mongodb` | MongoDB & Mongoose Best Practices: Production patterns for schema design, indexing, aggregation pipelines, transactions, connection management, and... |
+| `nestjs-architecture` | `--skills nestjs-architecture` | NestJS Feature-Based Architecture: Production patterns for organizing NestJS backends — feature modules, core infrastructure, shared utilities, gua... |
+| `react-fsd-architecture` | `--skills react-fsd-architecture` | Feature-Sliced Design (FSD) Architecture: Architectural methodology for organizing frontend projects by business features — layers, slices, segment... |
+| `react-native-expo` | `--skills react-native-expo` | React Native Expo (Sty AI Mobile): Production patterns for the Sty AI React Native app — Expo SDK 54, Expo Router v5, React Query v5, Zustand v5, R... |
+| `react-query` | `--skills react-query` | TanStack React Query Best Practices: Comprehensive guide for writing production-quality React Query code — query keys, mutations, caching, optimist... |
+| `review-code` | `--skills review-code` | Code Review: Comprehensive code review and quality analysis for fullstack monorepos (NestJS backend, Next.js frontend, React Native mobile). |
+| `security-scanner` | `--skills security-scanner` | Security Scanner: Comprehensive security audit for fullstack monorepos — NestJS backend, Next.js frontend, and React Native mobile app. |
+| `ui-ux-pro-max` | `--skills ui-ux-pro-max` | UI/UX design intelligence. |
+
+
+## Available Agents
+
+| Agent | Install | Description |
+|-------|---------|-------------|
+| `developer` | `--agents developer` | Full-stack developer agent for implementing features, fixing bugs, and writing production-quality code |
+| `frontend-design` | `--agents frontend-design` | Frontend design agent for building beautiful, accessible UI components and pages |
+| `mobile-reviewer` | `--agents mobile-reviewer` | Reviews React Native / Expo apps for App Store & Google Play compliance, UX best practices, and platform-specific issues |
+| `review-code` | `--agents review-code` | Reviews code for quality, architecture, and best practices across the fullstack monorepo |
+| `security-scanner` | `--agents security-scanner` | Scans for security vulnerabilities aligned with OWASP Top 10:2025, LLM Top 10, and Mobile Top 10 |
+| `tester` | `--agents tester` | Testing agent for writing and running unit tests, integration tests, and e2e tests |
+
+
+## Contributing
+
+See [DEVELOPMENT.md](./DEVELOPMENT.md) for how to add skills/agents and release new versions.

package/agents/developer.md

@@ -0,0 +1,56 @@
+---
+name: developer
+model: sonnet
+description: Full-stack developer agent for implementing features, fixing bugs, and writing production-quality code
+tools:
+  - Read
+  - Grep
+  - Glob
+  - Bash
+  - Write
+  - Edit
+---
+
+# developer
+
+You are a senior full-stack developer working in a monorepo environment. You write clean, production-quality code following the project's existing patterns and conventions.
+
+## Capabilities
+
+- Implement new features end-to-end (backend API + frontend UI + mobile screens)
+- Fix bugs by tracing root causes through the stack
+- Refactor code while preserving behavior
+- Write database schemas, services, controllers, DTOs
+- Build React/Next.js components and pages
+- Create React Native screens and navigation
+
+## Development Principles
+
+1. **Read before writing** — Always understand existing patterns before adding code
+2. **Follow conventions** — Match the project's naming, structure, and style
+3. **Minimal changes** — Only modify what's necessary; avoid unnecessary refactoring
+4. **Type safety** — Use proper TypeScript types; avoid `any`
+5. **Error handling** — Handle errors meaningfully; don't swallow exceptions
+6. **Security first** — Validate inputs, use auth guards, sanitize outputs
+
+## Workflow
+
+1. Understand the requirement
+2. Explore related code to learn existing patterns
+3. Plan the implementation (which files to create/modify)
+4. Implement with proper typing and error handling
+5. Verify the code compiles and follows project conventions
+
+## Stack Awareness
+
+- **Backend**: NestJS, MongoDB/Mongoose, Bull queues, Redis, Pino logger
+- **Frontend**: Next.js App Router, Tailwind CSS, shadcn/ui, Zustand, React Query
+- **Mobile**: React Native, Expo
+- **Shared**: TypeScript, ESLint, monorepo structure
+
+## Assigned Skills
+
+- /nestjs-architecture
+- /react-fsd-architecture
+- /react-query
+- /mongodb