@skillsmith/mcp-server 0.2.3 → 0.3.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@skillsmith/mcp-server",
-  "version": "0.2.3",
+  "version": "0.3.1",
   "description": "MCP server for Skillsmith skill discovery",
   "type": "module",
   "main": "./dist/src/index.js",
@@ -36,7 +36,8 @@
     }
   },
   "files": [
-    "dist"
+    "dist",
+    "src/assets"
   ],
   "license": "Elastic-2.0",
   "repository": {

package/src/assets/docs/USER_GUIDE.md

@@ -0,0 +1,192 @@
+# Skillsmith User Guide
+
+Welcome to Skillsmith, the skill discovery and management system for Claude Code.
+
+## Quick Start
+
+### 1. Configure MCP Server
+
+Add to `~/.claude/settings.json`:
+
+```json
+{
+  "mcpServers": {
+    "skillsmith": {
+      "command": "npx",
+      "args": ["-y", "@skillsmith/mcp-server"]
+    }
+  }
+}
+```
+
+### 2. Restart Claude Code
+
+Close and reopen your Claude Code session.
+
+### 3. Start Using
+
+Ask Claude:
+- "Search for testing skills"
+- "Install the commit skill"
+- "What skills do I have installed?"
+
+## What Gets Installed
+
+On first run, Skillsmith automatically installs essential skills:
+
+| Skill | Purpose |
+|-------|---------|
+| **varlock** | Secure environment variable management |
+| **commit** | Git commit message generation |
+| **governance** | Code quality enforcement |
+| **skill-builder** | Create custom skills |
+| **skillsmith** | This documentation |
+
+## Trust Tiers
+
+Always check the trust tier before installing skills:
+
+| Tier | Safety | Action |
+|------|--------|--------|
+| **Official** (Green) | Highest | Install freely |
+| **Verified** (Blue) | High | Install freely |
+| **Community** (Yellow) | Medium | Review first |
+| **Unverified** (Red) | Unknown | Careful review |
+
+### Quick Trust Check
+
+```
+"Show details for community/some-skill"
+```
+
+Look for:
+- Trust tier badge
+- Quality score (aim for 70+)
+- Number of stars
+- Days since published
+
+## Common Tasks
+
+### Search for Skills
+
+```
+"Find testing skills"
+"Search for devops skills with score above 80"
+"Find verified git workflow skills"
+```
+
+### Install a Skill
+
+```
+"Install community/jest-helper"
+"Install the commit skill"
+```
+
+### Compare Skills
+
+```
+"Compare jest-helper and vitest-helper"
+```
+
+### Get Recommendations
+
+```
+"Recommend skills for my React project"
+"What skills would help with this codebase?"
+```
+
+### Create a Custom Skill
+
+```
+"Create a skill for generating changelogs"
+```
+
+## Quota Limits
+
+| Tier | API Calls/Month | Price |
+|------|-----------------|-------|
+| Community | 1,000 | Free |
+| Individual | 10,000 | $9.99/mo |
+| Team | 100,000 | $25/user/mo |
+| Enterprise | Unlimited | $55/user/mo |
+
+Check your usage:
+```
+"What's my Skillsmith quota?"
+```
+
+Upgrade at: https://skillsmith.app/upgrade
+
+## Security Best Practices
+
+1. **Prefer Verified or Official skills** for important projects
+2. **Review Community skills** before installing
+3. **Never install Unverified skills** without manual review
+4. **Check the quality score** - aim for 70+
+5. **Report suspicious skills** to security@skillsmith.app
+
+## Where Skills Are Installed
+
+Skills install to: `~/.claude/skills/<skill-name>/`
+
+Each skill contains:
+- `SKILL.md` - Main skill file (Claude reads this)
+- Optional: `docs/`, `scripts/`, `templates/`
+
+## Troubleshooting
+
+### "Skill not found"
+
+The skill may not exist in the registry. Try:
+```
+"Search for similar-name"
+```
+
+### "Installation failed"
+
+Check:
+1. Internet connection
+2. Quota remaining
+3. Skill hasn't been blocklisted
+
+### "Security scan failed"
+
+The skill was blocked for security reasons. Try a different skill or contact support if you believe this is an error.
+
+### Quota Exceeded
+
+You've hit your monthly limit. Options:
+1. Wait until quota resets (1st of month)
+2. Upgrade your tier
+
+## Offline Usage
+
+Installed skills work offline. Only these operations require internet:
+- Searching for new skills
+- Installing skills
+- Getting recommendations
+
+## Updating Skillsmith
+
+```bash
+npx @skillsmith/mcp-server@latest
+```
+
+Or let it auto-update via npx.
+
+## Getting Help
+
+- **Documentation**: `npx @skillsmith/mcp-server --docs`
+- **Issues**: https://github.com/smith-horn/skillsmith/issues
+- **Support**: support@skillsmith.app
+- **Security**: security@skillsmith.app
+
+## License
+
+Skillsmith is licensed under **Elastic License 2.0**:
+- Self-hosting for internal use: Allowed
+- Modification for own use: Allowed
+- Offering as managed service: Not allowed
+- Circumventing license keys: Not allowed
+
+Full license: https://www.elastic.co/licensing/elastic-license

package/src/assets/skills/skillsmith/SKILL.md

@@ -0,0 +1,147 @@
+---
+name: "Skillsmith"
+description: "Discover, install, compare, and manage Claude Code skills. Use when searching for skills, evaluating quality, understanding trust tiers, checking quotas, or creating custom skills. Triggers: 'find skill', 'search skills', 'install skill', 'trust tier', 'create skill', 'skill quality', 'skill quota'."
+---
+
+# Skillsmith
+
+Skillsmith is your skill discovery and management system for Claude Code. It provides access to 500+ community skills with trust verification, quality scoring, and security scanning.
+
+## Quick Reference: MCP Tools
+
+| Tool | Use When | Example |
+|------|----------|---------|
+| `search` | Finding skills by keyword, category, or trust tier | "Find testing skills" |
+| `get_skill` | Getting full details about a specific skill | "Show details for community/jest-helper" |
+| `install_skill` | Installing a skill to ~/.claude/skills/ | "Install the commit skill" |
+| `uninstall_skill` | Removing an installed skill | "Uninstall jest-helper" |
+| `skill_recommend` | Getting contextual recommendations | "Recommend skills for my React project" |
+| `skill_validate` | Checking skill structure before manual install | "Validate this skill" |
+| `skill_compare` | Comparing 2-5 skills side-by-side | "Compare jest-helper and vitest-helper" |
+| `skill_suggest` | Getting suggestions based on current work | Automatic based on context |
+
+## Trust Tiers
+
+Skills are categorized by verification level:
+
+| Tier | Badge | Meaning | When to Trust |
+|------|-------|---------|---------------|
+| **Official** | Green checkmark | Published by Anthropic, fully reviewed | Always safe |
+| **Verified** | Blue checkmark | Verified publisher, 10+ stars, 30+ days old | Generally safe |
+| **Community** | Yellow | Passed security scan, has required metadata | Review before install |
+| **Unverified** | Red warning | No verification | Only if you trust the author |
+
+For detailed criteria, see [TRUST_TIERS.md](docs/TRUST_TIERS.md).
+
+## Quota System
+
+API calls are limited by tier:
+
+| Tier | API Calls/Month | Price |
+|------|-----------------|-------|
+| **Community** | 1,000 | Free |
+| **Individual** | 10,000 | $9.99/mo |
+| **Team** | 100,000 | $25/user/mo |
+| **Enterprise** | Unlimited | $55/user/mo |
+
+Warnings are shown at 80% and 90% usage. Upgrade at https://skillsmith.app/upgrade
+
+For details, see [QUOTAS.md](docs/QUOTAS.md).
+
+## Security Model
+
+Skillsmith operates as a security boundary between untrusted skill sources and your Claude Code environment.
+
+### What Skillsmith Validates
+
+Before any skill is installed, Skillsmith performs:
+
+1. **SKILL.md validation** - Must have valid YAML frontmatter with name and description
+2. **Security scan** - Checks for jailbreak patterns, suspicious URLs, sensitive file access
+3. **Typosquatting detection** - Warns if skill name is similar to known skills
+4. **Blocklist check** - Rejects known-malicious skills
+
+### What Skillsmith Cannot Prevent
+
+- Novel attack patterns not in our detection database
+- Social engineering in legitimate-looking instructions
+- Runtime behavior (skills execute with your permissions)
+
+**Recommendation**: Always review skill content before installation, especially for unverified skills.
+
+For the complete security model, see [SECURITY.md](docs/SECURITY.md).
+
+## Creating Skills
+
+The **skill-builder** skill (auto-installed) helps you create custom skills:
+
+```
+"Create a skill for generating API documentation"
+"Build a skill to automate code reviews"
+```
+
+The skill-builder guides you through:
+- YAML frontmatter (name ≤64 chars, description ≤1024 chars)
+- Progressive disclosure structure (4 levels)
+- Directory organization
+- Validation checklist
+
+## Search Examples
+
+```
+# Find all testing skills
+"Search for testing skills"
+
+# Find verified skills only
+"Find verified skills for git workflows"
+
+# Filter by quality score
+"Search for devops skills with score above 80"
+
+# Compare options
+"Compare jest-helper, vitest-helper, and mocha-helper"
+```
+
+## Common Tasks
+
+### Install a Skill
+```
+"Install the commit skill"
+```
+Skillsmith downloads the skill, runs security scan, and installs to ~/.claude/skills/.
+
+### Check What's Installed
+```
+"What skills do I have installed?"
+```
+
+### Remove a Skill
+```
+"Uninstall the old-skill"
+```
+
+### Get Recommendations
+```
+"Recommend skills for my TypeScript project"
+```
+Skillsmith analyzes your project context and suggests relevant skills.
+
+## License
+
+Skillsmith uses **Elastic License 2.0**:
+- You can self-host for internal use
+- You can modify for your own use
+- You cannot offer Skillsmith as a managed service to others
+- You cannot circumvent license key functionality
+
+## Related Documentation
+
+- [Security Deep-Dive](docs/SECURITY.md)
+- [Trust Tiers](docs/TRUST_TIERS.md)
+- [Quota System](docs/QUOTAS.md)
+
+## Getting Help
+
+- Docs: `npx @skillsmith/mcp-server --docs`
+- Issues: https://github.com/smith-horn/skillsmith/issues
+- Email: support@skillsmith.app

package/src/assets/skills/skillsmith/docs/QUOTAS.md

@@ -0,0 +1,182 @@
+# Quota System
+
+Skillsmith uses a usage-based quota system to ensure fair access and sustainable service.
+
+## Tier Limits
+
+| Tier | API Calls/Month | Price | Best For |
+|------|-----------------|-------|----------|
+| **Community** | 1,000 | Free | Individual hobbyists |
+| **Individual** | 10,000 | $9.99/mo | Active developers |
+| **Team** | 100,000 | $25/user/mo | Development teams |
+| **Enterprise** | Unlimited | $55/user/mo | Large organizations |
+
+## What Counts as an API Call
+
+Each of these operations counts as 1 API call:
+- `search` - Searching for skills
+- `get_skill` - Getting skill details
+- `install_skill` - Installing a skill
+- `uninstall_skill` - Removing a skill
+- `skill_recommend` - Getting recommendations
+- `skill_validate` - Validating a skill
+- `skill_compare` - Comparing skills
+- `skill_suggest` - Getting suggestions
+
+**Free operations** (don't count):
+- Viewing already-installed skills
+- Reading local skill files
+- Using installed skills
+
+## Quota Warnings
+
+Skillsmith provides progressive warnings as you approach your limit:
+
+| Usage | Level | What Happens |
+|-------|-------|--------------|
+| 80% | Info | Warning in tool response |
+| 90% | Warning | Warning + optional email |
+| 100% | Error | Operations blocked |
+
+### Example Warning at 80%
+
+```json
+{
+  "results": [...],
+  "_meta": {
+    "quota": {
+      "remaining": 200,
+      "limit": 1000,
+      "resetAt": "2026-02-01T00:00:00Z",
+      "warning": "80% of monthly quota used (200 remaining)"
+    }
+  }
+}
+```
+
+### At 100% (Blocked)
+
+```json
+{
+  "error": "QUOTA_EXCEEDED",
+  "message": "Monthly quota exceeded. Upgrade at skillsmith.app/upgrade",
+  "resetAt": "2026-02-01T00:00:00Z"
+}
+```
+
+## Checking Your Quota
+
+Ask Claude:
+```
+"What's my Skillsmith quota?"
+"How many API calls do I have left?"
+```
+
+Or check programmatically via the quota metadata in any response.
+
+## Quota Resets
+
+Quotas reset on the **first of each month** at 00:00 UTC.
+
+Example:
+- January 15: 800/1000 used
+- February 1: 0/1000 used (reset)
+
+Unused quota does not roll over.
+
+## Upgrading Your Tier
+
+### From Community to Individual ($9.99/mo)
+- 10x more API calls (10,000/month)
+- Priority support
+- Basic analytics dashboard
+
+```
+Upgrade at: https://skillsmith.app/upgrade?from=community&to=individual
+```
+
+### From Individual to Team ($25/user/mo)
+- 10x more API calls (100,000/month)
+- Team workspaces
+- Private skills
+- Usage analytics
+
+```
+Upgrade at: https://skillsmith.app/upgrade?from=individual&to=team
+```
+
+### From Team to Enterprise ($55/user/mo)
+- Unlimited API calls
+- SSO (SAML 2.0)
+- Role-based access control (RBAC)
+- Audit logging
+- SIEM integration
+- Dedicated support
+
+```
+Contact: sales@skillsmith.app
+```
+
+## Optimizing Quota Usage
+
+### Do
+- Cache search results when browsing
+- Use `get_skill` only for skills you're considering
+- Batch installations when possible
+
+### Don't
+- Run repeated searches for the same query
+- Call `skill_validate` multiple times on the same skill
+- Use `search` with overly broad queries
+
+### Efficient Patterns
+
+Instead of:
+```
+search("testing")  # 1 call
+search("testing jest")  # 2 calls
+search("testing vitest")  # 3 calls
+```
+
+Do:
+```
+search("testing", limit=20)  # 1 call, get more results
+```
+
+## Enterprise Considerations
+
+### Shared Quota (Team/Enterprise)
+- Quota is shared across all team members
+- Individual usage tracking available in dashboard
+- Admins can set per-user soft limits
+
+### Overage Protection
+- Hard block at 100% by default
+- Enterprise can enable overage billing
+- Overage rate: $0.001 per additional call
+
+### Audit Trail
+Enterprise tier includes full audit logging:
+- Who made each call
+- What skill was accessed
+- Timestamp and result
+
+## FAQ
+
+**Q: What happens if I hit my limit mid-project?**
+A: You can upgrade immediately. New quota applies instantly.
+
+**Q: Can I pre-pay for higher limits?**
+A: Contact sales@skillsmith.app for custom plans.
+
+**Q: Do local operations use quota?**
+A: No. Only Skillsmith API calls (search, install, etc.) use quota.
+
+**Q: Can I see my historical usage?**
+A: Individual+ tiers have a usage dashboard at skillsmith.app/usage.
+
+## Support
+
+- Billing questions: billing@skillsmith.app
+- Quota issues: support@skillsmith.app
+- Enterprise sales: sales@skillsmith.app

package/src/assets/skills/skillsmith/docs/SECURITY.md

@@ -0,0 +1,174 @@
+# Skillsmith Security Model
+
+This document provides detailed security information about how Skillsmith protects your Claude Code environment.
+
+## Security Boundaries
+
+```
+TRUSTED ZONE
+├── Claude model safety guardrails
+├── Claude Code runtime
+└── OS-level file access controls
+
+SEMI-TRUSTED ZONE (Skillsmith)
+├── Skill index (curated)
+├── Quality scoring
+├── Static analysis
+├── Trust tier verification
+└── Conflict detection
+
+UNTRUSTED ZONE
+├── GitHub repositories
+├── Third-party skill authors
+└── Community registries
+```
+
+## What Skillsmith Scans For
+
+### Critical Severity (Blocks Installation)
+
+**Jailbreak Patterns**
+- "ignore previous instructions"
+- "developer mode" / "DAN mode"
+- "bypass safety" / "bypass security"
+- "system: override"
+- "act as an AI without restrictions"
+
+**Malicious URLs**
+- Non-allowlisted external domains
+- Allowlist includes: github.com, githubusercontent.com, anthropic.com, claude.ai
+
+### High Severity (Requires Confirmation)
+
+**Suspicious URLs**
+- `file://` protocol (local file access)
+- `gopher://`, `dict://`, `ldap://` protocols
+- localhost / 127.0.0.x references
+- Private IP ranges (10.x.x.x, 192.168.x.x, 172.16-31.x.x)
+
+**Sensitive File Access Patterns**
+- `*.env*` files
+- `*.pem`, `*.key`, `*.p12` certificates
+- `*credentials*`, `*secrets*`, `*password*`
+- AWS credentials patterns
+
+**Dangerous Commands**
+- `rm -rf`, `format`, `delete`
+- `curl`, `wget` to unknown domains
+- `eval`, `exec` with dynamic input
+
+### Medium Severity (Warning)
+
+**Obfuscation Detection**
+- High entropy content (Shannon entropy > 4.5)
+- Possible base64 encoded payloads
+- Unusual character sequences
+
+**Permission Keywords**
+- References to sudo, root, admin
+- System modification commands
+
+## Threat Model
+
+| Threat | Severity | Mitigation | Status |
+|--------|----------|------------|--------|
+| Malicious SKILL.md | Critical | Pattern scanning, trust tiers | Active |
+| Prompt injection | Critical | Pattern detection, entropy analysis | Active |
+| Typosquatting | High | Levenshtein distance, char substitution | Active |
+| Dependency hijacking | Medium | URL allowlist | Active |
+| Author key compromise | Medium | Anomaly detection | Planned |
+| Supply chain attack | High | Registry signing | Planned |
+
+## Validation Patterns (Technical Detail)
+
+### SSRF Detection
+```
+file://, gopher://, dict://, ldap://
+localhost, 127.0.0.x
+10.x.x.x, 192.168.x.x, 172.16-31.x.x
+169.254.x.x (link-local)
+```
+
+### Path Traversal Detection
+```
+../, ..\
+..%2f, ..%5c (URL encoded)
+%2e%2e (double-encoded)
+```
+
+### Typosquatting Detection
+- Levenshtein distance ≤ 2 from known skill names
+- Character substitution (l/1, o/0, rn/m)
+- Homograph attacks (unicode lookalikes)
+
+## Best Practices
+
+### For Skill Users
+
+1. **Always check trust tier** before installing
+   - Official/Verified: Generally safe
+   - Community: Review skill content first
+   - Unverified: Only install if you trust the author personally
+
+2. **Review skill content** for unverified skills
+   - Read the SKILL.md body
+   - Check for suspicious URLs or commands
+   - Look for overly broad permissions
+
+3. **Use `skill_validate`** for manual installations
+   - Runs security scan before install
+   - Shows warnings and requires confirmation
+
+4. **Report suspicious skills**
+   - GitHub: https://github.com/smith-horn/skillsmith/security/advisories
+   - Email: security@skillsmith.app
+
+5. **Keep Skillsmith updated**
+   - New security patterns added regularly
+   - `npx @skillsmith/mcp-server@latest`
+
+### For Skill Authors
+
+1. **Avoid external URLs** unless necessary
+   - Prefer documented APIs (github.com, npm registry)
+   - Never reference internal/private URLs
+
+2. **Don't request sensitive file access**
+   - Never read .env files
+   - Never access credential stores
+
+3. **Be explicit about permissions**
+   - Document what files you read/write
+   - Document what commands you execute
+
+4. **Submit for verification**
+   - Verified skills get more installs
+   - Process documented at skillsmith.app/verify
+
+## Privacy Considerations
+
+Skillsmith respects your privacy:
+
+**Never sent to backend:**
+- Your codebase content
+- File paths or names
+- Environment variables
+- Credentials
+- Conversation content
+
+**Sent only with opt-in telemetry:**
+- Anonymized search queries
+- Skill install/uninstall events
+- Error rates (stack traces only)
+- Feature usage statistics
+
+## Reporting Security Issues
+
+**For vulnerabilities in Skillsmith itself:**
+- Email: security@skillsmith.app
+- GitHub Security Advisories: https://github.com/smith-horn/skillsmith/security/advisories
+
+**For malicious skills:**
+- Report via GitHub Issues
+- Include skill ID and specific concern
+- We investigate and blocklist within 24 hours