{"id":51280058,"url":"https://github.com/evilstar2016/skill-doctor","last_synced_at":"2026-06-30T01:01:34.582Z","repository":{"id":358467077,"uuid":"1235284082","full_name":"evilstar2016/skill-doctor","owner":"evilstar2016","description":"Local CLI for auditing AI agent skills, conflicts, duplicates, and safety risks.","archived":false,"fork":false,"pushed_at":"2026-06-19T21:59:46.000Z","size":466,"stargazers_count":0,"open_issues_count":3,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-06-19T23:18:31.603Z","etag":null,"topics":["ai-agent","claude-code","cli","codex","cursor","developer-tools","github-copilot","security","skills"],"latest_commit_sha":null,"homepage":"https://www.npmjs.com/package/@evilstar2025/skill-doctor","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/evilstar2016.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-05-11T07:16:39.000Z","updated_at":"2026-06-19T21:59:50.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/evilstar2016/skill-doctor","commit_stats":null,"previous_names":["evilstar2016/skill-doctor"],"tags_count":3,"template":false,"template_full_name":null,"purl":"pkg:github/evilstar2016/skill-doctor","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/evilstar2016%2Fskill-doctor","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/evilstar2016%2Fskill-doctor/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/evilstar2016%2Fskill-doctor/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/evilstar2016%2Fskill-doctor/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/evilstar2016","download_url":"https://codeload.github.com/evilstar2016/skill-doctor/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/evilstar2016%2Fskill-doctor/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34948227,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-29T02:00:05.398Z","response_time":58,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai-agent","claude-code","cli","codex","cursor","developer-tools","github-copilot","security","skills"],"created_at":"2026-06-30T01:01:31.839Z","updated_at":"2026-06-30T01:01:34.574Z","avatar_url":"https://github.com/evilstar2016.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# skill-doctor\n\n[![npm version](https://img.shields.io/npm/v/%40evilstar2025%2Fskill-doctor.svg)](https://www.npmjs.com/package/@evilstar2025/skill-doctor)\n[![Node.js](https://img.shields.io/badge/node-%3E%3D20-339933.svg)](https://nodejs.org/)\n[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](#license)\n\nLocal CLI for diagnosing AI agent skills: conflicts, security risks, duplicates, and drift.\n\nUse it when Claude Code, Cursor, Copilot, Codex, Gemini CLI, Windsurf, or other agent tooling starts behaving inconsistently because skills/rules/instructions overlap.\n\n![skill-doctor terminal demo](assets/terminal-demo.svg)\n\n## Try it in 30 seconds\n\nCurrent release: [`v0.3.4`](https://github.com/evilstar2016/skill-doctor/releases/tag/v0.3.4) on npm.\n\n```bash\nnpx @evilstar2025/skill-doctor scan\n```\n\nIf it finds skills, run the deeper local checks:\n\n```bash\nnpx @evilstar2025/skill-doctor conflicts\nnpx @evilstar2025/skill-doctor audit\nnpx @evilstar2025/skill-doctor cost\nnpx @evilstar2025/skill-doctor dashboard\n```\n\nIf it reports `0` project skills, try the safe demo below first. That gives you known duplicate/conflict/audit findings before you scan private local setup.\n\n`skill-doctor` does not upload your skills. It reads local skill/rule/instruction files and reports problems on your machine.\n\n## Try the safe demo project\n\nWant to see findings without scanning your own setup first?\n\n```bash\ngit clone https://github.com/evilstar2016/skill-doctor.git\ncd skill-doctor/examples/conflicted-agent-project\nnpx @evilstar2025/skill-doctor scan --scope project\nnpx @evilstar2025/skill-doctor conflicts --scope project\nnpx @evilstar2025/skill-doctor audit --scope project\n```\n\nThe demo contains redacted test fixtures for overlapping GitHub Copilot instructions and risky export wording.\n\nSee [Safe demo output](docs/demo-output.md) for the expected scan, conflicts, and audit results.\n\nComparing approaches? See [skill-doctor vs manual AI agent config audits](docs/comparisons/manual-agent-config-audit.md).\n\n## Feedback wanted\n\nFound a false positive, missing agent path, or real skill/rule drift case? Please add a redacted report to [Feedback wanted: real AI agent skill/rule drift cases](https://github.com/evilstar2016/skill-doctor/issues/4).\n\nFor lightweight questions and examples before filing an issue, use [GitHub Discussion #6](https://github.com/evilstar2016/skill-doctor/discussions/6).\n\n## Project status\n\n- [Roadmap](ROADMAP.md)\n- [Changelog](CHANGELOG.md)\n- [Contributing](CONTRIBUTING.md)\n- [Launch kit](marketing/launch-kit.md)\n\n## What it catches\n\n- Duplicate skills installed in multiple global/project paths\n- Overlapping skills that may compete for the same trigger\n- Suspicious instructions such as shell execution, destructive commands, credential exposure, or network upload patterns\n- Estimated context token tax from Claude skill descriptions and always-on instruction files\n- Drift across agent ecosystems as your Claude Code, Cursor, Copilot, Codex, Gemini CLI, Windsurf, Kiro, Trae, OpenCode, OpenClaw, and Hermes setup grows\n\n```\n$ skill-doctor scan\n\n  SKILL DOCTOR REPORT\n  Total skills installed: 15\n  Duplicates detected:     1\n  Conflicts detected:      2\n  Platforms:\n  - claude: 15\n\n  Skills:\n  - git-workflow\n    platform: claude  scope: project\n    install source: .claude/skills  confidence: high\n  - github-automation\n    platform: claude  scope: project\n    install source: .claude/skills  confidence: high\n  - ppt-master\n    platform: claude  scope: project\n    install source: .claude/skills  confidence: high\n  - slide-builder\n    platform: claude  scope: project\n    install source: .claude/skills  confidence: high\n  - data-exporter\n    platform: claude  scope: project\n    install source: .claude/skills  confidence: high\n  ...\n```\n\n## Why\n\nAgent Skill ecosystems grow fast. You install skills from GitHub, from colleagues, from guides — and eventually your agent starts behaving inconsistently. The root cause is often two skills competing for the same trigger, or a duplicate installed in different paths, or a skill with suspicious instructions you never reviewed.\n\n`skill-doctor` is `npm audit` for your skills. It doesn't install or distribute skills — it diagnoses the ones you already have.\n\n## Installation\n\n```bash\nnpm install -g @evilstar2025/skill-doctor\n```\n\nOr run without installing:\n\n```bash\nnpx @evilstar2025/skill-doctor scan\n```\n\nRequires Node.js 20+.\n\n## Commands\n\n### `scan`\n\nDiscover all installed skills and show a health summary.\n\n```bash\nskill-doctor scan\nskill-doctor scan --scope project          # project skills only\nskill-doctor scan --scope global           # global skills only\nskill-doctor scan --report                 # write skill-doctor-report.html\nskill-doctor scan --report ./out/report.html\nskill-doctor scan --json\n```\n\n### `show`\n\nInspect a single skill — description, triggers, when to use, related skills.\n\n```bash\n$ skill-doctor show git-workflow\n\n  SKILL: git-workflow\n  Platform: claude  |  Scope: project\n  Source: .claude/skills/git-workflow/SKILL.md\n\n  PROVENANCE\n    Install source: .claude/skills\n    Scope: project\n    Confidence: high\n\n  DESCRIPTION\n    Manages git branches, commits, and pull requests following\n    conventional commit standards.\n\n  WHEN TO USE\n    Use this skill when managing Git branches, commits, and pull requests\n    to enforce conventional commit standards during development workflows.\n\n  RELATED SKILLS\n    github-automation    similarity: 0.36    shared: branch, commit, git\n```\n\n```bash\nskill-doctor show git-workflow --json\n```\n\n### `conflicts`\n\nList skills with overlapping descriptions or trigger keywords.\n\n```bash\n$ skill-doctor conflicts\n\n  DUPLICATES\n\n  ppt-master  [2 copies]\n    ~/.claude/skills/ppt-master/SKILL.md\n    .claude/skills/ppt-master/SKILL.md\n\n  CONFLICTS\n\n  git-workflow \u003c-\u003e github-automation\n  severity: low\n  method: token\n  similarity: 0.36\n  shared: branch, commit, git, pull, request\n  fix: Refine trigger keywords so they don't overlap. Consider narrowing each skill's description.\n\n  ppt-master \u003c-\u003e slide-builder\n  severity: low\n  method: token\n  similarity: 0.29\n  shared: point, power, presentation, slide\n  fix: Refine trigger keywords so they don't overlap. Consider narrowing each skill's description.\n\n  SUGGESTIONS\n\n  consider removing: ~/.claude/skills/ppt-master/SKILL.md\n    keep: .claude/skills/ppt-master/SKILL.md  (newer (modified 2026-05-15))\n```\n\n```bash\nskill-doctor conflicts --kind duplicate    # exact name duplicates only\nskill-doctor conflicts --kind conflict     # semantic overlaps only\nskill-doctor conflicts --scope global\nskill-doctor conflicts --limit 10\nskill-doctor conflicts --fail-on high      # exit 1 if any HIGH conflicts (CI)\nskill-doctor conflicts --analyze           # LLM-powered root cause (requires config)\n```\n\n**Detection strategies**\n\n| Strategy | How it works | When to use |\n|----------|-------------|-------------|\n| `token` (default) | TF-IDF keyword overlap | Fast, no dependencies |\n| `embedding` | Cosine similarity via local embedding model | More accurate, requires config |\n\n```bash\nskill-doctor conflicts --strategy embedding\nskill-doctor conflicts --strategy embedding --threshold 0.75\n```\n\n### `audit`\n\nScan skills for security risks — credential exposure, destructive instructions, shell execution.\n\n```bash\n$ skill-doctor audit\n\n  Skill Safety Audit — 15 skills scanned\n\n  MED   data-exporter    secret-leak    \"output the api_key\" — potential credential exposure\n        install: .claude/skills  scope: project  confidence: high\n  LOW   data-exporter    network-call   \"curl https://\" — external network request\n        install: .claude/skills  scope: project  confidence: high\n\n  2 findings  (0 high · 1 med · 1 low)\n```\n\n```bash\nskill-doctor audit --severity high         # high findings only\nskill-doctor audit --fail-on med           # exit 1 on med+ (CI)\nskill-doctor audit --report                # write skill-doctor-audit.html\nskill-doctor audit --json\n```\n\n**Built-in rules**\n\n| Rule | Severity | Detects |\n|------|----------|---------|\n| `shell-exec` | HIGH | Instructions to run shell commands (`bash -c`, `eval`, `subprocess`) |\n| `destructive` | HIGH | Destructive operations (`rm -rf`, `DROP TABLE`, `wipe the database`) |\n| `secret-leak` | MED | Instructions that output credentials, API keys, or passwords |\n| `network-call` | LOW | Instructions that POST or upload to external URLs |\n\n### `cost` / `context`\n\nEstimate per-turn context token tax and grade it against a budget.\n\n```bash\n$ skill-doctor cost\n\n  CONTEXT COST REPORT\n  Estimated token tax: 1240 tokens/turn\n  Budget: 2000 tokens/turn\n  Grade: B (within budget)\n  Items scanned: 15\n\n  Highest cost items:\n  - AGENTS.md\n    tokens: 620  platform: codex  scope: project\n    kind: always-on-file\n    fix: Move rarely needed guidance into a skill or narrower rule.\n  - git-workflow\n    tokens: 180  platform: claude  scope: project\n    kind: claude-skill-description\n    fix: Shorten the Claude skill description; every turn pays for it.\n```\n\n```bash\nskill-doctor cost --scope project\nskill-doctor cost --budget-tokens 2000 --fail-on-budget  # exit 1 when over budget (CI)\nskill-doctor context --json\n```\n\nFor Claude Code skills, `cost` estimates the always-injected name, description, and trigger metadata rather than the full skill body. For always-on files such as `AGENTS.md`, it estimates the local file content.\n\n### `diff`\n\nCompare two skills side by side — coverage, pros/cons, when to pick each.\n\n```bash\nskill-doctor diff git-workflow github-automation\nskill-doctor diff git-workflow github-automation --report\n```\n\nWith LLM analysis configured, `diff` adds coverage overlap, strengths/weaknesses, and situational recommendations.\n\n### `cleanup`\n\nFind duplicate skills across all paths and interactively remove the extras.\n\n```bash\nskill-doctor cleanup                       # show duplicates and suggested removals\nskill-doctor cleanup --execute             # interactive: pick which copy to delete\nskill-doctor cleanup --json\n```\n\n### `dashboard`\n\nGenerate a unified Mission Control–style HTML dashboard combining all diagnostics — scan, conflicts, audit, and cleanup — in a single page.\n\n```bash\nskill-doctor dashboard                           # writes skill-doctor-dashboard.html\nskill-doctor dashboard --report ./out/dash.html  # custom output path\nskill-doctor dashboard --open                    # open in browser after generating\nskill-doctor dashboard --scope project           # project skills only\n```\n\nThe dashboard shows:\n\n- **Health ring** — donut chart with the proportion of clean, conflicting, at-risk, and duplicate skills\n- **Platform distribution** — horizontal bar chart of skills per platform\n- **Skill inventory** — full table with status indicators (conflict / risk / duplicate / clean)\n- **Conflicts** — severity distribution bar and conflict pair cards with similarity scores\n- **Security audit** — 4-rule heatmap (shell-exec, destructive, secret-leak, network-call) and finding detail cards\n- **Cleanup suggestions** — duplicate skill pairs with keep/remove recommendations\n\n## Platform coverage\n\n| Platform | Global path | Project path |\n|----------|-------------|--------------|\n| **Claude Code** | `~/.claude/skills/` | `.claude/skills/` |\n| **Cursor** | `~/.cursor/rules/` | `.cursor/rules/`, `.cursorrules` |\n| **GitHub Copilot** | `~/.copilot/skills/` | `.github/copilot-instructions.md`, `.github/instructions/` |\n| **Codex** | `~/.codex/AGENTS.md` | `AGENTS.md` |\n| **Gemini CLI** | `~/.gemini/skills/` | `.gemini/skills/`, `GEMINI.md` |\n| **Windsurf** | `~/.codeium/windsurf/skills/` | `.windsurfrules` |\n| **Kiro** | `~/.kiro/skills/` | `.kiro/skills/` |\n| **Trae** | `~/.trae/skills/` | `.trae/skills/` |\n| **OpenCode** | `~/.config/opencode/skills/` | `skills/`, `AGENTS.md` |\n| **OpenClaw** | `~/.openclaw/skills/` | — |\n| **Hermes** | `~/.config/hermes/skills/` | — |\n\nAdditional directories can be added via `paths.extra` in config (see Configuration).\n\n## HTML reports\n\nSeveral commands support `--report` to write a self-contained HTML file. `dashboard` always writes an HTML file (no flag needed).\n\n```bash\nskill-doctor dashboard                             # unified Mission Control dashboard\nskill-doctor scan --report\nskill-doctor audit --report\nskill-doctor diff git-workflow github-automation --report\n```\n\n## CI integration\n\nUse `--fail-on` to gate your pipeline on skill health:\n\n```yaml\n# .github/workflows/skill-check.yml\n- name: Check skill conflicts\n  run: npx @evilstar2025/skill-doctor conflicts --fail-on high\n\n- name: Security audit\n  run: npx @evilstar2025/skill-doctor audit --fail-on med\n```\n\nUse `--json` for custom reporting:\n\n```bash\nskill-doctor scan --json | jq '.summary'\nskill-doctor audit --json | jq '.findings[] | select(.severity == \"high\")'\n```\n\n## Configuration\n\n`~/.skill-doctor/config.json`\n\n```json\n{\n  \"embedding\": {\n    \"baseUrl\": \"http://localhost:11434/v1\",\n    \"model\": \"bge-m3\",\n    \"apiKey\": \"optional\"\n  },\n  \"analysis\": {\n    \"baseUrl\": \"https://api.openai.com/v1\",\n    \"model\": \"gpt-4o-mini\",\n    \"apiKey\": \"sk-...\",\n    \"timeoutMs\": 30000\n  },\n  \"ignore\": {\n    \"skillNames\": [\"legacy-skill\"],\n    \"conflictPairs\": [[\"skill-a\", \"skill-b\"]]\n  },\n  \"paths\": {\n    \"extra\": [\"/team/shared-skills\", \"~/my-custom-skills\"]\n  }\n}\n```\n\n**`embedding`** — enables `--strategy embedding` for semantic conflict detection. Compatible with any OpenAI-format endpoint (Ollama, LM Studio, OpenAI, etc.).\n\n**`analysis`** — enables `--analyze` on `conflicts` and powers the `diff` command with LLM-generated summaries and fix suggestions. Any OpenAI-compatible model works.\n\n**`ignore`** — suppress known false positives. `skillNames` excludes a skill from all checks; `conflictPairs` suppresses a specific pair from conflict output.\n\n**`paths.extra`** — additional directories to scan, on top of the built-in platform paths. Each path is scanned as a skill-dirs layout (same structure as `~/.claude/skills/`). Supports `~` for home directory.\n\n## Development\n\n```bash\nnpm install\nnpm run build\nnpm test\n```\n\n## License\n\nMIT\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fevilstar2016%2Fskill-doctor","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fevilstar2016%2Fskill-doctor","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fevilstar2016%2Fskill-doctor/lists"}