@plaited/development-skills 0.6.2 → 0.6.4

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

@@ -0,0 +1,249 @@
+---
+name: typescript-lsp
+description: Search TypeScript SYMBOLS (functions, types, classes) - NOT text. Use Glob to find files, Grep for text search, LSP for symbol search. Provides type-aware results that understand imports, exports, and relationships.
+license: ISC
+compatibility: Requires bun
+allowed-tools: Bash
+metadata:
+  file-triggers: "*.ts,*.tsx,*.js,*.jsx"
+---
+
+# 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 Each Tool
+
+| Tool | Purpose |
+|------|---------|
+| **Glob** | Find files by pattern |
+| **Grep** | Search text content |
+| **lsp-find** | Search TypeScript symbols |
+| **lsp-hover** | Get type info + TSDoc documentation |
+| **lsp-refs** | Find all references to a symbol |
+| **lsp-analyze** | Batch analysis of file structure |
+
+### LSP vs Grep/Glob
+
+| Task | Use LSP | Use Grep/Glob |
+|------|---------|---------------|
+| Find all usages of a function/type | ✅ `lsp-refs` | ❌ Misses re-exports, aliases |
+| Search for a symbol by name | ✅ `lsp-find` | ❌ Matches strings, comments |
+| Get type signature + TSDoc | ✅ `lsp-hover` | ❌ Not possible |
+| Understand file exports | ✅ `lsp-analyze --exports` | ❌ Doesn't resolve re-exports |
+| 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/.plaited/skills/validate-skill/SKILL.md

@@ -0,0 +1,108 @@
+---
+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 any agent's skills directory (`.claude/skills/`, `.cursor/skills/`, etc.)
+- 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`: Paths to validate (defaults to current agent's skills directory)
+
+**Options:**
+- `--json`: Output results as JSON
+
+**Examples:**
+
+```bash
+# Validate skills in current directory's .claude/skills/
+bunx @plaited/development-skills validate-skill .claude/skills
+
+# Validate Cursor skills
+bunx @plaited/development-skills validate-skill .cursor/skills
+
+# 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 .cursor/skills --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
+✓ .cursor/skills/my-skill
+✗ .claude/skills/invalid-skill
+  ERROR: Missing required field in frontmatter: 'description'
+
+2/3 skills valid
+```
+
+### JSON (--json)
+
+```json
+[
+  {
+    "valid": true,
+    "path": ".cursor/skills/my-skill",
+    "errors": [],
+    "warnings": [],
+    "properties": {
+      "name": "my-skill",
+      "description": "..."
+    }
+  }
+]
+```
+
+## Related Skills
+
+- **typescript-lsp** - Example of a well-structured skill with scripts
+- **code-documentation** - TSDoc standards for TypeScript/JavaScript code

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@plaited/development-skills",
-  "version": "0.6.2",
+  "version": "0.6.4",
   "description": "Development skills for Claude Code - TypeScript LSP, code documentation, and validation tools",
   "license": "ISC",
   "engines": {