Agent skill

Pneuma Evolve

by pandazki in pandazki/pneuma-skills

Analyze interaction history and propose evidence-backed improvements to a Pneuma mode skill.

MITAuto-check passed

Install Pneuma Evolve

skills CLI
$ npx skills add pandazki/pneuma-skills --skill pneuma-evolve -a claude-code

Project install by default; add -g for ~/.claude/skills/.

GitHub CLI
$ gh skill install pandazki/pneuma-skills pneuma-evolve --agent claude-code

Project scope by default; add --scope user for a personal install. Needs GitHub CLI 2.90.0 or later (public preview).

Manual copy
$ git clone --depth 1 https://github.com/pandazki/pneuma-skills.git skills-src && mkdir -p .claude/skills && cp -r skills-src/modes/evolve/skill .claude/skills/pneuma-evolve && rm -rf skills-src

Use ~/.claude/skills/ instead of .claude/skills for a personal install. The folder must contain SKILL.md.

Claude Code skills documentation · loads skills from .claude/skills/

Facts

Skill name
pneuma-evolve
GitHub stars
161
Token cost
~2.3k tokens
SKILL.md length
1,211 words
Files
7 (incl. scripts)
Skills in repo
30
Repo updated
First seen
Licence
MIT

At a glance

Analyze interaction history and propose evidence-backed improvements to a Pneuma mode skill.

  • Works in 4 steps: You write a proposal to… → The server's chokidar watcher picks the… → The user opens it, scans evidence +… → …
  • SKILL.md covers Working with the viewer, Evolution Process, Data Access Scripts and Dual Analysis: Augment AND Prune, plus 2 more sections
  • Runs TypeScript scripts from its folder; calls bun

What it does

Pneuma Evolve is an agent skill from pandazki/pneuma-skills. Analyze interaction history and propose evidence-backed improvements to a Pneuma mode skill. Use in the Evolution workspace to add useful guidance and prune obsolete instructions for user review.

Its SKILL.md is about 2.3k tokens, which your agent loads only when the skill is triggered. The skill folder holds 7 other files, including scripts (for example `scripts/_shared.ts`, `scripts/extract-tool-flow.ts` and `scripts/list-sessions.ts`).

The repository describes itself as: Co-creation infrastructure for humans and code agents — visual environment, skills, continuous learning, and distribution. The licence is MIT.

Example prompts

  • “/pneuma-evolve”

Requirements

  • Node.js

Workflow steps

4 steps, taken from the first numbered list in SKILL.md.

  1. You write a proposal to .pneuma/evolution/proposals/.json using Write.
  2. The server's chokidar watcher picks the file up; the dashboard's auto-poll (every ~3 seconds) refreshes the proposal list and the new…
  3. The user opens it, scans evidence + confidence ratings, and clicks Apply (mutates workspace skill files in place), Fork (clones into a new…
  4. The next turn's and reflect that decision; adjust accordingly (don't re-propose a Discarded change without new evidence; treat Applied…

What it can do on your machine

Read from SKILL.md and the folder at commit 0023d3c. It shows what the files ask for, not the result of running them.

  • Tool permissions

    Pre-approves nothing: there is no allowed-tools line, so your agent's usual permission prompts apply.

    From allowed-tools in the SKILL.md frontmatter.

  • Runs code

    Ships 6 files in scripts/ (TypeScript), which the agent can run.

    Shell commands in SKILL.md call:

    • bun

    From the folder's file list and the shell code blocks in SKILL.md.

  • Network

    No URLs in SKILL.md.

    From URLs in SKILL.md, links to its own repository left out.

  • Credentials

    Names no API keys, tokens, secrets or passwords.

    From names ending in _API_KEY, _TOKEN, _SECRET, _KEY or _PASSWORD in SKILL.md.

Context cost

Pneuma Evolve loads about 2.3k tokens when it runs. Until then it costs about 52 tokens; SKILL.md has 1,211 words of instructions outside code blocks.

Always · name and description, kept in context so the agent knows when to use it
~52
When it runs · the whole SKILL.md, loaded when a task matches
~2.3k

Estimates: characters ÷ 4, the usual rule of thumb; real counts depend on the model's tokenizer. Scripts and assets cost tokens only if the agent reads them.

Safety

Auto-check passed

The automated check found no risky patterns in SKILL.md.

Automated static check — not a guarantee. Review scripts before installing. It scans the text of SKILL.md for risky patterns (piping downloads into a shell, reading credential files, hidden Unicode, destructive commands); the scripts in this folder are not scanned.

SKILL.md

The full file from pandazki/pneuma-skills at commit 0023d3c, republished under its MIT licence (© pandazki). 1,211 words, ~2,288 tokens.

Download SKILL.mdSave it as .claude/skills/pneuma-evolve/SKILL.md (or your agent's skills folder). This skill also uses 6 other files; get the full folder from GitHub.
name
pneuma-evolve
description
Analyze interaction history and propose evidence-backed improvements to a Pneuma mode skill. Use in the Evolution workspace to add useful guidance and prune obsolete instructions for user review.

Skill Evolution Agent

In script examples, <SKILL_DIR> means the actual directory containing this loaded SKILL.md. Substitute its full path and keep shell paths quoted. The runtime installs it under .claude/skills for Claude Code, .agents/skills for Codex, or .kimi-code/skills for Kimi; use the path given in your instructions.

You are the Skill Evolution Agent for Pneuma. Your mission is to analyze a user's interaction history and write structured proposal files that evolve workspace skill files — both augmenting with learned preferences and pruning instructions that are no longer load-bearing.

Working with the viewer

The user sees an Evolution Dashboard (left panel). Unlike co-creation modes, there is no live canvas — your work surfaces as proposal files that the dashboard auto-polls and renders. This section consolidates everything you need to know about that surface.

Reading what the user sees

The user's last message arrives wrapped with two channels you should consume on every turn:

  • <viewer-context> — a snapshot of dashboard state. For evolve this includes: the target mode being evolved, the workspace path, the active evolution directive, data-source statistics, the proposal currently being inspected (id + path), and the diff/section the user is viewing within it. Read this before responding so your follow-ups reference what's actually open in front of them — e.g., "I see you're on proposal #3, change 2 — here's the additional evidence you asked about."
  • <user-actions> — discrete user events since your last turn. In evolve, the relevant action types are clicks on Apply to Workspace, Fork as Custom Mode, Discard, and Rollback (along with proposal-open / proposal-close navigation). Treat these as ground truth: if the user just discarded a proposal, do not re-pitch it; if they applied one, your next analysis should treat those changes as committed.
Locator cards

Locators aren't surfaced in evolve — proposals are the navigation surface. The dashboard renders the proposal list as the primary index, and the user navigates by clicking proposals directly. Don't emit <viewer-locator> cards in chat; instead, reference proposals by id or filename ("see .pneuma/evolution/proposals/2026-04-30-tone.json"), and the user will open them from the dashboard list.

Viewer actions

Evolve's viewer is effectively read-only from the agent's side. The dashboard exposes Apply / Fork / Discard / Rollback to the user, but there is no POST $PNEUMA_API/api/viewer/action endpoint you should call to drive it. Your only write surface is the filesystem: you write proposal JSON files; the dashboard reads them. Likewise, no native desktop APIs ($PNEUMA_API/api/native/*) are part of the evolve workflow.

If you need to communicate with the user, do it in chat — don't try to push UI state from the agent side.

Workflow integration

Concretely, the loop is:

  1. You write a proposal to .pneuma/evolution/proposals/<slug>.json using Write.
  2. The server's chokidar watcher picks the file up; the dashboard's auto-poll (every ~3 seconds) refreshes the proposal list and the new entry appears.
  3. The user opens it, scans evidence + confidence ratings, and clicks Apply (mutates workspace skill files in place), Fork (clones into a new custom mode), Discard (removes the proposal), or Rollback (reverts a previously applied proposal using the snapshot in .pneuma/evolution/backups/).
  4. The next turn's <viewer-context> and <user-actions> reflect that decision; adjust accordingly (don't re-propose a Discarded change without new evidence; treat Applied changes as the new baseline when reading SKILL.md).

Because the dashboard polls, the file is the message. A summary in chat is helpful, but the proposal must stand on its own — assume the user reads it inside the dashboard, not in the chat transcript.

Evolution Process

The evolution follows this flow:

  1. Briefing — Present the user with context (target mode, directive, data stats) and ask how to proceed
  2. Analysis — Scan conversation history using data access scripts
  3. Synthesis — Identify patterns, preferences, and recurring corrections
  4. Pruning review — Examine current skill instructions against history for stale or unnecessary constraints
  5. Evidence audit — Rate each finding's evidence strength before writing the proposal
  6. Proposal — Write a structured proposal with evidence citations and confidence ratings
  7. Review — User reviews in the dashboard and applies/forks/discards

Always start with the briefing. The user may want to:

  • Proceed directly with the default evolution directive
  • Provide additional preferences or focus areas before you start
  • Share reference content or style examples
  • Adjust the evolution direction entirely
Show full SKILL.md (519 more words)Show less

Data Access Scripts

You have purpose-built scripts at <SKILL_DIR>/scripts/ for efficient CC history analysis. Always use these instead of raw grep/cat/head on JSONL files. CC history files are very large (100MB+) and 99% noise (tool_results, thinking blocks, progress events).

ScriptPurposeKey Flags
list-sessions.tsDiscover sessions across projects--project, --since, --limit
session-digest.tsExtract pure conversation text (224MB → 500KB)--file, --max-turns
search-messages.tsCross-session regex search on conversation text--query, --role, --project, --limit
extract-tool-flow.tsTool usage sequences with error detection--file, --compact
session-stats.tsQuick session overview (message counts, duration)--file
  1. Discover sessions with bun list-sessions.ts
  2. Triage with bun session-stats.ts — find sessions with many user messages
  3. Digest with bun session-digest.ts — read the actual conversation, not tool noise
  4. Search with bun search-messages.ts — find cross-project preference signals
  5. Synthesize findings into a proposal with evidence-backed changes

Dual Analysis: Augment AND Prune

Every skill instruction encodes an assumption about what the model can't do on its own. As models improve, some of these assumptions become stale. Your analysis should cover both directions:

Augmentation (add what's missing)
  • Patterns the user repeatedly corrects the agent on → new instructions
  • Explicit preference declarations → new defaults
  • Recurring style choices → codified preferences
Pruning (remove what's stale)
  • Instructions the agent consistently follows correctly WITHOUT the instruction → the instruction may be redundant
  • Instructions the user actively overrides or ignores → the instruction may be wrong
  • Overly specific constraints that limit output quality → candidates for relaxation or removal

How to detect stale instructions: Read the current SKILL.md, then search history for sessions where the skill was active. Look for:

  1. Instructions that are never referenced in corrections (agent already knows this)
  2. Instructions that the user explicitly contradicts ("no, don't do it that way" when the skill says to)
  3. Instructions added for older model limitations that current models handle natively

Use "remove" as the action for pruning changes. The content field should contain the text to match and remove.

Evidence Quality

Before writing the proposal, audit each finding against these evidence tiers:

ConfidenceCriteriaMinimum evidence
highUser explicitly states a preference, or corrects the same thing 3+ times across sessions2+ quotes from different sessions
mediumClear pattern in 2+ sessions, or one strong explicit statement1-2 quotes with clear intent
lowSingle implicit signal, or pattern from only one session1 quote, possibly ambiguous

Every change in the proposal MUST include a confidence field. This makes evidence strength visible to the user during review instead of hidden behind confident prose.

Rules:

  • high confidence changes are recommended for immediate application
  • medium confidence changes are worth reviewing — present the evidence and let the user decide
  • low confidence changes should generally be omitted. Include them only if the potential impact is significant and clearly explain the uncertainty

Key Rules

  • Write proposals to disk — do NOT modify skill files directly
  • Every change must cite specific user quotes as evidence
  • Every change must include a confidence rating (high/medium/low)
  • Pruning (remove) changes require the same evidence standards as additions
  • An empty proposal (no changes) is a valid outcome when evidence is insufficient
  • After writing a proposal, summarize your findings briefly in chat

© pandazki, MIT. Rendered from Markdown: HTML in the file is shown as text, images as links, and headings moved down two levels. Raw file

Files

SKILL.md and 6 other files (scripts) in modes/evolve/skill of pandazki/pneuma-skills.

  • SKILL.md
  • scripts/_shared.ts
  • scripts/extract-tool-flow.ts
  • scripts/list-sessions.ts
  • scripts/search-messages.ts
  • scripts/session-digest.ts
  • scripts/session-stats.ts

Open the folder on GitHubat commit 0023d3c

Compare with similar skills

Pneuma Evolve next to the 5 skills that share the most tags, products or categories with it. Stars are the repository's; “used in” counts other GitHub owners with a copy.

Pneuma Evolve compared with similar skills
SkillStarsUsed inTokensAuto-checkLicenceRepo updated
Pneuma Evolve this skillpandazki/pneuma-skills161—~2.3kAutomated safety check: PassMIT
A-Evolve Agent Improvementaiming-lab/AutoResearchClaw15k—~1.8kAutomated safety check: PassMIT
Geo Proposalsickn33/agentic-awesome-skills47k1 repos~3.2kAutomated safety check: NotesMIT
Better Proposals AutomationComposioHQ/awesome-claude-skills77k3 repos~764Automated safety check: PassNone
Contract And Proposal Writeralirezarezvani/claude-skills28k2 repos~3.4kAutomated safety check: PassMIT
ProposalChorus-AIDLC/Chorus1.2k—~5.5kAutomated safety check: PassAGPL-3.0

Similar skills

  • A-Evolve Agent Improvement

    aiming-lab/AutoResearchClaw

    Diagnoses where an agent failed across runs and turns the findings into new skills, system prompt patches and knowledge entries, using the A-Evolve loop.

    15k GitHub stars~1.8k tokensUpdated 1 mo ago
    AI & LLM EngineeringAuto-check passed
  • Geo Proposal

    sickn33/agentic-awesome-skills

    Auto-generate a professional, client-ready GEO service proposal from audit data.

    47k GitHub starsUsed in 1 repo~3.2k tokens
    Sales & SupportAuto-check: notes
  • Better Proposals Automation

    ComposioHQ/awesome-claude-skills

    Automate Better Proposals tasks via Rube MCP (Composio). An agent skill from ComposioHQ/awesome-claude-skills.

    77k GitHub starsUsed in 3 repos~764 tokens
    Productivity & AutomationAuto-check passed
  • Contract And Proposal Writer

    alirezarezvani/claude-skills

    Generate professional, jurisdiction-aware business documents: freelance contracts, project proposals, SOWs, NDAs, and MSAs.

    28k GitHub starsUsed in 2 repos~3.4k tokens
    Legal & ComplianceAuto-check passed
  • Proposal

    Chorus-AIDLC/Chorus

    Chorus Proposal workflow on Hermes — create proposals with document and task drafts, manage dependency DAG, validate, submit, and run the read-only proposal reviewer via delegatetask.

    1.2k GitHub stars~5.5k tokensUpdated today
    Sales & SupportAuto-check passed
  • Proposal Writer

    holaboss-ai/holaOS

    Draft client proposals and statements of work that scope, price, and win the project.

    11k GitHub stars~574 tokensUpdated 1 mo ago
    Sales & SupportAuto-check passed

More from pandazki/pneuma-skills

All 30 skills in this repo
  • Pneuma Bansho

    pandazki/pneuma-skills

    Explain something by writing it on a board. An agent skill from pandazki/pneuma-skills.

    161 GitHub stars~6.9k tokensUpdated today
    Auto-check passed
  • Pneuma Clipcraft

    pandazki/pneuma-skills

    AI-orchestrated video production on @pneuma-craft. An agent skill from pandazki/pneuma-skills.

    161 GitHub stars~7.5k tokensUpdated today
    Auto-check: notes
  • Pneuma Lucid

    pandazki/pneuma-skills

    Pneuma Lucid Mode workspace guidelines. An agent skill from pandazki/pneuma-skills.

    161 GitHub stars~4.6k tokensUpdated today
    Auto-check: warnings
  • Pneuma Plotwise

    pandazki/pneuma-skills

    Pneuma Plotwise workspace guidelines. An agent skill from pandazki/pneuma-skills.

    161 GitHub stars~8.9k tokensUpdated today
    Auto-check passed
  • Pneuma Sprite

    pandazki/pneuma-skills

    Pneuma Sprite Mode workspace guidelines. An agent skill from pandazki/pneuma-skills.

    161 GitHub stars~16k tokensUpdated today
    Auto-check passed
  • Pneuma Webcraft

    pandazki/pneuma-skills

    Pneuma WebCraft Mode workspace guidelines with Impeccable.style design intelligence.

    161 GitHub stars~7.5k tokensUpdated today
    Auto-check: notes

Questions about Pneuma Evolve

What does Pneuma Evolve do?

Analyze interaction history and propose evidence-backed improvements to a Pneuma mode skill. Pneuma Evolve is an agent skill from pandazki/pneuma-skills. Analyze interaction history and propose evidence-backed improvements to a Pneuma mode skill.

How do I install Pneuma Evolve in Claude Code?

Run `npx skills add pandazki/pneuma-skills --skill pneuma-evolve -a claude-code`. Or copy the skill folder (modes/evolve/skill in pandazki/pneuma-skills) into .claude/skills/pneuma-evolve in your project. Claude Code loads it when a task matches its description.

How do I install Pneuma Evolve in Codex?

Run `npx skills add pandazki/pneuma-skills --skill pneuma-evolve -a codex`. Or copy the skill folder (modes/evolve/skill in pandazki/pneuma-skills) into .agents/skills/pneuma-evolve in your project. Codex loads it when a task matches its description.

Can I use Pneuma Evolve in Cursor, Gemini CLI or GitHub Copilot?

Cursor, Gemini CLI, GitHub Copilot and OpenCode also load SKILL.md folders. With the skills CLI, run `npx skills add pandazki/pneuma-skills --skill pneuma-evolve -a cursor` (or -a gemini-cli, github-copilot or opencode for the others). To copy it by hand, put the folder in .cursor/skills/pneuma-evolve, .gemini/skills/pneuma-evolve, .github/skills/pneuma-evolve and .opencode/skills/pneuma-evolve in your project.

What does Pneuma Evolve need to run?

Going by SKILL.md and its folder, Pneuma Evolve needs TypeScript for the scripts in its folder and the command-line tools its instructions call (bun). Our summary lists: Node.js.

Does Pneuma Evolve access the network?

SKILL.md contains no URLs. Any network use would come from the scripts or tools the agent runs. This is read from the text; nothing was executed.

Is Pneuma Evolve safe to install?

Our automated static check of SKILL.md found no risky patterns, such as piping downloads into a shell, reading credential files or hidden Unicode. It is not a guarantee. The check reads SKILL.md only: the scripts in the folder are not scanned, so read them before running anything.

What licence does Pneuma Evolve use?

Pneuma Evolve is published under the MIT licence (the repository's licence). It allows redistribution, so the full SKILL.md is shown on this page.

How many tokens does Pneuma Evolve use?

About 2.3k tokens (SKILL.md is roughly 9.2k characters). Agents keep only the skill's name and description in context until a task matches; then they load SKILL.md in full.

What are the alternatives to Pneuma Evolve?

Skills that share tags, products or a category with Pneuma Evolve: A-Evolve Agent Improvement (aiming-lab/AutoResearchClaw, 15k stars), Geo Proposal (sickn33/agentic-awesome-skills, 47k stars), Better Proposals Automation (ComposioHQ/awesome-claude-skills, 77k stars) and Contract And Proposal Writer (alirezarezvani/claude-skills, 28k stars). The comparison table on this page puts their stars, adoption, token cost, safety result and licence side by side.

Who maintains Pneuma Evolve?

pandazki (a GitHub user) maintains it in pandazki/pneuma-skills, which has 161 GitHub stars. The repository holds 30 skills in this directory. The repository was last updated on October 9, 2026.

Source: pandazki/pneuma-skills on GitHub. Facts on this page come from the repository at the commit we read; the author's words are quoted as theirs.