@pedroab0/skills 0.0.0-stage → 1.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Pedro Barbosa
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,195 @@
-# Temporary Holding Version
+# Skills
+
+<p align="center">
+  <a href="https://www.npmjs.com/package/@pedroab0/skills"><img src="https://img.shields.io/npm/dm/@pedroab0/skills.svg" alt="npm downloads" /></a>
+  <a href="https://www.npmjs.com/package/@pedroab0/skills"><img src="https://img.shields.io/npm/v/@pedroab0/skills.svg" alt="npm version" /></a>
+  <a href="https://www.figma.com/community/plugin/1691244420692136789/figma-node-json-extractor"><img src="https://img.shields.io/badge/Figma_Community-Plugin-000000?style=flat&logo=figma&logoColor=white" alt="Figma Community Plugin" /></a>
+  <a href="LICENSE"><img src="https://img.shields.io/badge/License-MIT-blue.svg" alt="License: MIT" /></a>
+</p>
+
+A curated collection of modular, production-ready skills developed for AI coding agents (such as Claude Code, OpenCode, Codex, Google Antigravity, and Cursor).
+
+Each skill in this repository is designed to give AI assistants specialized, autonomous capabilities while maintaining:
+- **Token Efficiency**: Pruning unnecessary data and noise to keep agent context windows lean and fast.
+- **Zero or Minimal Dependencies**: Standalone scripts that execute on demand without fragile background daemons.
+- **Domain Intelligence**: Structured, context-aware outputs (such as resolved design tokens and component props) that allow agents to generate production-quality code.
+
+---
+
+## Available Skills
+
+| Skill | Role / Workflow | Description | Links |
+| :--- | :--- | :--- | :--- |
+| **[`figma-to-code`](./figma-to-code)** | **One-Shot / Fast Prototyping** | Direct, single-turn conversion of Figma designs into clean, production-ready UI components. Best for rapid prototyping and standalone components. | [Guide](./figma-to-code/README.md) · [`SKILL.md`](./figma-to-code/SKILL.md) |
+| **[`figma-extractor`](./figma-extractor)** | **SDD Step 1 (Ingest)** | Pure specification scraper (CLI / REST API) and companion Figma Desktop plugin that pull compact layout trees, design tokens, and preview images into `./.specs/`. Never touches application code. | [Guide](./figma-extractor/README.md) · [Plugin](./figma-extractor/figma-plugin/README.md) · [Community](https://www.figma.com/community/plugin/1691244420692136789/figma-node-json-extractor) · [`SKILL.md`](./figma-extractor/SKILL.md) |
+| **[`figma-node-builder`](./figma-node-builder)** | **SDD Step 2 (Implement)** | Grounded UI builder that reads extracted Figma Node specifications (`.specs/*.json`) and preview images (`*.png`) to build components without CSS hallucinations. | [Guide](./figma-node-builder/README.md) · [`SKILL.md`](./figma-node-builder/SKILL.md) |
+
+---
+
+## Two Supported Workflows
+
+```mermaid
+flowchart TD
+    subgraph PathA ["⚡ Workflow A: Fast Prototyping (One-Shot)"]
+        A1["Figma URL"] --> A2["figma-to-code"]
+        A2 --> A3["Working UI Component"]
+    end
+
+    subgraph PathB ["📐 Workflow B: Spec-Driven Development (SDD)"]
+        B1["Figma URL or Canvas Selection"] --> B2["figma-extractor<br/>(CLI or Figma Desktop Plugin)"]
+        B2 --> B3["Specification Contract<br/>.specs/card.json (+ .png)"]
+        B3 --> B4["Human Review & Gap Analysis"]
+        B4 --> B5["figma-node-builder"]
+        B5 --> B6["Grounded Production Component"]
+    end
+```
+
+* **Use `figma-to-code`** when you want fast execution: you provide a Figma URL, and the agent extracts and writes the component in one turn.
+* **Use `figma-extractor` + `figma-node-builder`** in formal Spec-Driven Development (SDD): the design specification is extracted to disk first (via CLI or the companion Figma Desktop plugin), reviewed/approved, and then systematically implemented into your design system without premature code edits.
+
+---
+
+### Zero-API Companion: Figma Desktop Plugin
+
+<p align="center">
+  <img src="./figma-extractor/figma-plugin/assets/cover.png" alt="Figma Node JSON Extractor" width="100%" />
+</p>
+
+To extract specifications directly inside Figma Desktop without API tokens or rate limits, use the companion [**Figma Node JSON Extractor**](./figma-extractor/figma-plugin/README.md) plugin:
+* **Figma Community (Recommended)**: Install [**Figma Node JSON Extractor** on Figma Community](https://www.figma.com/community/plugin/1691244420692136789/figma-node-json-extractor) directly, or search for it under Figma Plugins.
+* **Manual Manifest Import (Local Backup)**: In Figma Desktop, go to **Plugins** $\rightarrow$ **Development** $\rightarrow$ **Import plugin from manifest...** and select `manifest.json` from your installed skills folder (e.g. `~/.claude/skills/figma-extractor/figma-plugin/manifest.json` or `~/.gemini/config/skills/figma-extractor/figma-plugin/manifest.json`).
+
+---
+
+## Quick Install via `npx`
+
+Install any or all skills into your favorite AI coding assistant with a single interactive command:
+
+```bash
+# Recommended (npm registry):
+npx @pedroab0/skills
+
+# Or directly from GitHub:
+npx github:pedroab0/skills
+```
+
+The installer features a clean, interactive terminal UI:
+* **Navigate**: Use keyboard arrows (`↑` / `↓`) or vim keys (`k` / `j`) to move between options.
+* **Select**: Press `[Enter]` or press number keys (`1` - `5`) to select directly.
+* **Exit**: Press `[ESC]` or `q` at any time to cancel cleanly.
+
+### Selection Options & Presets
+
+1. **All skills** `[Enter / 1]`: Installs `figma-to-code`, `figma-extractor`, and `figma-node-builder` (recommended).
+2. **figma-extractor and figma-node-builder** `[2]`: Spec-Driven Development (SDD) Suite.
+3. **figma-to-code** `[3]`: Fast prototyping (URL ──► UI Code).
+4. **figma-extractor** `[4]`: Figma design scraper (extracts layout AST, tokens & preview images to `.specs/`).
+5. **figma-node-builder** `[5]`: Builds UI components from extracted Figma JSON specs (`.specs/*.json`).
+
+Or specify flags for fast, non-interactive setup:
+```bash
+# Install all skills for Claude Code globally
+npx @pedroab0/skills --agent claude --skill all
+
+# Install SDD skills for Google Antigravity
+npx @pedroab0/skills --agent antigravity --skill figma-extractor,figma-node-builder
+
+# Install one-shot coder for Cursor (.cursor/rules)
+npx @pedroab0/skills --agent cursor --skill figma-to-code
+```
+
+---
+
+## Manual Installation Guide
+
+If you prefer to install manually, all skills follow the open Agent Skills standard (`SKILL.md` format):
+
+### 1. Claude Code
+
+Claude Code supports skills both locally within a repository or globally across your user profile.
+
+- **Global Installation (All Projects)**:
+  ```bash
+  mkdir -p ~/.claude/skills
+  ln -s /path/to/skills/figma-to-code ~/.claude/skills/figma-to-code
+  ln -s /path/to/skills/figma-extractor ~/.claude/skills/figma-extractor
+  ln -s /path/to/skills/figma-node-builder ~/.claude/skills/figma-node-builder
+  ```
+
+- **Usage & Activation**:
+  - **Automatic**: Claude Code inspects `SKILL.md` descriptions on startup and loads the appropriate skill automatically based on your prompt.
+  - **Manual Slash Command**: Run `/figma-to-code <FigmaURL>` or `/figma-extractor <FigmaURL>` directly in the chat.
+
+---
+
+### 2. OpenCode
+
+OpenCode discovers skills from project or user configuration directories, maintaining full compatibility with the open `SKILL.md` standard.
+
+- **Global Installation (All Projects)**:
+  ```bash
+  mkdir -p ~/.config/opencode/skills
+  ln -s /path/to/skills/figma-to-code ~/.config/opencode/skills/figma-to-code
+  ln -s /path/to/skills/figma-extractor ~/.config/opencode/skills/figma-extractor
+  ln -s /path/to/skills/figma-node-builder ~/.config/opencode/skills/figma-node-builder
+  ```
+
+---
+
+### 3. Cursor
+
+In Cursor, reference skills via `.cursor/rules/` or mention them in Composer chat:
+* To extract specs: prompt `@figma-extractor extract this frame: <url>`.
+* To implement a spec: prompt `@figma-node-builder implement .specs/card.json`.
+
+---
+
+### 4. Google Antigravity / Gemini CLI
+ 
+Symlink or copy the skills into your Antigravity skills directory (`~/.gemini/config/skills` for Antigravity 2.0, or legacy `~/.gemini/antigravity-cli/skills`):
+```bash
+mkdir -p ~/.gemini/config/skills
+ln -s /path/to/skills/figma-to-code ~/.gemini/config/skills/figma-to-code
+ln -s /path/to/skills/figma-extractor ~/.gemini/config/skills/figma-extractor
+ln -s /path/to/skills/figma-node-builder ~/.gemini/config/skills/figma-node-builder
+```
+
+---
+
+## Repository Structure
+
+```text
+skills/
+├── README.md                 # Curated skills repository catalog (this file)
+├── figma-to-code/            # Direct one-shot Figma to UI code generator
+│   ├── SKILL.md              # One-shot agent skill definition
+│   ├── README.md             # One-shot documentation & flags
+│   └── scripts/              # Extraction scripts & test suite
+├── figma-extractor/          # SDD Step 1: Pure Figma design specification scraper
+│   ├── SKILL.md              # Pure scraper skill definition (outputs to .specs/)
+│   ├── README.md             # In-depth scraper documentation & flags
+│   ├── figma-plugin/         # Zero-API Figma Desktop plugin (AST + preview exporter)
+│   └── scripts/              # Standalone Node.js extraction scripts & tests
+└── figma-node-builder/       # SDD Step 2: Spec-driven UI component builder
+    ├── SKILL.md              # 4-Phase SDD implementation skill definition
+    ├── README.md             # In-depth builder documentation
+    └── scripts/              # Spec inspector CLI & test suite
+```
+
+---
+
+## Adding New Skills
+
+When adding new skills to this curation:
+1. Create a dedicated directory: `<skill-name>/`
+2. Include a `SKILL.md` with standard YAML frontmatter (`name`, `description`) and agent instructions.
+3. Provide a `README.md` with detailed skill-specific documentation and manual execution flags.
+4. Keep scripts self-contained with minimal external dependencies.
+5. Update this root `README.md` catalog to list the new skill.
+
+---
+
+## License
+
+This project is licensed under the [MIT License](LICENSE).
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.