@plaited/development-skills 0.3.5

package/.claude/skills/typescript-lsp/SKILL.md

@@ -0,0 +1,239 @@
+---
+name: typescript-lsp
+description: REQUIRED for searching code in *.ts, *.tsx, *.js, *.jsx files. Use INSTEAD of Grep for TypeScript/JavaScript - provides type-aware symbol search that understands imports, exports, and relationships. Activate before reading, editing, or searching TypeScript code to verify signatures and find references.
+license: ISC
+compatibility: Requires bun
+allowed-tools: Bash
+metadata:
+  file-triggers: "*.ts,*.tsx,*.js,*.jsx"
+  replaces-tools: Grep
+---
+
+# TypeScript LSP Skill
+
+## Purpose
+
+This skill provides TypeScript Language Server Protocol integration for **exploring and understanding** TypeScript/JavaScript codebases. 
+
+**IMPORTANT**: Prefer LSP tools over Grep/Glob when working with `*.ts`, `*.tsx`, `*.js`, `*.jsx` files. LSP provides type-aware results that understand imports, exports, and symbol relationships.
+
+Use these tools to:
+- **Explore codebases** - Find symbols, understand module structure, discover implementations
+- **Find references** - Type-aware search across the entire codebase (better than grep for symbols)
+- **Understand types** - Get full type signatures, generics, and documentation
+- **Verify before editing** - Check all usages before modifying or deleting exports
+- **Navigate code** - Jump to definitions, find implementations
+
+## When to Use LSP vs Grep/Glob
+
+| Task | Use LSP | Use Grep/Glob |
+|------|---------|---------------|
+| Find all usages of a function/type | ✅ `lsp-references` | ❌ Misses re-exports, aliases |
+| Search for a symbol by name | ✅ `lsp-find` | ❌ Matches strings, comments |
+| Understand file exports | ✅ `lsp-analyze --exports` | ❌ Doesn't resolve re-exports |
+| Get type signature | ✅ `lsp-hover` | ❌ Not possible |
+| Find files by pattern | ❌ | ✅ `Glob` |
+| Search non-TS files (md, json) | ❌ | ✅ `Grep` |
+| Search for text in comments/strings | ❌ | ✅ `Grep` |
+
+## When to Use
+
+**Exploring code (prefer LSP):**
+- Run `lsp-find` to search for symbols across the workspace
+- Run `lsp-symbols` to get an overview of file structure
+- Run `lsp-analyze --exports` to see what a module provides
+
+**Before editing code:**
+- Run `lsp-references` to find all usages of a symbol you plan to modify
+- Run `lsp-hover` to verify current type signatures
+
+**Before writing code:**
+- Run `lsp-find` to search for similar patterns or related symbols
+- Run `lsp-hover` on APIs you plan to use
+
+## Path Resolution
+
+All scripts accept three types of file paths:
+- **Absolute paths**: `/Users/name/project/src/file.ts`
+- **Relative paths**: `./src/file.ts` or `../other/file.ts`
+- **Package export paths**: `my-package/src/module.ts` (resolved via `Bun.resolve()`)
+
+Package export paths are recommended for portability and consistency with the package's exports field.
+
+## Scripts
+
+### Individual Scripts
+
+#### lsp-hover
+Get type information at a specific position.
+
+```bash
+bunx @plaited/development-skills lsp-hover <file> <line> <char>
+```
+
+**Arguments:**
+- `file`: Path to TypeScript/JavaScript file
+- `line`: Line number (0-indexed)
+- `char`: Character position (0-indexed)
+
+**Example:**
+```bash
+bunx @plaited/development-skills lsp-hover src/utils/parser.ts 42 10
+```
+
+#### lsp-symbols
+List all symbols in a file.
+
+```bash
+bunx @plaited/development-skills lsp-symbols <file>
+```
+
+**Example:**
+```bash
+bunx @plaited/development-skills lsp-symbols src/utils/parser.ts
+```
+
+#### lsp-references
+Find all references to a symbol.
+
+```bash
+bunx @plaited/development-skills lsp-refs <file> <line> <char>
+```
+
+**Example:**
+```bash
+bunx @plaited/development-skills lsp-refs src/utils/parser.ts 42 10
+```
+
+#### lsp-find
+Search for symbols across the workspace.
+
+```bash
+bunx @plaited/development-skills lsp-find <query> [context-file]
+```
+
+**Arguments:**
+- `query`: Symbol name or partial name
+- `context-file`: Optional file to open for project context
+
+**Example:**
+```bash
+bunx @plaited/development-skills lsp-find parseConfig
+bunx @plaited/development-skills lsp-find validateInput src/lib/validator.ts
+```
+
+### Batch Script
+
+#### lsp-analyze
+Perform multiple analyses in a single session for efficiency.
+
+```bash
+bunx @plaited/development-skills lsp-analyze <file> [options]
+```
+
+**Options:**
+- `--symbols, -s`: List all symbols
+- `--exports, -e`: List only exported symbols
+- `--hover <line:char>`: Get type info (repeatable)
+- `--refs <line:char>`: Find references (repeatable)
+- `--all`: Run symbols + exports analysis
+
+**Examples:**
+```bash
+# Get file overview
+bunx @plaited/development-skills lsp-analyze src/utils/parser.ts --all
+
+# Check multiple positions
+bunx @plaited/development-skills lsp-analyze src/utils/parser.ts --hover 50:10 --hover 75:5
+
+# Before refactoring: find all references
+bunx @plaited/development-skills lsp-analyze src/utils/parser.ts --refs 42:10
+```
+
+## Common Workflows
+
+### Understanding a File
+
+```bash
+# 1. Get exports overview
+bunx @plaited/development-skills lsp-analyze path/to/file.ts --exports
+
+# 2. For specific type info, hover on interesting symbols
+bunx @plaited/development-skills lsp-hover path/to/file.ts <line> <char>
+```
+
+### Before Modifying an Export
+
+```bash
+# 1. Find all references first
+bunx @plaited/development-skills lsp-refs path/to/file.ts <line> <char>
+
+# 2. Check what depends on it
+# Review the output to understand impact
+```
+
+### Finding Patterns
+
+```bash
+# Search for similar implementations
+bunx @plaited/development-skills lsp-find handleRequest
+bunx @plaited/development-skills lsp-find parseConfig
+```
+
+### Pre-Implementation Verification
+
+```bash
+# Before writing code that uses an API, verify its signature
+bunx @plaited/development-skills lsp-hover path/to/api.ts <line> <char>
+```
+
+## Output Format
+
+All scripts output JSON to stdout. Errors go to stderr.
+
+**Hover output:**
+```json
+{
+  "contents": {
+    "kind": "markdown",
+    "value": "```typescript\nconst parseConfig: (options: Options) => Config\n```"
+  },
+  "range": { "start": {...}, "end": {...} }
+}
+```
+
+**Symbols output:**
+```json
+[
+  {
+    "name": "symbolName",
+    "kind": 13,
+    "range": { "start": {...}, "end": {...} }
+  }
+]
+```
+
+**Analyze output:**
+```json
+{
+  "file": "path/to/file.ts",
+  "exports": [
+    { "name": "exportName", "kind": "Constant", "line": 139 }
+  ]
+}
+```
+
+## Performance
+
+Each script invocation:
+1. Starts TypeScript Language Server (~300-500ms)
+2. Initializes LSP connection
+3. Opens document
+4. Performs query
+5. Closes and stops
+
+For multiple queries on the same file, use `lsp-analyze` to batch operations in a single session.
+
+## Related Skills
+
+- **code-documentation**: TSDoc standards for documentation

package/.claude/skills/validate-skill/SKILL.md

@@ -0,0 +1,105 @@
+---
+name: validate-skill
+description: Validate skill directories against AgentSkills spec
+license: ISC
+compatibility: Requires bun
+allowed-tools: Bash
+---
+
+# Validate Skill
+
+## Purpose
+
+This skill validates skill directories against the [AgentSkills specification](https://agentskills.io/specification). Use it to ensure your skills have proper frontmatter, required fields, and follow naming conventions.
+
+**Use when:**
+- Creating new skills in `.claude/skills/`
+- Reviewing PRs that modify skills
+- Validating skill structure before publishing
+
+## Scripts
+
+### validate-skill.ts
+
+Validate one or more skill directories.
+
+```bash
+bunx @plaited/development-skills validate-skill [paths...]
+```
+
+**Arguments:**
+- `paths`: Optional paths to validate (default: `.claude/skills/`)
+
+**Options:**
+- `--json`: Output results as JSON
+
+**Examples:**
+
+```bash
+# Validate all skills in .claude/skills/
+bunx @plaited/development-skills validate-skill
+
+# Validate a specific skill
+bunx @plaited/development-skills validate-skill .claude/skills/typescript-lsp
+
+# Validate multiple paths with JSON output
+bunx @plaited/development-skills validate-skill .claude/skills/typescript-lsp .claude/skills/code-documentation --json
+```
+
+## Validation Rules
+
+### Required Fields
+
+- `name`: Skill name (lowercase, alphanumeric with hyphens)
+- `description`: Brief description of the skill
+
+### Naming Conventions
+
+- Name must be lowercase
+- Only alphanumeric characters and hyphens allowed
+- Cannot start or end with hyphen
+- Cannot contain consecutive hyphens
+- Maximum 64 characters
+- Directory name must match skill name
+
+### Optional Fields
+
+- `license`: License identifier
+- `compatibility`: Runtime requirements
+- `allowed-tools`: Comma-separated list of allowed tools
+- `metadata`: Key-value pairs for additional metadata
+
+## Output Format
+
+### Human-Readable (default)
+
+```
+✓ .claude/skills/typescript-lsp
+✓ .claude/skills/code-documentation
+✗ .claude/skills/invalid-skill
+  ERROR: Missing required field in frontmatter: 'description'
+
+2/3 skills valid
+```
+
+### JSON (--json)
+
+```json
+[
+  {
+    "valid": true,
+    "path": ".claude/skills/typescript-lsp",
+    "errors": [],
+    "warnings": [],
+    "properties": {
+      "name": "typescript-lsp",
+      "description": "..."
+    }
+  }
+]
+```
+
+## Related Skills
+
+- **typescript-lsp** - Example of a well-structured skill with scripts
+- **code-documentation** - TSDoc standards for TypeScript/JavaScript code

package/LICENSE

@@ -0,0 +1,15 @@
+ISC License
+
+Copyright (c) 2025 Plaited
+
+Permission to use, copy, modify, and/or distribute this software for any
+purpose with or without fee is hereby granted, provided that the above
+copyright notice and this permission notice appear in all copies.
+
+THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH
+REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
+AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT,
+INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
+LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR
+OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
+PERFORMANCE OF THIS SOFTWARE.

package/README.md

@@ -0,0 +1,149 @@
+# development-skills
+
+TypeScript LSP, code documentation, and validation tools. Available as both a CLI tool and as installable skills for AI coding agents.
+
+## CLI Tool
+
+Use these tools directly via the CLI without installation:
+
+```bash
+# Run without installing
+bunx @plaited/development-skills lsp-hover src/index.ts 10 5
+
+# Or install globally
+bun add -g @plaited/development-skills
+development-skills lsp-find parseConfig
+```
+
+### Commands
+
+| Command | Description |
+|---------|-------------|
+| `lsp-hover <file> <line> <char>` | Get type information at position |
+| `lsp-find <query> [file]` | Search for symbols across workspace |
+| `lsp-refs <file> <line> <char>` | Find all references to symbol |
+| `lsp-analyze <file> [options]` | Batch analysis of file |
+| `validate-skill <path>` | Validate AgentSkills spec |
+
+### Examples
+
+```bash
+# Type information
+bunx @plaited/development-skills lsp-hover src/app.ts 25 10
+
+# Symbol search
+bunx @plaited/development-skills lsp-find UserConfig
+
+# Find references
+bunx @plaited/development-skills lsp-refs src/types.ts 15 8
+
+# Module analysis
+bunx @plaited/development-skills lsp-analyze src/index.ts --all
+
+# Validate skills
+bunx @plaited/development-skills validate-skill .claude/skills
+```
+
+## Skills for AI Agents
+
+**Install skills** for use with AI coding agents:
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/plaited/skills-installer/main/install.sh | bash -s -- --agent <agent-name> --project development-skills
+```
+
+Replace `<agent-name>` with your agent: `claude`, `cursor`, `copilot`, `opencode`, `amp`, `goose`, `factory`
+
+**Update skills:**
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/plaited/skills-installer/main/install.sh | bash -s -- update --agent <agent-name> --project development-skills
+```
+
+### Available Skills
+
+### TypeScript LSP
+
+TypeScript Language Server Protocol integration for exploring and understanding TypeScript/JavaScript codebases.
+
+**Use LSP over Grep/Glob when:**
+- Finding all usages of a function/type (LSP understands re-exports, aliases)
+- Searching for symbols by name (LSP ignores strings, comments)
+- Understanding file exports (LSP resolves re-exports)
+- Getting type signatures (not possible with grep)
+
+#### Commands
+
+##### `/lsp-hover`
+
+Get type information at a specific position.
+
+```bash
+/lsp-hover src/utils/parser.ts 42 10
+```
+
+##### `/lsp-find`
+
+Search for symbols across the workspace.
+
+```bash
+/lsp-find parseConfig
+/lsp-find validateInput src/lib/validator.ts
+```
+
+##### `/lsp-refs`
+
+Find all references to a symbol (before refactoring).
+
+```bash
+/lsp-refs src/utils/parser.ts 42 10
+```
+
+##### `/lsp-analyze`
+
+Batch analysis of a file.
+
+```bash
+/lsp-analyze src/utils/parser.ts --exports
+/lsp-analyze src/utils/parser.ts --all
+/lsp-analyze src/utils/parser.ts --hover 50:10 --refs 60:5
+```
+
+#### Path Resolution
+
+All commands accept:
+- **Absolute paths**: `/Users/name/project/src/file.ts`
+- **Relative paths**: `./src/file.ts`
+- **Package export paths**: `my-package/src/module.ts` (resolved via `Bun.resolve()`)
+
+### Skill Validation
+
+Validate skill directories against the AgentSkills specification.
+
+#### Commands
+
+##### `/validate-skill`
+
+Validate skill directories.
+
+```bash
+/validate-skill .claude/skills
+/validate-skill .claude/skills/typescript-lsp
+```
+
+## Development
+
+```bash
+# Install dependencies
+bun install
+
+# Run checks
+bun run check
+
+# Run tests
+bun test
+```
+
+## License
+
+ISC

package/bin/cli.ts

@@ -0,0 +1,109 @@
+#!/usr/bin/env bun
+/**
+ * Development Skills CLI
+ *
+ * Provides TypeScript LSP tools, skill validation, and code documentation utilities.
+ *
+ * Usage:
+ *   development-skills <command> [args...] [options]
+ *
+ * Commands:
+ *   lsp-hover <file> <line> <char>    Get type information at position
+ *   lsp-find <query> [file]            Search for symbols
+ *   lsp-refs <file> <line> <char>     Find all references
+ *   lsp-symbols <file>                 List all symbols in file
+ *   lsp-analyze <file>                 Batch analysis
+ *   validate-skill <path>              Validate AgentSkills spec
+ *   scaffold-rules [options]           Generate development rules
+ *
+ * Examples:
+ *   bunx @plaited/development-skills lsp-hover src/index.ts 10 5
+ *   bunx @plaited/development-skills lsp-find parseConfig
+ *   bunx @plaited/development-skills validate-skill .claude/skills/my-skill
+ *   bunx @plaited/development-skills scaffold-rules --agent=claude --format=json
+ */
+
+import { lspAnalyze } from '../src/lsp-analyze.ts'
+import { lspFind } from '../src/lsp-find.ts'
+import { lspHover } from '../src/lsp-hover.ts'
+import { lspRefs } from '../src/lsp-references.ts'
+import { lspSymbols } from '../src/lsp-symbols.ts'
+import { scaffoldRules } from '../src/scaffold-rules.ts'
+import { validateSkill } from '../src/validate-skill.ts'
+
+// Get raw args (everything after script name)
+const rawArgs = Bun.argv.slice(2)
+
+// Extract command (first non-option arg)
+const command = rawArgs.find((arg) => !arg.startsWith('-')) || ''
+
+// Get args after command (everything except the command itself)
+const commandIndex = rawArgs.indexOf(command)
+const args = commandIndex >= 0 ? rawArgs.slice(commandIndex + 1) : []
+
+if (!command || command === '--help' || command === '-h') {
+  console.log(`
+Development Skills CLI
+
+Usage:
+  development-skills <command> [args...] [options]
+
+Commands:
+  lsp-hover <file> <line> <char>    Get type information at position
+  lsp-find <query> [file]            Search for symbols
+  lsp-refs <file> <line> <char>     Find all references
+  lsp-symbols <file>                 List all symbols in file
+  lsp-analyze <file>                 Batch analysis
+  validate-skill <path>              Validate AgentSkills spec
+  scaffold-rules [options]           Generate development rules
+
+Examples:
+  bunx @plaited/development-skills lsp-hover src/index.ts 10 5
+  bunx @plaited/development-skills lsp-find parseConfig
+  bunx @plaited/development-skills lsp-refs src/types.ts 15 8
+  bunx @plaited/development-skills lsp-symbols src/app.ts
+  bunx @plaited/development-skills lsp-analyze src/app.ts
+  bunx @plaited/development-skills validate-skill .claude/skills/my-skill
+  bunx @plaited/development-skills scaffold-rules --agent=claude --format=json
+
+Options:
+  -h, --help    Show this help
+`)
+  process.exit(0)
+}
+
+// Route to appropriate command
+try {
+  switch (command) {
+    case 'lsp-hover':
+      await lspHover(args)
+      break
+    case 'lsp-find':
+      await lspFind(args)
+      break
+    case 'lsp-refs':
+    case 'lsp-references':
+      await lspRefs(args)
+      break
+    case 'lsp-symbols':
+      await lspSymbols(args)
+      break
+    case 'lsp-analyze':
+      await lspAnalyze(args)
+      break
+    case 'validate-skill':
+      await validateSkill(args)
+      break
+    case 'scaffold-rules':
+      await scaffoldRules(args)
+      break
+    default:
+      console.error(`Unknown command: ${command}`)
+      console.error('Run `development-skills --help` for usage')
+      process.exit(1)
+  }
+} catch (error) {
+  const message = error instanceof Error ? error.message : String(error)
+  console.error(`Error: ${message}`)
+  process.exit(1)
+}

package/package.json

@@ -0,0 +1,57 @@
+{
+  "name": "@plaited/development-skills",
+  "version": "0.3.5",
+  "description": "Development skills for Claude Code - TypeScript LSP, code documentation, and validation tools",
+  "license": "ISC",
+  "engines": {
+    "bun": ">= v1.2.9"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/plaited/development-skills.git"
+  },
+  "bugs": {
+    "url": "https://github.com/plaited/development-skills/issues"
+  },
+  "homepage": "https://github.com/plaited/development-skills/tree/main#readme",
+  "bin": {
+    "development-skills": "./bin/cli.ts"
+  },
+  "type": "module",
+  "files": [
+    "bin/",
+    "src/",
+    ".claude/"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "check": "bun run check:biome && bun run check:types && bun run check:package",
+    "check:biome": "biome check",
+    "check:package": "format-package --check",
+    "check:types": "tsc --noEmit",
+    "check:write": "biome check --write && format-package --write",
+    "prepare": "git config core.hooksPath .hooks || true",
+    "test": "bun test"
+  },
+  "lint-staged": {
+    "*.{js,cjs,jsx,tsx,ts}": [
+      "bunx biome check --write"
+    ],
+    "package.json": [
+      "format-package"
+    ]
+  },
+  "peerDependencies": {
+    "typescript-language-server": "^5.1.3"
+  },
+  "devDependencies": {
+    "@biomejs/biome": "2.3.11",
+    "@types/bun": "1.3.6",
+    "format-package": "7.0.0",
+    "lint-staged": "16.2.7",
+    "typescript": "5.9.3",
+    "typescript-language-server": "5.1.3"
+  }
+}