name: upskill description: Meta-skill that learns new capabilities from NPM and pip package registries. Use when user asks to integrate with a service (e.g., "I need to use Asana"), mentions an API we don't have a skill for, or explicitly invokes "/skill upskill ". Automatically searches NPM and pip, installs packages globally to ~/.claude/, and generates skill documentation. DEFAULT: Any time system needs to use an API, check package registries first.

Upskill - Learn New Capabilities from Package Registries

Purpose

Meta-skill that automatically learns new capabilities by searching NPM and pip registries, installing packages globally, and generating skill documentation. Enables the system to recursively teach itself new tools.

How Skills Work:

Skills are documentation/instructions loaded into context via the Skill tool
Main context reads the skill, then writes and executes scripts directly
No subagents - execution happens in main context for simplicity and speed
Skills are lightweight reference material (~20-30 lines), full docs separate

When to Use

Auto-trigger on:

User asks to integrate with a service: "I need to use Asana", "Connect to Slack"
User mentions an API/system we don't have a skill for
Explicit invocation: /skill upskill <package-name>
DEFAULT: Any time system needs to use an API → check package registries first

Process

Step 1: Search Both Registries (NPM first, then pip)

# Search NPM
curl -s "https://registry.npmjs.org/-/v1/search?text=<package-name>&size=20" | jq '.objects[] | {name: .package.name, version: .package.version, description: .package.description, downloads: .package.downloadsLastWeek}'

# Search PyPI (package must exist for direct query)
curl -s "https://pypi.org/pypi/<package-name>/json" | jq '{name: .info.name, version: .info.version, description: .info.summary}'

Selection criteria:

Official/maintained packages
Download counts and maintenance frequency
TypeScript definitions (NPM) or type stubs (pip)
Recently updated

Step 2: Fetch Package Info

NPM packages:

# Get full metadata
curl -s "https://registry.npmjs.org/<package-name>" | jq > npm-metadata.json

# Key fields: .versions, .dist.tarball, .readme, .types, .repository

pip packages:

# Get full metadata
curl -s "https://pypi.org/pypi/<package-name>/json" | jq > pypi-metadata.json

# Key fields: .info, .releases, .urls, .project_urls

Step 3: Install Package Globally

CRITICAL: Install to ~/.claude/ (not project-specific, not system-wide)

For NPM packages:

cd ~/.claude
npm install <package-name>
# Verifies: ~/.claude/node_modules/<package-name>/

For pip packages:

pip install --target ~/.claude/lib <package-name>
# Verifies: ~/.claude/lib/python3.X/site-packages/<package-name>/

Step 4: Analyze API Surface

NPM packages (TypeScript):

Check for .d.ts files in package
Parse exported functions, classes, interfaces
Extract main entry points from package.json
Identify authentication patterns (API keys, OAuth)

pip packages (Python):

Look for .pyi type stub files
Inspect module structure
Extract docstrings and function signatures
Identify authentication requirements

Fallback for both:

Extract examples from README.md
Look for common patterns (Client classes, resources)
Search for "authentication", "API key" patterns

Step 5: Generate Skill Structure

CRITICAL: Use correct directory structure

~/.claude/skills/<package-name>/
├── SKILL.md              # Main skill file (minimal, loaded into context)
├── full-docs.md          # Complete API reference (reference only)
└── metadata.json         # Machine-readable metadata

SKILL.md template (minimal, ~20-30 lines):

---
name: <package-name>
description: Use when <specific use case> - supports <main features>. Package installed at ~/.claude/node_modules/<package>/ (or ~/.claude/lib/pythonX.Y/site-packages/<package>/)
---

# <Package-Name> Skill

## Overview
<Brief description of what the package does>

## Package Info
- **Registry**: NPM | pip
- **Package**: <package-name>
- **Version**: X.Y.Z
- **Runtime**: Node.js | Python
- **Location**: ~/.claude/node_modules/<package>/ | ~/.claude/lib/python3.X/site-packages/<package>/

## Installation
Already installed globally at ~/.claude/<location>
Available in all projects.

## Authentication
<If required, explain how to get and set credentials>
<If not required, state: No authentication required>

## Quick Reference
<Main functions/methods with signatures>

metadata.json template:

{
  "name": "<package-name>",
  "package": "<package-name>",
  "version": "X.Y.Z",
  "runtime": "node" | "python",
  "registry": "npm" | "pypi",
  "last_checked": "2025-01-13T10:00:00Z",
  "last_updated": "2025-01-13T10:00:00Z",
  "capabilities": ["cap1", "cap2"],
  "triggers": ["keyword1", "keyword2"],
  "credential_env": null | "CLAUDE_<SERVICE>_TOKEN",
  "install_path": "~/.claude/node_modules/<package>/",
  "requires_auth": false | true
}

Step 6: Update Version Cache

# Update ~/.claude/skill-cache/package-versions.json
{
  "<package-name>": {
    "installed": "X.Y.Z",
    "latest": "X.Y.Z",
    "last_checked": "2025-01-13T10:00:00Z",
    "update_available": false,
    "critical": false,
    "breaking": false
  }
}

Step 7: Credential Setup (if required)

If package requires authentication:

Identify auth mechanism (API key, OAuth, token)
Provide URL to get credentials

Guide user to set environment variable:

# Recommended: App-specific prefix
export CLAUDE_<SERVICE>_TOKEN=your_token_here

# Or add to ~/.zshrc or ~/.bashrc

Test credentials before confirming success

Step 8: Test and Confirm

Verify installation:

# For NPM packages
node -e "const pkg = require('/Users/davidpreil/.claude/node_modules/<package>'); console.log('OK');"

# For pip packages
python3 -c "import sys; sys.path.insert(0, '/Users/davidpreil/.claude/lib'); import <package>; print('OK')"

Confirm success:

✓ Learned <package-name> vX.Y.Z (NPM|pip)
✓ Skill: ~/.claude/skills/<package-name>/
✓ Runtime: Node.js | Python
✓ Auth: <requirements>

Ready to use!

Package Selection Strategy

When both NPM and pip have options:

Prefer NPM if:

Official package with better TypeScript definitions
More downloads/active maintenance
Recently updated
Better documentation

Prefer pip if:

Python-only service or domain
Official SDK maintained by service
Better Python ecosystem integration

Ask user if:

Tie in quality
Different capabilities between versions

Always inform:

If alternative exists in other registry
Trade-offs of selected option

Registry APIs

NPM Registry

# Search
curl "https://registry.npmjs.org/-/v1/search?text=<query>&size=20"

# Package info
curl "https://registry.npmjs.org/<package-name>"

# Specific version
curl "https://registry.npmjs.org/<package-name>/<version>"

PyPI Registry

# Package info
curl "https://pypi.org/pypi/<package-name>/json"

# Search (no simple API, use web search or alternative)

Type Parsing Guide

NPM (TypeScript)

Parse .d.ts files for function signatures
Extract exported classes and interfaces
Look for JSDoc comments
Fall back to README examples if no types

pip (Python)

Parse .pyi type stub files
Extract docstrings from modules
Inspect function signatures
Fall back to README examples

Error Handling

Package not found:

Try alternative registry
Suggest similar names
Offer manual search

Install fails:

Check permissions
Verify network connection
Show error message
Suggest fixes

Package lacks types:

Warn user but proceed
Use README examples
Note limitations

Auth required but missing:

Prompt for credentials
Provide setup instructions
Don't proceed without auth

Example Workflow

User: "I need to work with Notion"

System execution:

Search NPM for "notion" → Found @notionhq/client
- Official package ✓
- TypeScript definitions ✓
- Weekly downloads: 300K ✓
Install: npm install @notionhq/client to ~/.claude/node_modules/
Analyze:
- Main export: Client
- Auth: Requires integration token
- Key methods: databases.query, pages.retrieve, etc.

Generate skill structure:

~/.claude/skills/notion/
├── SKILL.md
├── full-docs.md
└── metadata.json

Credential setup:

Get integration token: https://www.notion.so/my-integrations
Set: export CLAUDE_NOTION_TOKEN=your_token

Test and confirm:

✓ Learned @notionhq/client v2.2.3 (NPM)
✓ Skill: ~/.claude/skills/notion/
✓ Runtime: Node.js
✓ Auth: Set CLAUDE_NOTION_TOKEN

How Generated Skills Are Used

When a generated skill is invoked (e.g., /skill notion):

Skill tool loads ~/.claude/skills/notion/SKILL.md into context
Main context reads the skill documentation
Main context writes a script (e.g., notion-query.js)
Main context executes the script directly: node notion-query.js
Results returned immediately

No subagents - simple, fast, direct execution in main context.

Important Notes

Always install to ~/.claude/ (never project-specific)
Use subdirectory structure: skills/<package>/SKILL.md
Keep SKILL.md minimal (~20-30 lines) for context efficiency
Full documentation goes in full-docs.md
Test before confirming success
Inform user of alternatives in other registry
Document auth requirements clearly
Update version cache for all packages
Skills are documentation, execution is direct and simple

upskill

SKILL.md