{
  "markdown": "# auto-skill-finder\n\n**Universal AI skill router with dual-mode discipline.** Send a prompt — right skill loads automatically, correct mode activates: **ponytail** for code (lazy senior dev, YAGNI), **caveman** for chat (terse prose). No `/skill` commands. No manual selection. Works with Claude Code, Codex, Cursor, OpenCode, Gemini CLI, and any agent that reads `SKILL.md` or `AGENTS.md`.\n\nCuts response tokens ~65–75%. Zero accuracy loss. Zero config.\n\n---\n\n## What it does\n\nEvery prompt you send:\n\n1. **Detects intent** — code or chat? (rule-based, no API, instant)\n2. **Activates mode** — ponytail-code (lazy senior dev, YAGNI) or caveman-chat (terse prose)\n3. **Scans** all installed skills across all your AI agents\n4. **Scores** each skill against your prompt (name match, trigger keywords, description overlap)\n5. **Loads** the best match silently — no announcement, no friction\n6. **Compresses** skill content before injecting it (saves input tokens)\n7. **Responds** in the active mode\n\nNo configuration. No flags. Fires on every message.\n\n---\n\n## Dual-mode: ponytail-code vs caveman-chat\n\nAuto-detects which mode to use based on your prompt. No manual switching needed.\n\n### ponytail-code (auto-activates for code tasks)\n\nLazy senior developer discipline — [ponytail](https://github.com/DietrichGebert/ponytail). The best code is the code never written:\n\n```\nPrompt: \"fix the auth bug in my middleware\"\n\n→ Climbs the YAGNI ladder: reuse codebase → stdlib → native platform → installed dep → one line\n→ Fixes root cause, not symptom — one guard in the shared function, not one per caller\n→ Shortest working diff — after understanding the problem fully\n→ No unrequested abstractions, no scaffolding \"for later\"\n→ Output: code first, then max 3 lines (what skipped, when to add)\n```\n\nTriggers: fix, debug, implement, build, refactor, write code, error, bug, stacktrace, migration, API, endpoint, test, deploy…\n\n### caveman-chat (auto-activates for everything else)\n\nTerse prose only. No engineering overhead.\n\n```\nPrompt: \"explain how JWT works\"\n\n→ Drops articles, filler, pleasantries, hedging\n→ Fragments OK. Short synonyms.\n→ Full sentences when needed for clarity\n→ Intensity: lite / full (default) / ultra\n```\n\nTriggers: explain, what is, how does, summarize, compare, tell me, plan, strategy…\n\n### Detection logic\n\n![Detection flow](docs/detection-flow.svg)\n\nCode signals: file extensions, code blocks (```), error messages, stack traces, verbs like fix/debug/implement/refactor.\nChat signals: \"explain\", \"what is\", \"how does\", \"summarize\", question phrases.\n\nTurn off: `stop ponytail` / `stop caveman` or `normal mode`.\n\n---\n\n## Token savings\n\n| Source | Reduction |\n|--------|-----------|\n| Route to 1 skill vs loading all | ~95% of skill context skipped |\n| Inline prose compression (no API) | ~10–50% off injected skill content |\n| Caveman response mode | ~65–75% off AI responses |\n\n---\n\n## Install\n\n### One-liner (recommended)\n\n**macOS / Linux / WSL / Git Bash:**\n```bash\ncurl -fsSL https://raw.githubusercontent.com/prantikmedhi/auto-skill-finder/main/install.sh | bash\n```\n\n**Windows (PowerShell 5.1+):**\n```powershell\nirm https://raw.githubusercontent.com/prantikmedhi/auto-skill-finder/main/install.ps1 | iex\n```\n\nClones to `~/.auto-skill-finder`, auto-detects installed agents, wires hooks. Takes effect next session.\n\n### Install for one agent only\n\n```bash\n# bash\nAUTO_SKILL_ONLY=claude curl -fsSL https://raw.githubusercontent.com/prantikmedhi/auto-skill-finder/main/install.sh | bash\n\n# PowerShell\n$env:AUTO_SKILL_ONLY=\"claude\"; irm https://raw.githubusercontent.com/prantikmedhi/auto-skill-finder/main/install.ps1 | iex\n```\n\nSupported values: `claude`, `cursor`, `gemini`, `opencode`, `codex`, `cline`.\n\n### Update existing install\n\n```bash\nAUTO_SKILL_UPDATE=1 curl -fsSL https://raw.githubusercontent.com/prantikmedhi/auto-skill-finder/main/install.sh | bash\n```\n\n### Manual (any agent)\n\nCopy `SKILL.md` content into your agent's system prompt, rules file, or instructions. Copy `AGENTS.md` for agents that auto-discover it (OpenCode, Copilot).\n\n---\n\n## No slash commands needed\n\nAfter install, **just talk normally.** The AI agent finds and loads the right skill by itself — and picks the right mode.\n\n```\n❌ Old way:  /github-pr review this diff\n✅ New way:  review my pull request          → ponytail-code activates\n\n❌ Old way:  /docker-compose generate postgres setup\n✅ New way:  set up postgres with docker     → ponytail-code activates\n\n❌ Old way:  /stripe-integration add subscription billing\n✅ New way:  add stripe subscription to my app  → ponytail-code activates\n\n❌ Old way:  /jest write unit tests for this function\n✅ New way:  write unit tests for this function  → ponytail-code activates\n\n❌ Old way:  /sql-optimizer fix this slow query\n✅ New way:  this query is slow, fix it      → ponytail-code activates\n\n❌ Old way:  /linear create a bug ticket\n✅ New way:  create a bug ticket for this issue  → caveman-chat activates\n```\n\nNo `/commands`. No memorizing skill names. No manual invocation.\nRouter scores every installed skill against your prompt, picks the winner, activates the right mode — all silently.\nIf no skill matches, agent answers normally — no errors, no interruption.\n\n---\n\n## How skill routing works\n\nScoring (max 22 points per skill):\n\n| Points | Condition |\n|--------|-----------|\n| +10 | Prompt names the skill explicitly |\n| +5 each (max 15) | Trigger keyword match |\n| +1 each (max 7) | Description word overlap |\n\nThresholds:\n- **≥ 12** → auto-execute, no announcement\n- **5–11** → load skill, one-line note\n- **< 4** → fallback to general AI behavior\n\nSkills discovered from: `~/.claude/skills/`, `~/.claude/plugins/`, `~/.cursor/skills/`, `~/.config/opencode/skills/`, `~/skills/`, current directory.\n\n---\n\n## Build skill index (optional, faster routing)\n\nPre-index all your skills for instant lookup:\n\n```bash\npython3 scripts/build_index.py\n# writes ~/.claude/auto-skill-index.json\n```\n\nRe-run after installing new skills.\n\n---\n\n## Compress files with caveman (full LLM compression)\n\nFor compressing large markdown files (CLAUDE.md, todo lists, memory files) using Claude API:\n\n```bash\npython3 scripts/cli.py path/to/file.md\n```\n\n- Compresses natural language prose into caveman format\n- Preserves all code blocks, URLs, headings exactly\n- Saves original backup to `~/.local/share/caveman-compress/backups/`\n- Validates output before writing (auto-retries up to 2x)\n\nRequires `ANTHROPIC_API_KEY` or `claude` CLI in PATH.\n\n---\n\n## Scripts reference\n\n| Script | Purpose | API needed |\n|--------|---------|------------|\n| `scripts/skill_finder.py` | Core routing engine | No |\n| `scripts/detect_intent.py` | Code vs chat classifier (per-prompt) | No |\n| `scripts/inline_compress.py` | Rule-based prose compression (runs in hook) | No |\n| `scripts/prompt_analyzer.py` | Intent and entity extraction | No |\n| `scripts/build_index.py` | Build searchable skill index cache | No |\n| `scripts/detect.py` | Classify file as natural language vs code | No |\n| `scripts/validate.py` | Verify compression preserved structure | No |\n| `scripts/compress.py` | Full LLM-based caveman compression | Yes (Claude) |\n| `scripts/cli.py` | CLI for compress.py | Yes (Claude) |\n\n---\n\n## Modes\n\nAlways active. Two modes, auto-selected per prompt.\n\n**caveman-chat** (explanations, Q&A, planning):\n```\nNot: \"Sure! I'd be happy to help you with that...\"\nYes: \"JWT = signed token. Header.Payload.Signature. Server verify signature, no DB lookup needed.\"\n```\n\n**ponytail-code** (code tasks):\n```\nNot: writes a cache class with factory, interface, and config file\nYes: \"@lru_cache(maxsize=1000) on the fetch function. Skipped custom\n     cache class, add when lru_cache measurably falls short.\"\n```\n\nTurn off: `stop ponytail` / `stop caveman` or `normal mode`.\nIntensity (chat): `caveman lite`, `caveman ultra`.\n\n---\n\n## Supported agents\n\n| Agent | Mechanism | Auto-activates |\n|-------|-----------|----------------|\n| Claude Code | Hooks + skill | Yes |\n| Cursor | `.cursor/rules/` MDC file | Yes |\n| Gemini CLI | Extension via `gemini-extension.json` | Yes |\n| OpenCode | `AGENTS.md` auto-discovery | Yes |\n| Codex | `~/.codex/system-prompt.md` append | Yes |\n| Cline | `.clinerules/` file | Yes |\n| Copilot | `AGENTS.md` at repo root | Yes |\n| Others | Paste `SKILL.md` into system prompt | Manual |\n\n---\n\n## File structure\n\n```\nauto-skill-finder/\n├── SKILL.md              ← AI routing instructions (single source of truth)\n├── AGENTS.md             ← OpenCode / Copilot / Cursor auto-discovery\n├── GEMINI.md             ← Gemini CLI extension context\n├── CLAUDE.md             ← Claude Code project rules\n├── gemini-extension.json ← Gemini extension manifest\n├── package.json\n├── install.sh            ← Shell installer shim\n├── bin/\n│   └── install.js        ← Multi-agent installer\n├── hooks/\n│   ├── SessionStart.js       ← Caveman flag + system context\n│   └── UserPromptSubmit.js   ← Per-prompt routing + mode detection\n├── skills/\n│   ├── ponytail-code/SKILL.md ← Code mode: lazy senior dev, YAGNI ladder\n│   └── caveman-chat/SKILL.md  ← Chat mode: terse prose only\n├── config/\n│   └── agent-paths.json  ← Agent-specific skill dir config\n└── scripts/\n    ├── skill_finder.py       ← Core discovery engine\n    ├── detect_intent.py      ← Code vs chat classifier\n    ├── inline_compress.py    ← Rule-based compressor (no API)\n    ├── prompt_analyzer.py    ← Intent extraction\n    ├── build_index.py        ← Skill index cache\n    ├── detect.py             ← File type detection\n    ├── validate.py           ← Compression validator\n    ├── compress.py           ← LLM-based caveman compressor\n    └── cli.py                ← CLI entry point\n```\n\n---\n\n## Requirements\n\n- Node.js ≥ 18 (for installer and hooks)\n- Python 3.10+ (for routing scripts)\n- Claude Code, Cursor, Gemini CLI, OpenCode, or Codex installed\n\nFor LLM-based file compression: `ANTHROPIC_API_KEY` or `claude` CLI authenticated.\n\n---\n\n## Uninstall\n\n```bash\nnode bin/install.js --uninstall\n```\n\nRemoves hooks from `~/.claude/settings.json` and deletes hook files.\n\n---\n\n## License\n\nMIT\n",
  "bytes": 10092,
  "sha": "23c6384379c55b059a32ed07164ac9a4778f25c91728385e23da5dffe4d3eb21",
  "repo_slug": "prantikmedhi/auto-skill-finder",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/plg_prantikmedhi_auto_skill_finder_c06ae4bd/readme"
}