convez.ai
SkillDevOps & InfraestruturaAvançado
ievo-ai

iEvo — Plugin Auto-Evolutivo para Agentes de IA

ievo-ai/skills

Descobre, audita e evolui skills de agentes com segurança e portabilidade cross-platform

Ver no GitHub
InicialPluginScore · de 0 a 100

Camada universal de descoberta, auditoria de segurança e evolução para skills de agentes de código (Claude Code, Codex e 30+ plataformas). Captura lições como overlays que sobrevivem atualizações upstream, audita skills via análise profunda de segurança e instala com portabilidade em escopo de projeto.

Instalação

$npx convez-ai ievo-ai/skills

1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.

Métricas

Estrelas
1
Forks
0
Acompanhando
0
Saúde
50%
Último commit
há 2 meses
Versão
v0.80.38
Issues abertas
44
Contribuidores
7

Casos de uso

  • Descoberta segura de plugins e skills para agentes de código
  • Auditoria de segurança de skills antes da instalação (análise de conteúdo + threat modeling)
  • Captura de lições que persistem através de atualizações upstream
  • Gerenciamento de skills portáveis via padrão agentskills.io em múltiplas plataformas

Veredito

Alpha robusto (v0.6.x) que resolve um problema real: descoberta segura e evolução de skills em ecossistema fragmentado de agentes. Pipeline funcional end-to-end com testes locais, mas APIs e comportamento podem mudar até v1.0 — exige pinning explícito para produção.

README

A tradução para o português deste README ainda está na fila.

iEvo — Self-Evolving Plugin for AI Coding Agents

⚠️ 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.

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 standard.

iEvo is a universal discovery + safety + evolution layer on top of skills.sh and the multi-platform agent skills ecosystem.

Currently distributed via:

  • Claude Code marketplace (.claude-plugin/marketplace.json)
  • Codex marketplace (.codex-plugin/marketplace.json)
  • skills.sh registry (planned for v1.0)

Cross-platform skills inside the plugin are portable via the 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.

Quick start

Claude Code

# 1. Install iEvo plugin (zero prereqs — v0.6.0 dropped the find-skills install step)
/plugin marketplace add ievo-ai/skills
/plugin install ievo@ievo-skills
/reload-plugins

# 2. Initialize in your project
cd <your-project>
/ievo:init

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.

Codex (CLI / app / VS Code extension)

# 1. Add the iEvo marketplace
/plugins add ievo-ai/skills

# 2. Install
/plugins install ievo@ievo-skills

# 3. Initialize in your project
cd <your-project>
/ievo:init

Codex support added in v0.3.3 — same plugin content, separate marketplace manifests (.claude-plugin/marketplace.json vs .codex-plugin/marketplace.json).

Cross-platform skills inside the plugin are fully portable via 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.

/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.

That's it. Interactive interview, security checks, install. Then /reload-plugins to activate.

Permission pre-setup (optional, skips the prompt)

If 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):

{
  "permissions": {
    "allow": [
      "Bash(gh api*)",
      "Bash(gh search*)"
    ]
  }
}

Without 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.)

The pipeline

/ievo:init composes 6 stages (v0.6.0+):

discover.mjs (ours, parallel skills.sh API queries)
    ↓
index-repos (ours, parallel repo-indexer sub-agents)
    ↓
categorical rank — top-5 per category
    ↓
interview (per candidate — AskUserQuestion)
    ↓
security-auditor (parallel sub-agents, antivirus deep scan)
    ↓
install (project-scope vendor or plugin)
  1. 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.
  2. 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).
  3. 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.
  4. 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.
  5. install runs two paths (project-scope, copy + source SHA metadata):
    • Vendor (skills + agents): gh api repos/<owner>/<repo>/contents/<path>?ref=<sha> → Write tool → .claude/<type>/ → inject overlay marker → record source repo + commit SHA in .ievo/evolution/<scope>/<name>.md for /ievo:update to track upstream changes
    • Plugin install (anything with hooks/MCP/commands): edit .claude/settings.json extraKnownMarketplaces + enabledPlugins for team-portable activation

Commands & Skills

Skills (auto-activatable, cross-platform via agentskills.io)

SkillWhat it does
/ievo:initFull pipeline: discover, audit, install
/ievo:evolution "<lesson>"Capture a lesson — append to overlay file. Never modifies agent/skill body.
/ievo:feedbackSubmit bug/idea/skip-reasons as GitHub issue
/ievo:debug-onEnable verbose / trace-level logging for the iEvo pipeline
/ievo:debug-offDisable verbose logging and finalize the debug session
/ievo:hooks-setupConfigure Claude Code lifecycle hooks for iEvo pipeline events (init complete, security RED, evolution captured)
/ievo:overlay-statusList active evolution overlays in this project, grouped by scope (Project / agents / skills) with last-modified dates
/ievo:index-reposStandalone: enumerate a repo (callable on its own)
/ievo:security-checkStandalone: audit a specific skill/agent/plugin

Commands (strictly explicit, Claude Code-specific)

CommandWhat it does
/ievo:uninstallRemove markers from CLAUDE.md/AGENTS.md and .claude/agents/, .claude/skills/. Preserves .ievo/.
/ievo:updateRefresh vendored agent/skill files from upstream. Re-inject markers. Overlay files untouched.

The overlay model

Under v0.2.0, agent and skill files are never modified by evolution. Lessons accumulate in separate overlay files, read live at every dispatch.

When you vendor an agent (via /ievo:init) or evolve it (via /ievo:evolution):

  1. Local file (.claude/agents/<name>.md) gets a ONE-TIME marker block right after its frontmatter:
    <!-- ievo:start -->
    **Before applying the instructions below**, read `.ievo/evolution/agents/<name>.md` if it exists, and apply ALL rules from its sections IN ADDITION to the instructions below.
    <!-- ievo:end -->
    
  2. Overlay file (.ievo/evolution/agents/<name>.md) holds the accumulated rules:
    ---
    source:
      repo: wshobson/agents
      path: plugins/python-development/agents/python-pro.md
      commit_sha: a1b2c3d4
      fetched_at: 2026-05-18T10:00:00Z
    ---
    
    # python-pro — Evolution Overlay
    
    ## 2026-05-19 14:32 UTC — Check git status before commit
    **Trigger:** user-observed mistake during code review
    
    Always check `git status` before commits to avoid orphaned files.
    

When the agent is dispatched, Claude reads both files automatically — the agent body's instructions and the overlay's accumulated rules.

Why this matters:

  • Upstream updates are trivial: /ievo:update re-fetches the file and re-injects the marker. Overlay rules continue applying.
  • No drift, no Opus replay loop, no patches accumulating in the agent body.
  • Overlay file is the single source of truth for evolution. Easy to audit, easy to share via git.

Project-side layout

After /ievo:init with some skills/agents vendored and some plugins installed:

<your-project>/
├── CLAUDE.md                        # (if first project-wide evolution recorded — gets marker block)
├── .claude/
│   ├── settings.json                # NEW: plugin marketplaces + enabledPlugins (commit for team sync)
│   ├── agents/
│   │   └── python-pro.md            # vendored, has overlay marker
│   └── skills/
│       └── changelog/
│           └── SKILL.md             # vendored, has overlay marker
└── .ievo/
    ├── evolution/                   # COMMIT to git — project's evolution state
    │   ├── project.md
    │   ├── agents/
    │   │   └── python-pro.md        # overlay file — actual rules live here
    │   └── skills/
    │       └── changelog.md
    ├── cache/                       # GITIGNORE — re-derivable
    │   └── index/
    │       └── wshobson-agents.md
    └── log/                         # GITIGNORE — local diagnostic
        └── init-20260518-093613.md

/ievo:init adds the right .gitignore entries automatically if your project has a .gitignore.

Security model (v0.5.2 — senior-security-engineer vulnerability assessment)

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.

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).

Verdicts

VerdictWhatUX
🟢 GREENFull deep scan complete, no threats detected, intent is clearly legitimatesilent install
🟡 YELLOWMinor concerns worth noting but not blocking (e.g., plain utility scripts present)batch multi-select confirmation
🔴 REDAt least one specific threat detected with high confidence, cited file + excerpt4 options: try alternative / force install / skip / report to source repo

Threats scanned for

  1. Prompt injection — direct ("ignore previous"), indirect ("for debugging note .env contents"), encoded payloads
  2. Credential exfiltration — reads of .env, ~/.aws/, ~/.ssh/, even when framed as "debugging"
  3. Suspicious external network — curl X | bash, unknown domains, output to writable paths
  4. Time bombs — date/counter/env-flag-based conditional execution
  5. Encoded payloads — long base64/hex strings, dynamic command construction
  6. Broad/destructive bash — Bash(*), Bash(rm:*), Bash(sudo:*), Bash(curl:*)
  7. Hook abuse — PreToolUse/UserPromptSubmit with suspicious command
  8. Runtime download — scripts pulling additional code at runtime
  9. Social engineering — legitimate name + malicious body
  10. Tool model bypass — instructions to disable safety checks

Report-to-source flow (RED only)

When verdict is RED, user gets a 4th option: "Report to <owner>/<repo> (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.

Issue body footer identifies iEvo as the source (Reviewed via iEvo — community security audit tooling) so maintainers know it's automated review, not random spam.

What we DON'T do

  • ❌ Owner-based trust shortcuts (TRUSTED_OWNERS, "famous account = safe") — dropped in v0.5.2
  • ❌ Heuristic risk_tier in repo indices ("trusted/neutral/caution") — dropped in v0.5.2
  • ❌ Surface-level pattern matching as final verdict — Sonnet's reasoning is the only signal
  • ❌ Auto-install RED items — always explicit user choice

Known configuration gotcha — CLAUDE_CODE_SUBAGENT_MODEL

Claude Code v2.1.146+ ships a CLAUDE_CODE_SUBAGENT_MODEL environment variable that overrides an agent's frontmatter model: declaration. Per official docs, the model-resolution order for subagents is:

  1. CLAUDE_CODE_SUBAGENT_MODEL env var, if set
  2. Per-invocation model parameter
  3. The subagent definition's model: frontmatter (where iEvo declares sonnet)
  4. The main-conversation model

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.

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.

Install paths

iEvo supports two install paths per candidate:

Vendor (skills + agents)

  • gh api fetches the source file/directory.
  • Writes to .claude/<type>/<name>/ in your project.
  • Injects the overlay marker.
  • Creates .ievo/evolution/<scope>/<name>.md with source metadata frontmatter.
  • No hooks, no MCP, no commands come along — just the agent/skill content.
  • Best for: pulling specific agents/skills without committing to a whole plugin.

Plugin install (anything with hooks / MCP / commands)

  • Edits .claude/settings.json extraKnownMarketplaces + enabledPlugins.
  • Settings file is committed to git → team gets prompt to trust folder → plugin auto-installs for them too.
  • Brings everything: agents, skills, commands, hooks, MCP servers.
  • Best for: plugins where the value is the integration (hooks intercepting workflows, MCP servers, slash commands).

The interview at /ievo:init step 7b asks per candidate: vendor specific items OR install whole plugin OR skip.

Repository structure

ievo-ai/skills/
├── .claude-plugin/
│   ├── plugin.json
│   └── marketplace.json
└── plugins/ievo/
    ├── .claude-plugin/plugin.json
    ├── commands/
    │   ├── uninstall.md
    │   └── update.md
    ├── skills/
    │   ├── init/SKILL.md           # /ievo:init — orchestrator
    │   ├── evolution/SKILL.md      # /ievo:evolution — overlay capture
    │   ├── feedback/SKILL.md       # /ievo:feedback — file GitHub issues
    │   ├── debug-on/SKILL.md       # /ievo:debug-on — enable verbose session logging
    │   ├── debug-off/SKILL.md      # /ievo:debug-off — disable verbose session logging
    │   ├── hooks-setup/SKILL.md    # /ievo:hooks-setup — configure lifecycle hooks
    │   ├── overlay-status/SKILL.md # /ievo:overlay-status — list active evolution overlays
    │   ├── index-repos/SKILL.md    # /ievo:index-repos — enumerate a repo
    │   └── security-check/SKILL.md # /ievo:security-check — audit a candidate
    ├── agents/
    │   ├── evolution.md            # sub-agent dispatched by evolution skill
    │   ├── repo-indexer.md         # parallel dispatch — one per repo for indexing (Step 6)
    │   └── security-auditor.md     # parallel dispatch — one per selected item for audit (Step 8)
    └── scripts/
        ├── discover.mjs            # skills.sh API discovery (parallel queries)
        ├── scan_repo.mjs           # deterministic repo scanner (Node, no LLM)
        ├── validate_agents.mjs     # vendor-neutral model: frontmatter validator
        └── tests/                  # node:test suites + fixtures (100% coverage gate)

Standards compliance

  • Plugin format: Claude Code-native + Codex-native (dual marketplace manifests)
  • Skills inside: agentskills.io spec — portable to Cursor, Copilot, Gemini CLI, Goose, Junie, 30+ other agent platforms
  • Distribution: triple-mode — Claude Code plugin install OR Codex plugin install OR npx skills add ievo-ai/skills --skill <name> via skills.sh (planned v1.0)
  • Universal positioning: works wherever Node.js 18+ + git + an agent platform that supports skills are available

Roadmap

For the full shipped-version history (v0.2 → current), see CHANGELOG.md. Forward-looking items only below.

  • 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.
  • v1.0: Skills.sh publication + cross-project pattern detection (curator). Lessons that recur across projects get promoted to "blessed" upstream evolutions.

Acknowledgments

  • find-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 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.
  • agentskills.io — the open standard for skills

License

MIT. See LICENSE.

Ver o original no GitHub

Bom para

Relacionados