@skillsmith/cli 0.3.0 → 0.3.2

package/README.md

@@ -2,6 +2,19 @@
 
 Command-line interface for Skillsmith - discover, manage, and author Claude Code skills.
 
+## What's New in v0.3.1
+
+- **Database Fix**: Fixed "no such table: skills" error on fresh installations
+- **API Resilience**: Improved handling of partial API responses
+- **Import Improvements**: Better rate limiting (150ms default, configurable via `SKILLSMITH_IMPORT_DELAY_MS`)
+- **Python Support**: Added Python file detection (`.py`, `.pyi`, `.pyw`) to `analyze` command
+
+## What's New in v0.3.0
+
+- **Registry Sync**: Keep your local skill database up-to-date with `sync` command
+- **Auto-Sync**: Configurable daily/weekly background sync during MCP sessions
+- **Sync History**: Track sync operations with `sync history`
+
 ## What's New in v0.2.7
 
 - **MCP Server Scaffolding**: Generate TypeScript MCP servers with `author mcp-init`
@@ -27,6 +40,27 @@ Or use directly with npx:
 npx @skillsmith/cli search "testing"
 ```
 
+## Updating the CLI
+
+Check your current version:
+
+```bash
+skillsmith --version
+```
+
+Update to the latest version:
+
+```bash
+# If installed globally
+npm update -g @skillsmith/cli
+
+# Or reinstall to specific version
+npm install -g @skillsmith/cli@latest
+
+# Using npx always gets the latest
+npx @skillsmith/cli@latest sync
+```
+
 ## Command Alias
 
 The CLI provides two command names:
@@ -289,6 +323,85 @@ skillsmith import --topic claude-skill --max 500
 - `-d, --db <path>` - Database path
 - `-v, --verbose` - Verbose output
 
+### sync
+
+Synchronize your local skill database with the live Skillsmith registry.
+
+```bash
+# Sync skills from registry (differential - only changes)
+skillsmith sync
+
+# Force full sync (ignore last sync time)
+skillsmith sync --force
+
+# Preview what would be synced
+skillsmith sync --dry-run
+```
+
+**Options:**
+- `-f, --force` - Force full sync, ignore last sync timestamp
+- `--dry-run` - Preview changes without writing to database
+- `-d, --db <path>` - Database path
+- `--json` - Output results as JSON
+
+#### sync status
+
+Show sync status and statistics.
+
+```bash
+skillsmith sync status
+```
+
+**Output includes:**
+- Auto-sync enabled/disabled
+- Sync frequency (daily/weekly)
+- Last sync time
+- Next scheduled sync
+- Last run statistics
+
+#### sync history
+
+View sync operation history.
+
+```bash
+# Show recent sync history
+skillsmith sync history
+
+# Show more entries
+skillsmith sync history --limit 20
+```
+
+**Options:**
+- `-l, --limit <n>` - Number of history entries (default: 10)
+
+#### sync config
+
+Configure automatic sync settings.
+
+```bash
+# Show current configuration
+skillsmith sync config --show
+
+# Enable automatic background sync
+skillsmith sync config --enable
+
+# Disable automatic sync
+skillsmith sync config --disable
+
+# Set sync frequency
+skillsmith sync config --frequency daily
+skillsmith sync config --frequency weekly
+
+# Combine options
+skillsmith sync config --enable --frequency weekly
+```
+
+**Options:**
+- `--show` - Display current configuration
+- `--enable` - Enable automatic background sync
+- `--disable` - Disable automatic sync
+- `--frequency <freq>` - Set frequency: `daily` or `weekly`
+
 ## Configuration
 
 ### Environment Variables
@@ -296,6 +409,7 @@ skillsmith import --topic claude-skill --max 500
 | Variable | Description | Default |
 |----------|-------------|---------|
 | `SKILLSMITH_DB_PATH` | Database file location | `~/.skillsmith/skills.db` |
+| `SKILLSMITH_IMPORT_DELAY_MS` | Delay between GitHub API calls during import | `150` |
 | `GITHUB_TOKEN` | GitHub token for imports | - |
 
 ### Database Location
@@ -306,6 +420,34 @@ By default, the CLI uses `~/.skillsmith/skills.db`. Override with:
 SKILLSMITH_DB_PATH=/custom/path/skills.db skillsmith search "testing"
 ```
 
+## Privacy & Data Handling
+
+Skillsmith is designed with privacy as a core principle.
+
+### What Stays on Your Computer (Never Transmitted)
+
+| Data | Location | Purpose |
+|------|----------|---------|
+| Skill usage history | `~/.skillsmith/analytics.db` | Personal ROI tracking |
+| Time saved metrics | `~/.skillsmith/analytics.db` | Your productivity insights |
+| Value calculations | Computed locally | ROI dashboard |
+| Project context | Hashed locally | Anonymous grouping |
+
+**The ROI Dashboard feature is 100% local.** Your usage patterns, time saved, and value metrics never leave your computer. This data exists solely for your benefit.
+
+### What Is Transmitted (Required for Functionality)
+
+| Data | When | Why |
+|------|------|-----|
+| Search queries | When you search | To return matching skills |
+| Skill IDs | When viewing/installing | To fetch skill details |
+
+### Optional Telemetry (Opt-In)
+
+Anonymous product analytics (search counts, feature usage) are **opt-in only**. Telemetry is disabled by default and requires explicit configuration (`SKILLSMITH_TELEMETRY_ENABLED=true`).
+
+To run fully offline: Set `SKILLSMITH_OFFLINE_MODE=true` to disable all network calls.
+
 ## Examples
 
 ### Discover and Install Skills
@@ -385,6 +527,22 @@ skillsmith remove community/old-skill
 skillsmith search --interactive
 ```
 
+### Keep Skills Up-to-Date
+
+```bash
+# Sync with the live registry
+skillsmith sync
+
+# Check sync status
+skillsmith sync status
+
+# Enable daily auto-sync
+skillsmith sync config --enable --frequency daily
+
+# View sync history
+skillsmith sync history
+```
+
 ## License
 
 [Elastic License 2.0](https://www.elastic.co/licensing/elastic-license)

package/assets/skillsmith-skill/SKILL.md

@@ -0,0 +1,235 @@
+---
+name: "skillsmith"
+description: "Discover, install, compare, and manage Claude Code skills. Search the registry, get recommendations, validate skill quality, and manage your installed skills."
+version: "0.1.0"
+category: "productivity"
+tags:
+  - skills
+  - discovery
+  - registry
+  - mcp
+  - installation
+author: "Skillsmith"
+allowed-tools:
+  - mcp__skillsmith
+  - Bash
+---
+
+# Skillsmith Skill
+
+Discover, install, compare, and manage Claude Code skills through natural language.
+
+## Trigger Phrases
+
+- "search for skills", "find skills", "discover skills"
+- "install skill", "add skill"
+- "recommend skills", "suggest skills"
+- "compare skills"
+- "validate skill", "check skill"
+- "list installed skills", "show my skills"
+- "uninstall skill", "remove skill"
+- "skill details", "get skill"
+- "browse skills", "explore skills"
+- "high quality skills", "verified skills"
+
+## Slash Commands
+
+| Command | Description | Example |
+|---------|-------------|---------|
+| `/skillsmith search` | Search for skills by query or filters | `/skillsmith search testing` |
+| `/skillsmith install` | Install a skill from the registry | `/skillsmith install community/jest-helper` |
+| `/skillsmith recommend` | Get contextual skill recommendations | `/skillsmith recommend` |
+| `/skillsmith compare` | Compare multiple skills side-by-side | `/skillsmith compare jest-helper vitest-helper` |
+| `/skillsmith validate` | Validate a skill's structure | `/skillsmith validate ./my-skill` |
+| `/skillsmith list` | List all installed skills | `/skillsmith list` |
+| `/skillsmith uninstall` | Remove an installed skill | `/skillsmith uninstall jest-helper` |
+| `/skillsmith get` | Get detailed skill information | `/skillsmith get community/jest-helper` |
+
+## MCP Tool Delegation
+
+This skill delegates to the `mcp__skillsmith` MCP server for all operations. When the user requests skill-related actions, use the appropriate MCP tool.
+
+**Note:** The examples below show the tool parameters. Invoke these using Claude's standard MCP tool calling mechanism.
+
+### Search for Skills
+
+Use `mcp__skillsmith__search` with these parameters:
+- `query` (optional): Search term
+- `category` (optional): development, testing, devops, etc.
+- `trust_tier` (optional): verified, community, experimental
+- `min_score` (optional): Minimum quality score (0-100)
+- `limit` (optional): Max results (default 10)
+
+**Example:** Search for testing skills with quality score > 70
+```json
+{
+  "query": "testing",
+  "min_score": 70,
+  "limit": 10
+}
+```
+
+**Note:** Either `query` OR at least one filter (`category`, `trust_tier`, `min_score`) must be provided.
+
+### Get Skill Details
+
+Use `mcp__skillsmith__get_skill` with:
+- `id` (required): Skill ID in format `author/name`
+
+```json
+{ "id": "community/jest-helper" }
+```
+
+### Install a Skill
+
+Use `mcp__skillsmith__install_skill` with:
+- `id` (required): Skill ID
+- `force` (optional): Overwrite if exists
+
+```json
+{ "id": "community/jest-helper", "force": false }
+```
+
+### Uninstall a Skill
+
+Use `mcp__skillsmith__uninstall_skill` with:
+- `id` (required): Skill name
+
+```json
+{ "id": "jest-helper" }
+```
+
+### Get Recommendations
+
+Use `mcp__skillsmith__skill_recommend` with:
+- `context` (optional): Project context
+- `limit` (optional): Max recommendations
+
+```json
+{ "context": "React TypeScript project", "limit": 5 }
+```
+
+### Compare Skills
+
+Use `mcp__skillsmith__skill_compare` with:
+- `skill_ids` (required): Array of 2-5 skill IDs to compare
+
+```json
+{ "skill_ids": ["community/jest-helper", "community/vitest-helper"] }
+```
+
+### Validate a Skill
+
+Use `mcp__skillsmith__skill_validate` with:
+- `path` (required): Path to skill directory
+
+```json
+{ "path": "./my-skill" }
+```
+
+## Usage Examples
+
+### Example 1: Search and Install
+
+User: "Find testing skills for React"
+
+1. Search for skills using `mcp__skillsmith__search`:
+   ```json
+   { "query": "testing React" }
+   ```
+
+2. Present results to user with quality scores and trust tiers
+
+3. If user selects one, install using `mcp__skillsmith__install_skill`:
+   ```json
+   { "id": "community/react-testing-library-helper" }
+   ```
+
+### Example 2: Get Recommendations
+
+User: "What skills would help with this codebase?"
+
+1. Analyze current project context (package.json, file types, etc.)
+
+2. Get recommendations using `mcp__skillsmith__skill_recommend`:
+   ```json
+   { "context": "Node.js TypeScript API with Express" }
+   ```
+
+3. Present recommendations with explanations
+
+### Example 3: Compare Options
+
+User: "Compare jest-helper and vitest-helper"
+
+Use `mcp__skillsmith__skill_compare`:
+```json
+{ "skill_ids": ["community/jest-helper", "community/vitest-helper"] }
+```
+
+Present comparison table showing features, quality scores, trust tiers, etc.
+
+### Example 4: Browse by Category
+
+User: "Show me verified security skills"
+
+Use `mcp__skillsmith__search`:
+```json
+{ "category": "security", "trust_tier": "verified" }
+```
+
+### Example 5: Quality-Based Search
+
+User: "Find high-quality DevOps skills"
+
+Use `mcp__skillsmith__search`:
+```json
+{ "category": "devops", "min_score": 80 }
+```
+
+## Trust Tiers
+
+| Tier | Description | Badge |
+|------|-------------|-------|
+| `verified` | Official Anthropic or partner skills | Green |
+| `community` | Community-reviewed and approved | Yellow |
+| `experimental` | New or beta skills, use with caution | Red |
+
+## Quality Scores
+
+Quality scores (0-100) reflect skill quality based on:
+
+- Repository health (stars, forks, activity)
+- Documentation completeness
+- Code quality indicators
+- Community engagement
+
+Recommended minimum scores:
+- Production use: 70+
+- General use: 50+
+- Experimental: Any
+
+## CLI Fallback
+
+If the MCP server is unavailable, use the CLI directly:
+
+```bash
+# Search
+skillsmith search "testing" --tier verified
+
+# Install
+skillsmith install community/jest-helper
+
+# List installed
+skillsmith list
+
+# Remove
+skillsmith remove jest-helper
+```
+
+## Related Commands
+
+- `skillsmith analyze` - Analyze codebase for skill recommendations
+- `skillsmith sync` - Sync skills from registry
+- `skillsmith author init` - Create a new skill
+- `skillsmith author validate` - Validate skill structure