skills-but-for-dev

⚡ The Problem: LLM Knowledge Cutoff & Dead Repositories

When you ask Cursor, Claude Code, Antigravity, or Copilot:

"Build an AI meeting assistant that records audio, separates speakers, and generates summaries"

The model immediately starts writing code using libraries from its static pre-training data. Meanwhile:

• 💀 High-star repos might be dead: A project with 35,000 stars might have had zero commits in 18 months.

• 🚀 Breakout libraries remain invisible: The state-of-the-art voice model or fast audio engine released last month doesn't exist in the LLM's weights.

• ⚖️ Hidden licensing traps: Generating code that imports GPL-3.0 or CC-BY-NC-4.0 libraries can create major intellectual property and commercial liabilities.

• 💥 VRAM crashes: AI agents frequently recommend 14B parameter models on a local machine with only 8 GB of VRAM.

skills-but-for-dev fixes this. It acts as an autonomous pre-flight curator for your agent, querying live GitHub velocity, PyPI monthly adoption, and Hugging Face VRAM requirements before writing code.

Related MCP server: repo-scout

🥊 Before & After

🛠️ Key Capabilities

• Dual-Bucket Candidate Retrieval: Discovers proven industry leaders (stars:>500) alongside fast-rising breakout repositories (stars:75..3500, pushed $< 30$ days) without cannibalization.

• Real-World PyPI Production Adoption: Fetches real monthly download statistics via pypistats.org to protect against star-inflation and GitHub bots.

• Real-Time Star Velocity & Acceleration: Calculates 4-week moving average ($v_4$) and acceleration ratio ($v_4 / v_{12}$) in a single request.

• Dormant Spike Anomaly Detection: Flags suspicious repositories that were inactive for 6+ months and suddenly spiked in stars over a single week.

• Hardware VRAM Estimator: Accurate minimum VRAM baseline calculation across .safetensors, sharded model weights, Diffusers pipelines, and distinct GGUF quantization levels (Q4_K_M, Q8_0).

• Zero-Config GitHub Token Auto-Discovery: Seamlessly discovers existing GitHub CLI logins (gh auth token) or falls back to an adaptive, quota-conserving unauthenticated mode.

• Anti-Prompt-Injection Sanitizer: Strips malicious hidden markdown instructions, zero-width tags, and bloated YAML headers before context reaches your LLM.

• Sub-5ms SQLite WAL Cache: Deterministic, persistent local cache with automatic TTL expiration.

📋 Architecture & Data Flow

flowchart TD
    User["Developer Prompt\n'Build a RAG system for PDF invoices'"] --> Agent["AI Coding Agent\n(Cursor / Antigravity / Claude Code)"]
    Skill["SKILL.md"] -.->|"Decomposition Instructions"| Agent
    Agent -->|"1. search_github_repos('pdf parser')\n2. search_hf_models('embeddings')"| Server["skills-but-for-dev MCP Server"]

    subgraph Server_Internals["skills-but-for-dev Engine"]
        Server --> Norm["Query Normalizer\n(Noise stripping & Language filter)"]
        Norm --> GH["GitHub REST Client\n(Dual-Bucket search + Star Velocity)"]
        Norm --> HF["Hugging Face Client\n(VRAM & Pipeline Estimator)"]
        Norm --> PyPI["PyPI Stats Client\n(30-Day Download Verification)"]
        GH --> Scoring["Conservative Scoring Engine\n(80% Base + 10% Health + 10% PyPI)"]
        HF --> Scoring
        PyPI --> Scoring
        Scoring --> Cache[("SQLite Cache (WAL Mode)\n~4.7ms warm latency")]
    end

    Server -->|"Curated Architecture Recipe"| Agent
    Agent -->|"Step-by-step Tech Stack with Verified Licences"| User

🚀 Quickstart

1. Run Instantly with uvx (Zero Installation)

No cloning or virtual environment setup required. Works with any MCP-compatible client:

# Verify it runs and check diagnostics
uvx skills-but-for-dev ping

2. Configure in Your IDE

🔹 Cursor (.cursor/mcp.json)

{
  "mcpServers": {
    "skills-but-for-dev": {
      "command": "uvx",
      "args": ["skills-but-for-dev"],
      "env": {
        "GITHUB_TOKEN": "optional_your_pat_here"
      }
    }
  }
}

🔹 Antigravity / Gemini (mcp_config.json)

{
  "mcpServers": {
    "skills-but-for-dev": {
      "command": "uvx",
      "args": ["skills-but-for-dev"]
    }
  }
}

🔹 Claude Desktop (claude_desktop_config.json)

{
  "mcpServers": {
    "skills-but-for-dev": {
      "command": "uvx",
      "args": ["skills-but-for-dev"]
    }
  }
}

Tip: If you already use the GitHub CLI (gh), skills-but-for-dev automatically detects your authentication token via gh auth token. You don't even need to configure GITHUB_TOKEN manually!

💡 Example Agent Stack Recipe

When your agent uses skills-but-for-dev, it generates structured architecture recipes before writing code:

⚡ Performance & Evaluation Benchmarks

Benchmarked across realistic multi-layer agent scenarios using strict Ground Truth matching:

You can run the evaluation suite locally at any time:

python evals/run_evals.py

🧰 CLI Tools & Diagnostics

Inspect active tokens, cache paths, and server health directly from your terminal:

# Print active version
skills-but-for-dev --version

# Ping server and verify token discovery source (ENV vs GitHub CLI)
skills-but-for-dev ping

📖 Architecture Deep Dive

For mathematical formulas (star velocity moving averages, exponential recency decay, dormant spike detection ratios), see ARCHITECTURE.md.

📄 License

Distributed under the Apache License 2.0.