New: 98,000+ skills indexed from GitHub repos with 100+ stars · every skill safety-checkedBrowse top skillsTop skills
Esc to closeBrowse all skills
Submit a skillBrowse skills
Submit a skillBrowse skills

Agent skill

Run History Skill Upgrader

by dongshuyan in dongshuyan/compass-skills

Use real run evidence, validation failures, source drift, platform drift, and user feedback to plan and, only after explicit approval, apply structural upgrades to an existing skill.

MITAuto-check passedProductivity & Automation

Install Run History Skill Upgrader

skills CLI
$ npx skills add dongshuyan/compass-skills --skill run-history-skill-upgrader -a claude-code

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

GitHub CLI
$ gh skill install dongshuyan/compass-skills run-history-skill-upgrader --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/dongshuyan/compass-skills.git skills-src && mkdir -p .claude/skills && cp -r skills-src/skills/run-history-skill-upgrader .claude/skills/run-history-skill-upgrader && 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
run-history-skill-upgrader
GitHub stars
753
Token cost
~1.7k tokens
SKILL.md length
827 words
Files
9 (incl. scripts, references)
Skills in repo
9
Repo updated
First seen
Licence
MIT

At a glance

Use real run evidence, validation failures, source drift, platform drift, and user feedback to plan and, only after explicit approval, apply structural upgrades to an existing skill.

  • Works in 2 steps: plan_only: read the target skill and the… → apply_after_approval: modify files only…
  • The user asks to improve an existing skill from recent runs
  • SKILL.md covers Language Policy, Role, Portability and Mandatory Two-Stage Approval, plus 7 more sections
  • Runs Python scripts from its folder; calls python

What it does

Run History Skill Upgrader is an agent skill from dongshuyan/compass-skills. Use real run evidence, validation failures, source drift, platform drift, and user feedback to plan and, only after explicit approval, apply structural upgrades to an existing skill. Use when the user asks to improve an existing skill from recent runs, recurring failures, outdated sources, excessive bloat, changed platform behavior, or validated workflow feedback. Do not use to create a brand-new skill or to execute the business workflow itself.

Its SKILL.md is about 1.7k tokens, which your agent loads only when the skill is triggered. The skill folder holds 12 other files, including scripts and reference files (for example `agents/openai.yaml`, `evals/evals.json` and `references/evidence-and-scope.md`).

It sits in Productivity & Automation. It works with Python. The repository describes itself as: 司南：个性化 AI 任务总控 Skills 系统 /COMPASS: Personal Alignment Skills OS for AI Agents. The licence is MIT.

When your agent uses it

  • The user asks to improve an existing skill from recent runs
  • Recurring failures
  • Outdated sources
  • Excessive bloat

Example prompts

  • “/run-history-skill-upgrader”

Requirements

  • Python 3

Workflow steps

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

  1. plan_only: read the target skill and the agreed evidence scope, then produce a concrete upgrade plan and stop.
  2. apply_after_approval: modify files only after the user explicitly approves that specific plan.

What it can do on your machine

Read from SKILL.md and the folder at commit 1b2e556. 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 2 files in scripts/ (Python), which the agent can run.

    Shell commands in SKILL.md call:

    • python

    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

Run History Skill Upgrader loads about 1.7k tokens when it runs, and up to ~4.1k if it reads all its reference files. Until then it costs about 119 tokens; SKILL.md has 827 words of instructions outside code blocks.

Always · name and description, kept in context so the agent knows when to use it
~119
When it runs · the whole SKILL.md, loaded when a task matches
~1.7k
With references · SKILL.md plus every file in references/, read only if the agent opens them
~4.1k

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 dongshuyan/compass-skills at commit 1b2e556, republished under its MIT licence (© dongshuyan). 827 words, ~1,681 tokens.

Download SKILL.mdSave it as .claude/skills/run-history-skill-upgrader/SKILL.md (or your agent's skills folder). This skill also uses 8 other files; get the full folder from GitHub.
name
run-history-skill-upgrader
description
Use real run evidence, validation failures, source drift, platform drift, and user feedback to plan and, only after explicit approval, apply structural upgrades to an existing skill. Use when the user asks to improve an existing skill from recent runs, recurring failures, outdated sources, excessive bloat, changed platform behavior, or validated workflow feedback. Do not use to create a brand-new skill or to execute the business workflow itself.

Run History Skill Upgrader

Language Policy

Write all user-facing output in the user's language. Default to Chinese when the language is unknown.

Role

Turn real run feedback into structural net improvement for an existing skill. Upgrades may add, modify, merge, delete, deprecate, or decide not to change anything.

Portability

This skill is agent-agnostic. It should work in Codex, Claude Code, OpenCode, OpenClaw, Hermes, and similar local agent hosts that can read SKILL.md plus optional references/, scripts/, evals/, and agents/.

  • Resolve <skill-dir> from the directory that contains this SKILL.md.
  • Let <python> mean the host's available Python launcher: python3, python, or py -3.
  • Do not assume a fixed skill root, shell, home-directory layout, or path separator.
  • Placeholder paths such as <skill-dir>/scripts/... describe path segments, not a required separator style. On Windows, use the separator style that your shell or harness accepts.
  • Treat platform-specific helper tooling as optional. Use it only when it is actually available.

Mandatory Two-Stage Approval

This skill always starts in plan_only.

  1. plan_only: read the target skill and the agreed evidence scope, then produce a concrete upgrade plan and stop.
  2. apply_after_approval: modify files only after the user explicitly approves that specific plan.

The following are not approval by themselves:

  • "upgrade it";
  • "directly edit it";
  • "don't ask me";
  • "go ahead";
  • the original request to improve a skill.

Valid approval must clearly point to the current plan, for example "approve plan A", "apply the plan above", or "yes, execute that upgrade plan".

Workflow

  1. Lock the target skill name and path.
  2. Lock plan_only unless explicit post-plan approval already exists in the current conversation.
  3. Lock the evidence scope: conversation, logs, screenshots, artifacts, diffs, tests, source docs, or user feedback.
  4. Read the current target skill before proposing changes.
  5. Classify the signals: process gap, validation gap, source drift, platform drift, user preference, candidate idea, incident, routing gap, or content bloat.
  6. Design the case set: incident, candidate rule, regression case, boundary case, and optional holdout challenge.
  7. Pass the generalization gate. A one-off incident does not automatically deserve a lasting rule.
  8. Map route impact. Remove weak routes and move machine-checkable facts to tools, tests, schema checks, diffs, validators, or files.
  9. Choose the net-improvement shape: no_change, maintenance_note_only, prune_or_consolidate, local_refactor, cross_reference_refactor, major_refactor, or deprecate_or_replace_source.
  10. Produce the concrete plan and stop.
  11. Apply only after explicit approval.
  12. Validate, report what changed, and record follow-up risks.

Evidence Rules

Strong evidence:

  • user feedback or corrections;
  • real run outputs, logs, screenshots, tests, or diffs;
  • actual target-skill files;
  • official docs or first-party repositories that explain source or platform drift.

Weak evidence unless corroborated:

  • one-off timeouts;
  • one failed page load;
  • a search snippet without opening the source;
  • a model-generated idea with no supporting run evidence;
  • a private path or one temporary filename presented as if it were a universal rule.
Show full SKILL.md (360 more words)Show less

Upgrade Rules

  • Prefer deleting or merging stale guidance over stacking new reminders on top.
  • Keep examples only when they preserve complex behavior or important failure recovery.
  • Temporary user preferences stay task-local unless the user clearly wants them kept as durable behavior.
  • Holdout challenges are for post-apply validation, not for plan design.
  • Do not ship an internal maintenance log with this released skill package. If the target skill already has one, update it only after approval and only if the user wants durable maintenance history there.

File-Editing Discipline

Before applying changes:

  • read the target skill's SKILL.md, relevant references/, scripts/, evals/, and optional agent metadata;
  • preserve unrelated user changes;
  • capture a diff or snapshot reference when practical;
  • edit only files that belong to the current approved plan.

Do not write credentials, browser sessions, private account data, unrelated personal paths, or hidden prompts into the target skill.

Validation

Run the bundled validator for this upgrader skill:

bash
<python> <skill-dir>/scripts/validate_upgrade_artifacts.py --skill <skill-dir>

This bundled validator checks package structure, the portable Agent Skills frontmatter field set, referenced paths, JSON shape, Python syntax, common private-path leaks, and the upgrader's required approval terms. Its dependency-free frontmatter preflight accepts scalar fields, block text, and one-level string metadata; it rejects other YAML forms instead of guessing. A specific host may accept different syntax or a narrower field set, so its canonical validator remains authoritative for installation there. Neither structural check runs the eval cases or proves that an upgrade improves behavior.

Then run the target skill's own validator and the smallest relevant technical checks:

  • python -m py_compile for modified Python scripts;
  • python -m json.tool for edited JSON files;
  • trigger regression if the frontmatter description changed;
  • route and boundary regression if the workflow changed;
  • comparison against the original failure, at least one similar positive case, and at least one near-negative case for high-risk upgrades.

Do not claim that the upgrade is complete if validation was skipped or failed.

Final Response

Report:

  • the target skill and path;
  • whether the result is plan-only or applied;
  • evidence sources actually used;
  • files actually changed;
  • validation commands actually run and their results;
  • deleted or rejected ideas and why;
  • remaining risks or follow-up checks.

References

  • references/evidence-and-scope.md
  • references/upgrade-decision-protocol.md
  • references/validation-and-regression.md
  • references/examples.md
  • scripts/validate_upgrade_artifacts.py
  • evals/evals.json

© dongshuyan, 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 8 other files (scripts, references) in skills/run-history-skill-upgrader of dongshuyan/compass-skills.

  • SKILL.md
  • agents/openai.yaml
  • evals/evals.json
  • references/evidence-and-scope.md
  • references/examples.md
  • references/upgrade-decision-protocol.md
  • references/validation-and-regression.md
  • scripts/test_validate_upgrade_artifacts.py
  • scripts/validate_upgrade_artifacts.py

Open the folder on GitHubat commit 1b2e556

Compare with similar skills

Run History Skill Upgrader 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.

Run History Skill Upgrader compared with similar skills
SkillStarsUsed inTokensAuto-checkLicenceRepo updated
Run History Skill Upgrader this skilldongshuyan/compass-skills753—~1.7kAutomated safety check: PassMIT
A2a Protocolinternet-court/internet-court-skill6.6k1 repos~2.5kAutomated safety check: PassApache-2.0
Discord Bot Architectdavila7/claude-code-templates33k7 repos~2kAutomated safety check: PassMIT
A2a ProtocolTerminalSkills/skills163—~2.8kAutomated safety check: PassApache-2.0
Process Inboxtelegramdesktop/tdesktop33k1 repos~5.4kAutomated safety check: PassGPL-3.0
Process InboxTDesktop-x64/tdesktop3k—~4.3kAutomated safety check: PassGPL-3.0

Similar skills

  • A2a Protocol

    internet-court/internet-court-skill

    Builds Agent-to-Agent (A2A) servers and clients following Google's open protocol for agent interoperability.

    6.6k GitHub starsUsed in 1 repo~2.5k tokens
    Productivity & AutomationAuto-check passed

  • Discord Bot Architect

    davila7/claude-code-templates

    Specialized skill for building production-ready Discord bots.

    33k GitHub starsUsed in 7 repos~2k tokens
    Productivity & AutomationAuto-check passed

  • A2a Protocol

    TerminalSkills/skills

    Builds Agent2Agent (A2A) servers and clients, the open protocol (originally from Google, now under the Linux Foundation) that lets AI agents from different frameworks call each other.

    163 GitHub stars~2.8k tokensUpdated 7 days ago
    Productivity & AutomationAuto-check passed

  • Process Inbox

    telegramdesktop/tdesktop

    Process the local ignored ai-tdesktop inbox into durable, independently testable Telegram Desktop task records while task execution worktrees remain active.

    33k GitHub starsUsed in 1 repo~5.4k tokens
    Productivity & AutomationAuto-check passed

  • Process Inbox

    TDesktop-x64/tdesktop

    Process the local ignored ai-tdesktop inbox into durable, independently testable Telegram Desktop task records while task execution worktrees remain active.

    3k GitHub stars~4.3k tokensUpdated 19 days ago
    Productivity & AutomationAuto-check passed

  • Browser Automation Edge Cases

    aden-hive/hive

    Step-by-step procedure for debugging browser automation failures on complex sites such as LinkedIn, Twitter/X, single-page apps and Shadow DOM pages.

    11k GitHub stars~1.8k tokensUpdated 2 days ago
    Productivity & AutomationAuto-check passed

More from dongshuyan/compass-skills

All 9 skills in this repo

  • Task Forest

    dongshuyan/compass-skills

    Maintains a repo-local task forest or task DAG for the current workspace.

    753 GitHub stars~1.6k tokensUpdated 1 mo ago
    Auto-check passed

  • Run History Skill Builder

    dongshuyan/compass-skills

    Turn a completed task, browser flow, artifact pipeline, failure-recovery trace, or repeatedly refined workflow into a new reusable skill package or a reviewed skill-design plan.

    753 GitHub stars~1.8k tokensUpdated 1 mo ago
    Auto-check passed

  • Session Handoff Prompt

    dongshuyan/compass-skills

    Create a concise continuation prompt that a fresh agent session can paste in to resume a long or degraded session.

    753 GitHub stars~1.7k tokensUpdated 1 mo ago
    Auto-check passed

  • User Profile Keeper

    dongshuyan/compass-skills

    Local user-profile maintenance skill for Codex, Claude Code, OpenClaw, OpenCode, and other agent harnesses.

    753 GitHub stars~2.4k tokensUpdated 1 mo ago
    Auto-check passed

  • Assess Interview Candidate

    dongshuyan/compass-skills

    根据候选人简历与岗位要求生成可审计的后台评估、简明的候选人介绍、按岗位重要性排列的简历疑点、12–18 道可直接照读的面试题，以及支持重点标记和本机保存的离线 HTML。用于招聘方准备结构化面试、核验岗位能力和记录回答。不要用于求职者模拟面试、私人背景调查、心理或人格诊断、从敏感属性推断表现，或自动录用、淘汰、排序候选人。

    753 GitHub stars~2.2k tokensUpdated 1 mo ago
    Auto-check passed

  • Academic Humanizer

    dongshuyan/compass-skills

    Draft, audit, or minimally revise English- or Chinese-language academic prose to reduce formulaic, vacuous, mechanically repetitive, or process-leaking language while preserving claims, evidence…

    753 GitHub stars~4.2k tokensUpdated 1 mo ago
    Auto-check passed

Works with

Categories

Questions about Run History Skill Upgrader

What does Run History Skill Upgrader do?

Use real run evidence, validation failures, source drift, platform drift, and user feedback to plan and, only after explicit approval, apply structural upgrades to an existing skill. Run History Skill Upgrader is an agent skill from dongshuyan/compass-skills. Use real run evidence, validation failures, source drift, platform drift, and user feedback to plan and, only after explicit approval, apply structural upgrades to an existing skill.

When should I use Run History Skill Upgrader?

Run History Skill Upgrader fits situations like: the user asks to improve an existing skill from recent runs; recurring failures; outdated sources; excessive bloat.

How do I install Run History Skill Upgrader in Claude Code?

Run `npx skills add dongshuyan/compass-skills --skill run-history-skill-upgrader -a claude-code`. Or copy the skill folder (skills/run-history-skill-upgrader in dongshuyan/compass-skills) into .claude/skills/run-history-skill-upgrader in your project. Claude Code loads it when a task matches its description.

How do I install Run History Skill Upgrader in Codex?

Run `npx skills add dongshuyan/compass-skills --skill run-history-skill-upgrader -a codex`. Or copy the skill folder (skills/run-history-skill-upgrader in dongshuyan/compass-skills) into .agents/skills/run-history-skill-upgrader in your project. Codex loads it when a task matches its description.

Can I use Run History Skill Upgrader 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 dongshuyan/compass-skills --skill run-history-skill-upgrader -a cursor` (or -a gemini-cli, github-copilot or opencode for the others). To copy it by hand, put the folder in .cursor/skills/run-history-skill-upgrader, .gemini/skills/run-history-skill-upgrader, .github/skills/run-history-skill-upgrader and .opencode/skills/run-history-skill-upgrader in your project.

What does Run History Skill Upgrader need to run?

Going by SKILL.md and its folder, Run History Skill Upgrader needs Python for the scripts in its folder and the command-line tools its instructions call (python). Our summary lists: Python 3.

Does Run History Skill Upgrader 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 Run History Skill Upgrader 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 Run History Skill Upgrader use?

Run History Skill Upgrader 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 Run History Skill Upgrader use?

About 1.7k tokens (SKILL.md is roughly 6.7k characters). Agents keep only the skill's name and description in context until a task matches; then they load SKILL.md in full. Its references folder adds about 2.4k tokens, read only when the agent opens those files.

What are the alternatives to Run History Skill Upgrader?

Skills that share tags, products or a category with Run History Skill Upgrader: A2a Protocol (internet-court/internet-court-skill, 6.6k stars), Discord Bot Architect (davila7/claude-code-templates, 33k stars), A2a Protocol (TerminalSkills/skills, 163 stars) and Process Inbox (telegramdesktop/tdesktop, 33k stars). The comparison table on this page puts their stars, adoption, token cost, safety result and licence side by side.

Who maintains Run History Skill Upgrader?

dongshuyan (a GitHub user) maintains it in dongshuyan/compass-skills, which has 753 GitHub stars. The repository holds 9 skills in this directory. The repository was last updated on August 26, 2026.

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