@alexgorbatchev/pi-skill-library 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Alex Gorbatchev
+
+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

@@ -0,0 +1,88 @@
+# @alexgorbatchev/pi-skill-library
+
+[pi](https://pi.dev) extension that discovers `skills-library` roots and exposes their skills through `/library:<skill-name>` commands. This extension solves the problem of too many skills. There are skills that you need only occasionally and maybe don't even need them discoverable. 
+
+## Install
+
+```bash
+pi install npm:@alexgorbatchev/pi-skill-library
+```
+
+## What it does
+
+This package does **not** register bundled skills through Pi's normal skill loader.
+Instead, it discovers `skills-library` directories, loads the skills from those roots itself, and expands:
+
+```text
+/library:<skill-name>
+```
+
+into the same `<skill ...>...</skill>` block format Pi uses for built-in `/skill:<name>` expansion.
+
+That keeps these skills out of Pi's default skill discovery flow while still making them explicitly invokable.
+
+## Library root locations
+
+The extension looks for `skills-library` in these places:
+
+- `<cwd>/.pi/skills-library`
+- `<cwd>` and ancestor `.agents/skills-library` directories, stopping at the git root (or filesystem root when no git root exists)
+- `~/.pi/agent/cskills-library`
+- `~/.agents/skills-library`
+- package-local `skills-library` directories derived from discovered package skill roots
+- extra paths configured via Pi settings under `@alexgorbatchev/pi-skills-library.paths`
+
+## Settings
+
+Use a namespaced block in Pi settings:
+
+```json
+{
+  "@alexgorbatchev/pi-skills-library": {
+    "paths": [
+      "./skills-library",
+      "~/shared/pi-skills-library"
+    ]
+  }
+}
+```
+
+Path resolution follows normal Pi settings behavior:
+
+- paths in `~/.pi/agent/settings.json` resolve relative to `~/.pi/agent`
+- paths in `.pi/settings.json` resolve relative to `.pi`
+- absolute paths are supported
+- `~/...` is supported
+
+## Directory layout
+
+Each library root should contain normal skill directories:
+
+```text
+skills-library/
+├── my-skill/
+│   └── SKILL.md
+└── another-skill/
+    ├── SKILL.md
+    └── references/
+```
+
+## Commands
+
+Invoke a library skill directly:
+
+```text
+/library:my-skill
+/library:my-skill additional context here
+```
+
+Discovered library skills are registered as real extension slash commands at startup and reload, so they show up in slash-command autocomplete like other commands.
+
+On startup, the extension prints a library-discovery message into the transcript listing each discovered library root and its skills. Home-directory paths are rendered with the `~/` convention.
+
+Use the package info command to print the same report again:
+
+```text
+/pi-skill-library
+```
+

package/package.json

@@ -0,0 +1,49 @@
+{
+  "name": "@alexgorbatchev/pi-skill-library",
+  "version": "0.1.0",
+  "description": "Pi extension that exposes skills-library roots through /library:<skill-name> commands.",
+  "type": "module",
+  "license": "MIT",
+  "packageManager": "bun@1.3.10",
+  "keywords": [
+    "pi-package",
+    "pi-extension",
+    "skills",
+    "skill",
+    "library"
+  ],
+  "files": [
+    "src",
+    "skills-library",
+    "README.md",
+    "LICENSE"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "pi": {
+    "extensions": [
+      "./src/index.ts"
+    ]
+  },
+  "peerDependencies": {
+    "@mariozechner/pi-coding-agent": "*"
+  },
+  "devDependencies": {
+    "@mariozechner/pi-coding-agent": "0.64.0",
+    "@types/node": "24.7.2",
+    "@typescript/native-preview": "7.0.0-dev.20260330.1",
+    "dprint": "0.53.0",
+    "oxlint": "1.56.0",
+    "typescript": "6.0.2"
+  },
+  "scripts": {
+    "dev": "bun x pi -e ./src/index.ts",
+    "check": "bun run typecheck && bun run lint && bun run format:check && bun run verify:pi-load",
+    "typecheck": "tsgo --noEmit -p tsconfig.json",
+    "lint": "oxlint --config oxlintrc.json .",
+    "format": "dprint fmt",
+    "format:check": "dprint check",
+    "verify:pi-load": "PI_OFFLINE=1 bun x pi --no-extensions -e ./src/index.ts --list-models > /dev/null 2>&1"
+  }
+}

package/skills-library/opencode-config/SKILL.md

@@ -0,0 +1,51 @@
+---
+name: opencode-config
+description: >-
+  Set up and configure opencode.jsonc for OpenCode projects. Use when creating a
+  new opencode.jsonc configuration file, adding instruction file paths, or
+  configuring OpenCode settings for a repository.
+targets:
+  - '*'
+---
+
+# OpenCode Config
+
+## Overview
+
+Create and configure `opencode.jsonc` in the repository root to customize OpenCode behavior per project.
+
+## Setup
+
+1. Create `opencode.jsonc` in the repository root
+2. Add the schema reference for validation and autocompletion
+3. Add instruction file paths to the `instructions` array
+
+### Minimal Configuration
+
+```jsonc
+{
+  "$schema": "https://opencode.ai/config.json",
+}
+```
+
+### .github Instructions
+
+If there is `.github/instructions` folder update config to include `instructions` field, like so:
+
+```jsonc
+"instructions": [
+  ".github/instructions/*.instructions.md",
+],
+```
+
+### .github Skills
+
+If there is `.github/skills` folder update config to include `skills` field, like so:
+
+```jsonc
+"skills": {
+  "paths": [
+    ".github/skills",
+  ]
+}
+```

package/skills-library/react-development/SKILL.md

@@ -0,0 +1,135 @@
+---
+name: react-development
+description: >-
+  Build and modify React components, hooks, context providers, and JSX render
+  trees. Use when implementing or refactoring React UI code, component APIs,
+  render branches, shared primitives, hook-driven state, DOM structure, or test
+  ID conventions. Covers the required `data-testid` naming contract and the ban
+  on using `createElement` from React in regular application code.
+---
+
+# React Development
+
+Use existing React patterns before introducing new ones. Preserve accessibility, composability, and readable JSX.
+
+## Workflow
+
+1. Inspect the existing component, shared primitives, hooks, and nearby tests before editing.
+2. Reuse an existing component or hook when one already expresses the pattern.
+3. Keep rendering in JSX. Extract helpers or hooks instead of switching to `createElement`.
+4. Apply the test ID contract exactly when a tagged element is needed.
+5. Run the narrowest relevant validation first, then broader lint and test commands.
+
+## Non-negotiable rules
+
+### 1. Use the test ID contract exactly
+
+Apply these rules exactly unless the repository documents a different contract:
+
+- Use the plain component name on the root rendered element of a component.
+- Use `ComponentName--thing` for tagged child elements inside that component.
+- Use kebab-case for `thing`.
+- Use semantic targets, not positional names.
+- Use the local helper component name when a helper component renders its own tagged root.
+- Do not invent `--root` or other suffixes on the root unless the repository explicitly requires them.
+
+Valid:
+
+```tsx
+export function PlanChat() {
+  return (
+    <section data-testid='PlanChat'>
+      <div data-testid='PlanChat--thread-viewport' />
+    </section>
+  );
+}
+```
+
+```tsx
+function ReasoningPart() {
+  return <ToolCallCard testId='ReasoningPart' />;
+}
+```
+
+Invalid:
+
+```tsx
+<section data-testid='PlanChat--root' />
+```
+
+```tsx
+<div data-testid='thread-viewport' />
+```
+
+```tsx
+function ReasoningPart() {
+  return <ToolCallCard testId='PlanChat--reasoning-card' />;
+}
+```
+
+Prefer accessible queries in tests. Add `data-testid` only when the element is not reliably targetable through role, label, text, or stable semantic structure.
+
+### 2. Keep regular React code in JSX
+
+Do not use `createElement` or `React.createElement` in ordinary application code.
+
+Use JSX for:
+
+- normal component bodies
+- conditional rendering
+- lists and mapping
+- wrapper composition
+- provider trees
+- tool or widget registries that can be expressed directly in JSX
+
+Allow `createElement` only when a specific domain constraint requires it and that requirement is documented explicitly at the use site or in adjacent documentation. Typical exceptions are rare and include cases such as:
+
+- schema-driven renderers
+- AST or MDX renderers
+- plugin systems that receive component types dynamically
+- framework integration points that require raw element factory calls
+
+Do not introduce `createElement` just to:
+
+- avoid JSX syntax
+- build dynamic props more mechanically
+- mimic framework internals
+- shorten code that JSX already expresses clearly
+
+When an exception is truly required, isolate it, document why JSX is insufficient, and test it.
+
+## Component design rules
+
+- Prefer function components and hooks over class components unless the codebase already requires a class boundary.
+- Keep props narrow and typed.
+- Extract pure transforms into helpers instead of embedding large calculations in render.
+- Extract repeated stateful behavior into hooks only when more than one caller needs it or the component becomes hard to read.
+- Reuse shared primitives for buttons, inputs, dialogs, cards, and layout shells before adding one-off markup.
+- Keep render branches explicit. Make loading, empty, error, and success states easy to read.
+- Preserve accessible names and roles when refactoring structure.
+
+## Review checklist
+
+Before finishing a React change, verify all of the following:
+
+- root test IDs use the plain component name
+- child test IDs use `ComponentName--thing`
+- helper components with their own tagged roots use their own names
+- no new `createElement` usage was introduced without an explicit documented exception
+- shared primitives were reused where appropriate
+- accessible queries remain possible for user-facing controls
+- relevant lint, type, and test commands were run
+
+## References
+
+- Read `references/oxlint.md` when adding or changing React-specific lint rules, custom Oxlint plugins, test ID enforcement, or `createElement` bans.
+- Read `references/reactPolicyPlugin.js` for a concrete local Oxlint plugin example.
+- Read `references/reactPolicyPlugin.test.ts` for a concrete Bun test harness for the plugin.
+- Read `references/oxlintrc.json` for a concrete scoped config example.
+
+## Companion skills
+
+Use related skills when the task goes deeper in those areas:
+
+- `react-testing` for Storybook stories, play functions, and interaction coverage
+- `typescript-code-quality` when TypeScript structure and type-safety rules matter heavily

package/skills-library/react-development/references/oxlint.md

@@ -0,0 +1,144 @@
+# Oxlint for React Repositories
+
+Read this file when the task involves adding, tightening, or debugging React lint rules, custom Oxlint plugins, or CI enforcement.
+
+## Enforcement strategy
+
+Use Oxlint for fast editor and CI feedback.
+
+Split enforcement into two groups:
+
+1. **Built-in rules** for generic quality and correctness
+2. **Local JS plugins** for repository-specific React contracts
+
+Prefer built-in rules when they express the requirement directly. Use a local plugin only when the rule is specific to the repository and cannot be expressed well with built-ins.
+
+## High-value React policies to enforce
+
+### 1. Ban `createElement` in regular application code
+
+Use a linter rule or repo-local plugin to reject:
+
+- `import { createElement } from 'react'`
+- `React.createElement(...)`
+
+Scope exceptions explicitly to:
+
+- tests
+- Storybook setup/mocks
+- documented framework boundaries
+- documented schema/plugin renderers
+
+If the repository allows a rare production exception, require a short comment at the use site explaining why JSX is insufficient.
+
+## 2. Enforce the test ID naming contract
+
+If the repository uses test IDs, prefer a custom plugin for exact policy enforcement.
+
+Example policy:
+
+- component root: `ComponentName`
+- child elements: `ComponentName--thing`
+- helper components with their own tagged roots use their own names
+
+Use a local plugin when the policy depends on component names, render branches, or JSX structure.
+
+## 3. Scope rules by file type
+
+Do not run React-specific rules on the whole repository.
+
+Use `overrides` to target the file types the policy actually governs.
+
+For repositories where every `.tsx` file is in scope for React UI policy, prefer this broad pattern so new files are not missed:
+
+```json
+{
+  "$schema": "./node_modules/oxlint/configuration_schema.json",
+  "jsPlugins": ["./scripts/oxlint/reactPolicyPlugin.js"],
+  "overrides": [
+    {
+      "files": ["**/*.tsx"],
+      "rules": {
+        "repo-react/no-regular-create-element": "error",
+        "repo-react/require-component-root-testid": "error"
+      }
+    }
+  ]
+}
+```
+
+Use narrower globs only when the repository deliberately excludes some `.tsx` categories from the policy.
+
+## Local plugin guidance
+
+Implement a local plugin when the repository needs React-specific contracts that built-ins do not cover.
+
+Concrete reference files in this skill:
+
+- `references/reactPolicyPlugin.js` — example plugin with `no-regular-create-element` and `require-component-root-testid`
+- `references/reactPolicyPlugin.test.ts` — Bun tests that run Oxlint against temp fixtures
+- `references/oxlintrc.json` — scoped config example wiring the plugin into Oxlint
+
+Typical cases:
+
+- test ID naming derived from component names
+- banning `createElement` except in scoped files
+- repository-specific wrapper conventions
+- enforcing root render wrappers for provider-only components
+
+Keep plugins small and exact. One repository contract per rule is usually the right granularity.
+
+## Rule design guidance
+
+### `no-regular-create-element`
+
+The rule should:
+
+- flag `createElement` imports from `react`
+- flag `React.createElement(...)`
+- ignore test files and documented exception paths through config scoping, not heuristics
+- report a direct message: use JSX instead of `createElement` in regular React code
+
+### `require-component-root-testid`
+
+The rule should:
+
+- detect exported PascalCase components
+- inspect all non-null render branches
+- require exact root test IDs
+- validate child test IDs against the component name
+- ignore nested functions and nested classes while traversing one component body
+
+Use a repository-level test in addition to the plugin when the rule performs AST-heavy structural checks.
+
+## Validation workflow
+
+When adding or changing React lint rules:
+
+1. Run the targeted Oxlint command on the affected files first.
+2. Run the plugin tests if a local plugin changed.
+3. Run the type checker.
+4. Run adjacent React tests.
+5. Run the broader repo lint command last.
+
+Example:
+
+```bash
+bun x oxlint -c oxlintrc.json --deny-warnings src/components
+bun test scripts/oxlint/__tests__/reactPolicyPlugin.test.ts
+bun x tsgo -p . --noEmit
+bun test src/components --max-concurrency=1
+```
+
+## Failure policy
+
+Do not weaken a React lint rule just to get a change through.
+
+If the rule blocks valid code, fix one of these instead:
+
+- the component structure
+- the rule implementation
+- the file scope in config
+- the documented policy
+
+Do not add blanket ignores when a scoped override or a better rule is the correct solution.

package/skills-library/react-development/references/oxlintrc.json

@@ -0,0 +1,16 @@
+{
+  "$schema": "./node_modules/oxlint/configuration_schema.json",
+  "jsPlugins": ["./scripts/oxlint/reactPolicyPlugin.js"],
+  "rules": {
+    "eqeqeq": "error"
+  },
+  "overrides": [
+    {
+      "files": ["**/*.tsx"],
+      "rules": {
+        "repo-react/no-regular-create-element": "error",
+        "repo-react/require-component-root-testid": "error"
+      }
+    }
+  ]
+}