{"id":51004904,"url":"https://github.com/ievo-ai/skills","last_synced_at":"2026-06-20T19:30:32.709Z","repository":{"id":358462620,"uuid":"1241446028","full_name":"ievo-ai/skills","owner":"ievo-ai","description":"iEvo — self-evolving plugin for Claude Code. Capture lessons, patch local agents and skills, replay logs on upstream updates.","archived":false,"fork":false,"pushed_at":"2026-06-14T11:02:56.000Z","size":869,"stargazers_count":0,"open_issues_count":50,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-06-14T12:26:15.812Z","etag":null,"topics":["agent-skills","claude-code","claude-plugin","evolution","ievo","self-improving"],"latest_commit_sha":null,"homepage":null,"language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ievo-ai.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","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":"AGENTS.md","dco":null,"cla":null}},"created_at":"2026-05-17T11:59:21.000Z","updated_at":"2026-06-14T10:54:34.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/ievo-ai/skills","commit_stats":null,"previous_names":["ievo-ai/skills"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/ievo-ai/skills","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ievo-ai%2Fskills","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ievo-ai%2Fskills/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ievo-ai%2Fskills/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ievo-ai%2Fskills/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ievo-ai","download_url":"https://codeload.github.com/ievo-ai/skills/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ievo-ai%2Fskills/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34583589,"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-20T02:00:06.407Z","response_time":98,"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":["agent-skills","claude-code","claude-plugin","evolution","ievo","self-improving"],"created_at":"2026-06-20T19:30:29.676Z","updated_at":"2026-06-20T19:30:32.700Z","avatar_url":"https://github.com/ievo-ai.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# iEvo — Self-Evolving Plugin for AI Coding Agents\n\n\u003e ⚠️ **Alpha** — iEvo is in active early development (current line: `v0.6.x`). The pipeline works end-to-end and individual skills are tested, but APIs, file layouts, and behaviour can change between minor versions. Pin to a specific `marketplace.json` version if you need stability. v1.0 will be the first stable release.\n\n\u003e Discover relevant skills + agents for your project, audit them via senior-security-engineer review (deep content scan + threat modeling, no owner-based trust shortcuts), install with project-scope portability. Capture lessons as overlays that survive upstream updates. Works on Claude Code, Codex, and any platform that supports the [agentskills.io](https://agentskills.io) standard.\n\niEvo is a **universal discovery + safety + evolution layer** on top of [skills.sh](https://www.skills.sh) and the multi-platform agent skills ecosystem.\n\n**Currently distributed via:**\n- Claude Code marketplace (`.claude-plugin/marketplace.json`)\n- Codex marketplace (`.codex-plugin/marketplace.json`)\n- skills.sh registry (planned for v1.0)\n\n**Cross-platform skills** inside the plugin are portable via the [agentskills.io specification](https://agentskills.io/specification) — adopted by Claude Code, Cursor, Codex, Copilot, Gemini CLI, Goose, Junie, and 30+ other agent platforms. Platform-specific bits (slash commands, sub-agents via Task tool) work on Claude Code and Codex.\n\n## Quick start\n\n### Claude Code\n\n```bash\n# 1. Install iEvo plugin (zero prereqs — v0.6.0 dropped the find-skills install step)\n/plugin marketplace add ievo-ai/skills\n/plugin install ievo@ievo-skills\n/reload-plugins\n\n# 2. Initialize in your project\ncd \u003cyour-project\u003e\n/ievo:init\n```\n\n**v0.6.0**: discovery now happens via our own `discover.mjs` script hitting `https://skills.sh/api/search` directly — no more manual `npx skills add` step required.\n\n### Codex (CLI / app / VS Code extension)\n\n```bash\n# 1. Add the iEvo marketplace\n/plugins add ievo-ai/skills\n\n# 2. Install\n/plugins install ievo@ievo-skills\n\n# 3. Initialize in your project\ncd \u003cyour-project\u003e\n/ievo:init\n```\n\nCodex support added in v0.3.3 — same plugin content, separate marketplace manifests (`.claude-plugin/marketplace.json` vs `.codex-plugin/marketplace.json`).\n\n**Cross-platform skills inside the plugin** are fully portable via [agentskills.io](https://agentskills.io) spec. Slash commands and sub-agents work on Claude Code; Codex's own command/agent semantics may differ — refer to your platform's docs for exact behavior of the commands.\n\n`/ievo:init` will ask you to add Bash permissions for `gh` commands on first run — say yes (`Add to .claude/settings.local.json` recommended) to avoid each network call needing manual approval.\n\nThat's it. Interactive interview, security checks, install. Then `/reload-plugins` to activate.\n\n### Permission pre-setup (optional, skips the prompt)\n\nIf you want to set permissions before running `/ievo:init`, add to `.claude/settings.local.json` (per-user, gitignored — recommended) or `.claude/settings.json` (team-shared, committed):\n\n```json\n{\n  \"permissions\": {\n    \"allow\": [\n      \"Bash(gh api*)\",\n      \"Bash(gh search*)\"\n    ]\n  }\n}\n```\n\nWithout these, Claude Code's auto-mode classifier blocks each `gh api` call as \"untrusted network command\" — works but with manual Allow prompts. (v0.6.0 dropped the previously-required `npx skills` permission since discovery now happens via local Node script.)\n\n## The pipeline\n\n`/ievo:init` composes 6 stages (v0.6.0+):\n\n```\ndiscover.mjs (ours, parallel skills.sh API queries)\n    ↓\nindex-repos (ours, parallel repo-indexer sub-agents)\n    ↓\ncategorical rank — top-5 per category\n    ↓\ninterview (per candidate — AskUserQuestion)\n    ↓\nsecurity-auditor (parallel sub-agents, antivirus deep scan)\n    ↓\ninstall (project-scope vendor or plugin)\n```\n\n1. **discover.mjs** queries `https://skills.sh/api/search` in parallel — one request per language / dep / category / framework / stack-specific compound query. Heuristics inherited from find-skills SKILL.md (trusted owners reputation boost, install thresholds, category seed queries, synonym fallback) encoded directly in the script. Wall-clock ~3-6 seconds.\n2. **index-repos** scans the FULL content of every unique repo from step 1 — finds plugins, agents, hooks, commands. Uses shallow `git clone --depth=1` into `~/.ievo/checkouts/` (one network op per repo, then filesystem scan — no API rate limits). Sub-agents run in parallel — wall-clock = slowest repo (~30-60s).\n3. **categorical rank** groups candidates by category (testing, linting, security, observability, etc.) and keeps top-5 per category instead of overall top-12. Every relevant category gets visibility.\n4. **security-auditor** sub-agents run in parallel — one per selected item. Each runs as a senior application security engineer with domain expertise (prompt injection, credential exfiltration, supply-chain compromise, hook abuse, indirection attacks). Reads FULL content of every file shipped with the item + all dependencies. Wall-clock ~10-15s for 5-7 items.\n5. **install** runs two paths (project-scope, copy + source SHA metadata):\n   - **Vendor** (skills + agents): `gh api repos/\u003cowner\u003e/\u003crepo\u003e/contents/\u003cpath\u003e?ref=\u003csha\u003e` → Write tool → `.claude/\u003ctype\u003e/` → inject overlay marker → record source repo + commit SHA in `.ievo/evolution/\u003cscope\u003e/\u003cname\u003e.md` for `/ievo:update` to track upstream changes\n   - **Plugin install** (anything with hooks/MCP/commands): edit `.claude/settings.json` `extraKnownMarketplaces` + `enabledPlugins` for team-portable activation\n\n## Commands \u0026 Skills\n\n### Skills (auto-activatable, cross-platform via agentskills.io)\n\n| Skill | What it does |\n|-------|--------------|\n| `/ievo:init` | Full pipeline: discover, audit, install |\n| `/ievo:evolution \"\u003clesson\u003e\"` | Capture a lesson — append to overlay file. Never modifies agent/skill body. |\n| `/ievo:feedback` | Submit bug/idea/skip-reasons as GitHub issue |\n| `/ievo:debug-on` | Enable verbose / trace-level logging for the iEvo pipeline |\n| `/ievo:debug-off` | Disable verbose logging and finalize the debug session |\n| `/ievo:hooks-setup` | Configure Claude Code lifecycle hooks for iEvo pipeline events (init complete, security RED, evolution captured) |\n| `/ievo:overlay-status` | List active evolution overlays in this project, grouped by scope (Project / agents / skills) with last-modified dates |\n| `/ievo:index-repos` | Standalone: enumerate a repo (callable on its own) |\n| `/ievo:security-check` | Standalone: audit a specific skill/agent/plugin |\n\n### Commands (strictly explicit, Claude Code-specific)\n\n| Command | What it does |\n|---------|--------------|\n| `/ievo:uninstall` | Remove markers from CLAUDE.md/AGENTS.md and `.claude/agents/`, `.claude/skills/`. Preserves `.ievo/`. |\n| `/ievo:update` | Refresh vendored agent/skill files from upstream. Re-inject markers. Overlay files untouched. |\n\n## The overlay model\n\nUnder v0.2.0, **agent and skill files are never modified by evolution**. Lessons accumulate in separate **overlay files**, read live at every dispatch.\n\nWhen you vendor an agent (via `/ievo:init`) or evolve it (via `/ievo:evolution`):\n\n1. **Local file** (`.claude/agents/\u003cname\u003e.md`) gets a ONE-TIME marker block right after its frontmatter:\n   ```markdown\n   \u003c!-- ievo:start --\u003e\n   **Before applying the instructions below**, read `.ievo/evolution/agents/\u003cname\u003e.md` if it exists, and apply ALL rules from its sections IN ADDITION to the instructions below.\n   \u003c!-- ievo:end --\u003e\n   ```\n2. **Overlay file** (`.ievo/evolution/agents/\u003cname\u003e.md`) holds the accumulated rules:\n   ```markdown\n   ---\n   source:\n     repo: wshobson/agents\n     path: plugins/python-development/agents/python-pro.md\n     commit_sha: a1b2c3d4\n     fetched_at: 2026-05-18T10:00:00Z\n   ---\n\n   # python-pro — Evolution Overlay\n\n   ## 2026-05-19 14:32 UTC — Check git status before commit\n   **Trigger:** user-observed mistake during code review\n\n   Always check `git status` before commits to avoid orphaned files.\n   ```\n\nWhen the agent is dispatched, Claude reads both files automatically — the agent body's instructions and the overlay's accumulated rules.\n\n**Why this matters:**\n- Upstream updates are trivial: `/ievo:update` re-fetches the file and re-injects the marker. Overlay rules continue applying.\n- No drift, no Opus replay loop, no patches accumulating in the agent body.\n- Overlay file is the **single source of truth** for evolution. Easy to audit, easy to share via git.\n\n## Project-side layout\n\nAfter `/ievo:init` with some skills/agents vendored and some plugins installed:\n\n```\n\u003cyour-project\u003e/\n├── CLAUDE.md                        # (if first project-wide evolution recorded — gets marker block)\n├── .claude/\n│   ├── settings.json                # NEW: plugin marketplaces + enabledPlugins (commit for team sync)\n│   ├── agents/\n│   │   └── python-pro.md            # vendored, has overlay marker\n│   └── skills/\n│       └── changelog/\n│           └── SKILL.md             # vendored, has overlay marker\n└── .ievo/\n    ├── evolution/                   # COMMIT to git — project's evolution state\n    │   ├── project.md\n    │   ├── agents/\n    │   │   └── python-pro.md        # overlay file — actual rules live here\n    │   └── skills/\n    │       └── changelog.md\n    ├── cache/                       # GITIGNORE — re-derivable\n    │   └── index/\n    │       └── wshobson-agents.md\n    └── log/                         # GITIGNORE — local diagnostic\n        └── init-20260518-093613.md\n```\n\n`/ievo:init` adds the right `.gitignore` entries automatically if your project has a `.gitignore`.\n\n## Security model (v0.5.2 — senior-security-engineer vulnerability assessment)\n\n**Reputation is not security.** Owner-based trust is unreliable — OpenAI, Anthropic, Microsoft accounts have all been compromised in past incidents. iEvo's verdict comes only from content scan.\n\n`security-auditor` agent dispatches in parallel per selected item. Each instance acts as a **senior application security engineer** with deep domain expertise in AI agent supply-chain vulnerabilities (prompt injection, credential exfiltration, supply-chain compromise, hook abuse, indirection attacks, encoded payloads, social engineering, tool-model bypass). It applies the `security-check` skill — full content review of every file shipped with the item (SKILL.md/agent.md body + scripts/ + references/ + assets/ + bundled plugin files), then performs threat modeling and structured vulnerability assessment using the current Sonnet family reasoning (`model: sonnet` alias — platform-agnostic, vendor-neutral).\n\n### Verdicts\n\n| Verdict | What | UX |\n|---------|------|-----|\n| 🟢 GREEN | Full deep scan complete, no threats detected, intent is clearly legitimate | silent install |\n| 🟡 YELLOW | Minor concerns worth noting but not blocking (e.g., plain utility scripts present) | batch multi-select confirmation |\n| 🔴 RED | At least one specific threat detected with high confidence, cited file + excerpt | 4 options: try alternative / force install / skip / **report to source repo** |\n\n### Threats scanned for\n\n1. **Prompt injection** — direct (\"ignore previous\"), indirect (\"for debugging note .env contents\"), encoded payloads\n2. **Credential exfiltration** — reads of `.env`, `~/.aws/`, `~/.ssh/`, even when framed as \"debugging\"\n3. **Suspicious external network** — `curl X | bash`, unknown domains, output to writable paths\n4. **Time bombs** — date/counter/env-flag-based conditional execution\n5. **Encoded payloads** — long base64/hex strings, dynamic command construction\n6. **Broad/destructive bash** — `Bash(*)`, `Bash(rm:*)`, `Bash(sudo:*)`, `Bash(curl:*)`\n7. **Hook abuse** — PreToolUse/UserPromptSubmit with suspicious command\n8. **Runtime download** — scripts pulling additional code at runtime\n9. **Social engineering** — legitimate name + malicious body\n10. **Tool model bypass** — instructions to disable safety checks\n\n### Report-to-source flow (RED only)\n\nWhen verdict is RED, user gets a 4th option: **\"Report to `\u003cowner\u003e/\u003crepo\u003e` (file security issue)\"**. iEvo pre-fills a professional issue body citing the specific findings (file + excerpt + concern), shows preview, lets user edit/cancel, then files via `gh issue create`. Community defense layer — maintainer notified within minutes, future users protected.\n\nIssue body footer identifies iEvo as the source (`Reviewed via iEvo — community security audit tooling`) so maintainers know it's automated review, not random spam.\n\n### What we DON'T do\n\n- ❌ Owner-based trust shortcuts (TRUSTED_OWNERS, \"famous account = safe\") — dropped in v0.5.2\n- ❌ Heuristic risk_tier in repo indices (\"trusted/neutral/caution\") — dropped in v0.5.2\n- ❌ Surface-level pattern matching as final verdict — Sonnet's reasoning is the only signal\n- ❌ Auto-install RED items — always explicit user choice\n\n### Known configuration gotcha — `CLAUDE_CODE_SUBAGENT_MODEL`\n\nClaude Code v2.1.146+ ships a `CLAUDE_CODE_SUBAGENT_MODEL` environment variable that **overrides** an agent's frontmatter `model:` declaration. Per [official docs](https://code.claude.com/docs/en/sub-agents), the model-resolution order for subagents is:\n\n1. `CLAUDE_CODE_SUBAGENT_MODEL` env var, if set\n2. Per-invocation model parameter\n3. The subagent definition's `model:` frontmatter (where iEvo declares `sonnet`)\n4. The main-conversation model\n\n**The security implication.** iEvo's `security-auditor` agent declares `model: sonnet` precisely because Sonnet-tier reasoning is required to catch indirection attacks (\"Haiku is insufficient\", per `security-check/SKILL.md`). If an operator sets `CLAUDE_CODE_SUBAGENT_MODEL` to any Haiku-tier value (`haiku`, or a pinned `claude-haiku-...` ID) for cost or speed, the security scan silently runs at Haiku reasoning — degrading the entire security guarantee without any visible warning.\n\n**Mitigation**: either (a) leave `CLAUDE_CODE_SUBAGENT_MODEL` unset (frontmatter wins), or (b) set it to a vendor-neutral Sonnet/Opus alias (`sonnet` / `opus`) when needed for specific subagent classes. Do NOT set it to a Haiku-tier value in any environment running `/ievo:init`. The env var first appears in Claude Code release notes at v2.1.146 (May 2026); it may have been added earlier without changelog mention. No equivalent Codex env var is documented yet (May 2026); this note will update when one ships.\n\n## Install paths\n\niEvo supports two install paths per candidate:\n\n### Vendor (skills + agents)\n\n- `gh api` fetches the source file/directory.\n- Writes to `.claude/\u003ctype\u003e/\u003cname\u003e/` in your project.\n- Injects the overlay marker.\n- Creates `.ievo/evolution/\u003cscope\u003e/\u003cname\u003e.md` with source metadata frontmatter.\n- **No hooks, no MCP, no commands** come along — just the agent/skill content.\n- Best for: pulling specific agents/skills without committing to a whole plugin.\n\n### Plugin install (anything with hooks / MCP / commands)\n\n- Edits `.claude/settings.json` `extraKnownMarketplaces` + `enabledPlugins`.\n- Settings file is committed to git → team gets prompt to trust folder → plugin auto-installs for them too.\n- Brings everything: agents, skills, commands, hooks, MCP servers.\n- Best for: plugins where the value is the integration (hooks intercepting workflows, MCP servers, slash commands).\n\nThe interview at `/ievo:init` step 7b asks per candidate: vendor specific items OR install whole plugin OR skip.\n\n## Repository structure\n\n```\nievo-ai/skills/\n├── .claude-plugin/\n│   ├── plugin.json\n│   └── marketplace.json\n└── plugins/ievo/\n    ├── .claude-plugin/plugin.json\n    ├── commands/\n    │   ├── uninstall.md\n    │   └── update.md\n    ├── skills/\n    │   ├── init/SKILL.md           # /ievo:init — orchestrator\n    │   ├── evolution/SKILL.md      # /ievo:evolution — overlay capture\n    │   ├── feedback/SKILL.md       # /ievo:feedback — file GitHub issues\n    │   ├── debug-on/SKILL.md       # /ievo:debug-on — enable verbose session logging\n    │   ├── debug-off/SKILL.md      # /ievo:debug-off — disable verbose session logging\n    │   ├── hooks-setup/SKILL.md    # /ievo:hooks-setup — configure lifecycle hooks\n    │   ├── overlay-status/SKILL.md # /ievo:overlay-status — list active evolution overlays\n    │   ├── index-repos/SKILL.md    # /ievo:index-repos — enumerate a repo\n    │   └── security-check/SKILL.md # /ievo:security-check — audit a candidate\n    ├── agents/\n    │   ├── evolution.md            # sub-agent dispatched by evolution skill\n    │   ├── repo-indexer.md         # parallel dispatch — one per repo for indexing (Step 6)\n    │   └── security-auditor.md     # parallel dispatch — one per selected item for audit (Step 8)\n    └── scripts/\n        ├── discover.mjs            # skills.sh API discovery (parallel queries)\n        ├── scan_repo.mjs           # deterministic repo scanner (Node, no LLM)\n        ├── validate_agents.mjs     # vendor-neutral model: frontmatter validator\n        └── tests/                  # node:test suites + fixtures (100% coverage gate)\n```\n\n## Standards compliance\n\n- Plugin format: Claude Code-native + Codex-native (dual marketplace manifests)\n- Skills inside: [agentskills.io spec](https://agentskills.io/specification) — portable to Cursor, Copilot, Gemini CLI, Goose, Junie, 30+ other agent platforms\n- Distribution: triple-mode — Claude Code plugin install OR Codex plugin install OR `npx skills add ievo-ai/skills --skill \u003cname\u003e` via [skills.sh](https://www.skills.sh) (planned v1.0)\n- Universal positioning: works wherever Node.js 18+ + git + an agent platform that supports skills are available\n\n## Roadmap\n\nFor the full shipped-version history (v0.2 → current), see [`CHANGELOG.md`](./CHANGELOG.md). Forward-looking items only below.\n\n- **v0.7.0 (planned):** Cortex A/B validation gate for evolutions — mutations that don't improve get rejected via blind evaluation. Plus a GitHub-search source in `discover.mjs` for agent-only / plugin-only repos not surfaced by skills.sh.\n- **v1.0:** Skills.sh publication + cross-project pattern detection (curator). Lessons that recur across projects get promoted to \"blessed\" upstream evolutions.\n\n## Acknowledgments\n\n- [find-skills](https://github.com/vercel-labs/skills) — vercel-labs's skill discovery. Through v0.5.x we used find-skills as bootstrap prereq; v0.6.0+ we ship our own [`discover.mjs`](plugins/ievo/scripts/discover.mjs) that hits the same skills.sh API directly, with heuristics inherited verbatim from find-skills SKILL.md (trusted owners, install thresholds, category queries, synonym fallback). Credit to vercel-labs for the original best practices.\n- [agentskills.io](https://agentskills.io) — the open standard for skills\n\n## License\n\nMIT. See `LICENSE`.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fievo-ai%2Fskills","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fievo-ai%2Fskills","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fievo-ai%2Fskills/lists"}