97b427831a
Open-source marketplace for AI Agent skills. Features: - Next.js 15 web app with i18n (en/fa) - CLI tool for skill installation (npx skillhub) - GitHub crawler/indexer with multi-strategy discovery - Security scanning for all indexed skills - Self-hostable with Docker Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
94 lines
3.5 KiB
Markdown
94 lines
3.5 KiB
Markdown
# Claim System
|
|
|
|
## Overview
|
|
|
|
The claim system allows users to:
|
|
1. **Add Skills**: Request to add their GitHub repositories containing SKILL.md files
|
|
2. **Remove Skills**: Request to remove their skills from SkillHub (auto-approved for verified owners)
|
|
|
|
## Add Skill Flow
|
|
|
|
### User Actions
|
|
1. Sign in with GitHub OAuth
|
|
2. Navigate to `/claim#add`
|
|
3. Enter GitHub repository URL
|
|
4. Optionally provide reason for adding the skill
|
|
5. Submit request
|
|
|
|
### Backend Processing
|
|
1. Validate GitHub URL format
|
|
2. Check if repository exists and is public
|
|
3. Scan repository for SKILL.md files (recursive auto-scan)
|
|
4. Create pending add request in database
|
|
5. Send confirmation email ONLY if skills found (`skillCount > 0`)
|
|
|
|
### Email Behavior
|
|
- **Skills found**: Email sent with count
|
|
- **No skills found**: No email sent (manual review needed, user notified on screen)
|
|
|
|
### Success States
|
|
- **1 skill found**: "SKILL.md was found and will be indexed soon"
|
|
- **Multiple skills**: "Found N skills that will be indexed soon"
|
|
- **No skills**: "No SKILL.md found - repository will be reviewed manually. You will receive an email if skills are approved for indexing."
|
|
|
|
### Field Requirements
|
|
- **Repository URL**: Required
|
|
- **Reason**: Optional (defaults to "No reason provided")
|
|
|
|
## Remove Skill Flow
|
|
|
|
### User Actions
|
|
1. Sign in with GitHub OAuth
|
|
2. Navigate to `/claim#remove`
|
|
3. Enter skill ID (format: `owner/repo/skill-name`)
|
|
4. Optionally provide reason for removal
|
|
5. Submit request
|
|
|
|
### Backend Processing
|
|
1. Verify skill exists in database
|
|
2. Verify user owns the repository (via GitHub API)
|
|
3. Auto-approve and block skill from indexing
|
|
4. Send confirmation email
|
|
|
|
### Field Requirements
|
|
- **Skill ID**: Required
|
|
- **Reason**: Optional (defaults to "No reason provided")
|
|
|
|
## Error Handling
|
|
|
|
| Error Code | Message | Trigger |
|
|
|------------|---------|---------|
|
|
| `INVALID_URL` | Invalid GitHub URL | Malformed URL |
|
|
| `INVALID_REPO` | Repository not found or not accessible | 404 from GitHub or private repo |
|
|
| `RATE_LIMIT_EXCEEDED` | GitHub API rate limit exceeded | 403 with rate limit header |
|
|
| `NETWORK_TIMEOUT` | Request timed out | Timeout during validation |
|
|
| `ALREADY_PENDING` | Pending request exists | Duplicate request |
|
|
| `NOT_OWNER` | Not repository owner | Ownership verification failed (remove only) |
|
|
| `SKILL_NOT_FOUND` | Skill not in database | Skill ID doesn't exist (remove only) |
|
|
| `GITHUB_ERROR` | GitHub verification failed | General GitHub API error |
|
|
| `INVALID_SKILL` | Invalid GitHub info | Skill missing repo data |
|
|
|
|
## Implementation Notes
|
|
|
|
### Key Features
|
|
- **Auto-scan**: Entire repository is scanned recursively for all SKILL.md files
|
|
- **No manual path input**: Removed confusing "Skill Path" field
|
|
- **Optional reasons**: Users don't have to explain their requests
|
|
- **Conditional emails**: Only send when skills are actually found
|
|
- **Bilingual**: Full support for English and Farsi (RTL)
|
|
- **Specific errors**: Each edge case has a clear, actionable error message
|
|
|
|
### Technical Details
|
|
- **API Routes**: `/api/skills/add-request` and `/api/skills/removal-request`
|
|
- **Component**: `ClaimForm.tsx` with tab-based UI
|
|
- **i18n**: Uses next-intl for translations
|
|
- **Email**: Resend library with bilingual templates
|
|
- **Security**: CSRF protection, GitHub OAuth verification
|
|
|
|
### Recent Improvements (Feb 2026)
|
|
- ✅ Fixed email logic to only send when skills found
|
|
- ✅ Made reason fields optional
|
|
- ✅ Removed confusing skill path field
|
|
- ✅ Improved success messages for different states
|
|
- ✅ Added specific error messages for rate limits, timeouts, and private repos
|