skill1ssue: Find the Right Skill

Autonomous multi-platform skill discovery. Check local skills and cache first, then launch parallel crawlers across git forges with stealth anti-bot protection. Deduplicate, rank, and present results in 5 contextual response modes.

Overview

8 Platforms: GitHub, GitLab, Codeberg, Gitea, Forgejo, Moltbook, Bitbucket, SourceHut

5 Response Modes: Quick Discovery, Structured Comparison, Domain Exploration, Deep Analysis, Zero-Result

Quick Start

# Search across all platforms (8 forges)
python3 scripts/swarm_orchestrator.py "pdf processing" --platforms all --max-workers 6

# Search with quality filters (min 10 stars, fetch descriptions)
python3 scripts/swarm_orchestrator.py "data viz" --min-stars 10 --fetch-descriptions --max-results 20

# Scrape a single platform
python3 scripts/platform_scraper.py github "data visualization"

# Scrape with license detection and star filter
python3 scripts/platform_scraper.py gitlab "api docs" --min-stars 5 --detect-license

# Check cached results
python3 scripts/state_manager.py --query "pdf processing"

# Cache management
python3 scripts/state_manager.py --stats           # Show cache stats
python3 scripts/state_manager.py --prune --age-hours 48  # Remove stale entries
python3 scripts/state_manager.py --clear-cache       # Clear all cache

# Dry run (show what would be searched)
python3 scripts/swarm_orchestrator.py "testing" --platforms all --dry-run

# Save results to file instead of stdout
python3 scripts/swarm_orchestrator.py "pdf processing" --platforms all --output results.json

# List supported platforms
python3 scripts/platform_scraper.py --list-platforms
python3 scripts/swarm_orchestrator.py --list-platforms

Example workflow:

User: "I need a skill that generates charts from CSV data"
  → Check local: ls /app/.agents/skills/ | grep -i chart
  → Check cache: python3 scripts/state_manager.py --query "chart csv"
  → Swarm search: python3 scripts/swarm_orchestrator.py "chart csv" --platforms all --min-stars 5
  → Deduplicate by full_name, rank by stars × weight × description_bonus × license_bonus
  → Present: Mode 1 (Quick) if 1-2 matches, Mode 2 (Comparison) if 3+

Architecture

User Query
  |
  ├─> [Phase 0: Fast Path] ──Hit?──> Return immediately
  |       Local skills → Cache → Registry
  |       Miss?
  ├─> [Phase 1: Swarm] ──Parallel platform search
  |       GitHub + GitLab + Codeberg (Tier 1)
  |       Gitea + Forgejo + Moltbook (Tier 2, if needed)
  |       Bitbucket + SourceHut (Tier 3, if needed)
  |       Web search fallback (if all fail)
  |
  ├─> [Phase 2: Fallback Chain] ──If swarm empty
  |       Web search → Browser visit → Repo download → Raw file probe
  |
  ├─> [Phase 3: Processing]
  |       Deduplicate → Categorize → Rank → Cache → Present
  |
  └─> [Phase 4: Output] ──5 contextual modes

Skill Integration Points

Phase 0: Fast Path (Always First)

Check Local Skills

# Search built-in skills
ls /app/.agents/skills/ | grep -i <keyword>

# Search user skills
ls /app/.user/skills/ | grep -i <keyword>

If match found, read SKILL.md and present immediately. No search needed.

Check Cache

python3 scripts/state_manager.py --query "<keyword>"

Checks ~/.kimi/skill1ssue/result_cache.json with 24h TTL. On hit, return cached results.

Phase 1: Swarm Search (Parallel)

Tier 1 (Always)

Tier 2 (If Tier 1 < 5 results)

Tier 3 + Fallback (If Tier 2 < 3 results)

Orchestrate All Tiers

# Full sweep (Tier 1-3 + fallback)
python3 scripts/swarm_orchestrator.py "<query>" --platforms all --max-workers 8

# Tier 1 only (fastest)
python3 scripts/swarm_orchestrator.py "<query>" --platforms github gitlab codeberg --max-workers 3

Anti-Bot Handling

Note: playwright-stealth.js and playwright-simple.js are not bundled. Activate the /playwright-scraper-skill or /fast-browser-use skills when anti-bot protection is encountered. See Skill Integration Points above.

Phase 2: Fallback Chain

If swarm yields no results, try in order:

1. Web search — web_search with site:github.com agent skill <query>
2. Browser visit — browser_visit platform search pages + browser_find
3. Download full repo — curl -L -o skill.zip "https://github.com/{user}/{repo}/archive/main.zip"
4. Raw file probe (last resort) — https://raw.githubusercontent.com/{user}/{repo}/main/SKILL.md

Phase 3: Result Processing

Ranking Formula

score = (stars + 1) × platform_weight × description_bonus × license_bonus

description_bonus = 1.3 if description present, else 1.0
license_bonus     = 1.1 if license detected, else 1.0

Results are auto-cached by the orchestrator after each successful search (24h TTL). Use --no-cache to skip caching.

Deduplication

Merge by full_name (owner/repo). Keep entry with highest star count.

Caching

The swarm orchestrator auto-caches results after each successful search (24h TTL). Manual cache operations:

# Check if results were cached
python3 scripts/state_manager.py --query "<your search query>"

# Manually cache a results file
python3 scripts/state_manager.py --cache-results results.json

Cache stored at ~/.kimi/skill1ssue/result_cache.json with atomic writes and file locking for concurrent access safety.

Phase 4: Output (5 Response Modes)

Select mode by result count and query intent:

Mode 1: Quick Discovery (1-2 results)

## Recommendation: {skill-name}

**Verdict**: {skill-name} is the best match for "{query}".

**Why it fits**: {2-3 sentence rationale linking user's need to skill capabilities}

**Install**: Download the full repo:
```bash
curl -L -o skill.zip "{repo-zip-url}" && unzip -q skill.zip

Also found: {secondary skill} — worth considering if {specific condition}.

### Mode 2: Structured Comparison (3+ results)

Skill Comparison for "{query}"

Found {N} skills across {P} platforms. Organized by primary purpose:

{Category A} -- {description of what this category addresses}

{Category B} -- {description}

Head-to-Head: Top Candidates

Activate /weighted-scorer with criteria: Feature Fit, Ecosystem Maturity, Maintenance Burden, License, Security Posture.

python3 /path/to/decision_matrix.py --json '{...}'

### Mode 3: Domain Exploration (5+ broad results)

{Domain} Skill Landscape

Found {N} skills across {P} platforms. The ecosystem has {observation}.

Core Capabilities

These handle the primary workflow:

• {skill} ({platform} ★{stars}) -- {what it does}. {why it stands out}
• {skill} ({platform} ★{stars}) -- {what it does}. {why it stands out}

Specialized / Niche

These address specific sub-problems:

• {skill} ({platform} ★{stars}) -- {narrow purpose}. Use when: {condition}

Emerging / Experimental

Lower maturity but worth watching:

• {skill} ({platform} ★{stars}) -- {promise}. Risk: {why not ready}

Ecosystem Notes

• Coverage gap: {what no skill addresses yet}
• Most active: {which skill has recent commits}
• Safest bet: {highest maturity + stars + description quality}
• Next step: Narrow query to one category, or use /deep-research

### Mode 4: Deep Analysis (complex evaluation)

Skill Deep Analysis: "{query}"

Search Summary

• Platforms searched: {P} (health: {rates})
• Skills found: {N} (after dedup: {M})
• Cache status: {fresh/cached/stale}

Per-Skill Assessment

{Skill A} -- {platform} ★{stars}

Trade-off Analysis

Recommendation

{clear verdict with confidence level and rationale}

Install

curl -L -o skill.zip "{repo-zip-url}" && unzip -q skill.zip

### Mode 5: Zero-Result Response

No Skills Found for "{query}"

Searched: {platforms}. Cache: {checked}. Registry: {queried}.

Why: {too niche? wrong keywords? new domain?}

Try:

1. Rephrase: "{query}" → "{alternative}"
2. Broaden: Search "{broader category}" instead
3. Deep research: Activate /deep-research to map the domain
4. Create your own: Use /skill-creator

### Response Rules (all modes)

1. Never output flat numbered lists — always categorize or compare
2. Every skill must have a one-line fit annotation
3. Show provenance: which platform, cached or fresh
4. Surface gaps: note what no skill addresses
5. End with concrete next step: install, compare, research, or create

## Persistent State

Managed by `scripts/state_manager.py`:

| File | Purpose | TTL |
|------|---------|-----|
| `~/.kimi/skill1ssue/search_history.json` | Last 500 queries | Permanent |
| `~/.kimi/skill1ssue/result_cache.json` | Cached results | 24h |
| `~/.kimi/skill1ssue/skill_registry.json` | All discovered skills | Permanent |

```python
from state_manager import StateManager
sm = StateManager()

# Cache management
stats = sm.cache_stats()          # {"entries": 12, "total_results": 340, ...}
removed = sm.prune_cache(48)      # Remove entries older than 48h
sm.clear_cache()                  # Clear all cached results

# Similar query lookup
similar = sm.get_similar_queries("current query")

Troubleshooting

Edge Cases

Edge Case: All platforms down. Every scraper fails. Fall back to web search exclusively. Cache result as [status: degraded — web-only results].

Edge Case: Query matches 10+ skills. Switch to Mode 3 (Domain Exploration) automatically. Cluster by capability domain. Surface top 3 per cluster.

Edge Case: Skill has no description. Extracted from README or skip. Rank with description_bonus = 1.0 instead of 1.3. Flag as [description: inferred].

Edge Case: Private repository. Scraper returns 404. Skip silently. Do not expose existence of private repos.

Edge Case: Rate limit on all platforms. Back off exponentially: 30s → 60s → 120s. After 3 failures, return cached results with [status: stale — rate limited].

When NOT to Use

Decline or defer when:

• User wants to browse without a goal — skill discovery needs a problem or keyword, not idle browsing
• User asks for pirated/proprietary skills — only discover publicly available, open-source skills
• Query is for a specific skill already known — direct them to install instead of searching
• Network is completely unavailable — cache check still works, but fresh search is impossible

Confidence Calibration

• High: Phase 0 (local skills) — deterministic file system check
• High: Phase 1 (swarm) — reliable for popular skills on GitHub/GitLab
• Medium: Phase 2 (fallbacks) — web search quality varies
• Medium: Ranking formula — heuristic, not ground truth
• Low: Mode 4 (Deep Analysis) — requires judgment on skill quality

Iteration Guidance

After presenting results:

1. User may refine query — re-run Phase 0 (cache) then Phase 1 if needed
2. User may ask "which one?" — activate /weighted-scorer for structured comparison
3. User may want details on one skill — download full repo, read SKILL.md + bundled resources
4. If no skill fits — offer /deep-research to map domain, then /skill-creator to build one
5. Update cache with user feedback (relevant/irrelevant flags) to improve future rankings

Cache Management

The state manager stores data in ~/.kimi/skill1ssue/:

Cache TTL is 24 hours by default. Prune weekly to prevent bloat.

Script Reference

Resources

• Script details (when to use each script, key flags): See ## Script Reference above
• Platform details (URLs, anti-bot levels, rate limits, forge-specific gotchas): references/platforms.md — load when configuring scraper for a new forge
• Query patterns (templates by search intent, advanced operator syntax): references/search_queries.md — load when user's query is vague and needs reformulation