compass-skills

Start here: Use & develop your own Skill ecosystem

A practical tutorial for using SKILL.md, auditing reusable skills, drafting skills with AI, extracting real workflows, and building a local Skill ecosystem.

npx skills add dongshuyan/compass-skills --skill '*' -a claude-code

COMPASS Skills gives AI agents seven local skills: four runtime collaboration skills, two run-history skill-engineering skills, and one academic humanization skill for avoiding and removing AI-sounding prose.

The project currently ships seven SKILL.md skills:

For multi-skill repositories, install only the functions you actually need. The run-history pair supports skill engineering; academic-humanizer helps authors avoid AI-sounding language while drafting and remove it from existing academic prose.

Quick Start

List the available skills before installing:

npx skills add dongshuyan/compass-skills --list

Install all skills for Claude Code:

npx skills add dongshuyan/compass-skills --skill '*' -a claude-code

Install all skills for both Codex and Claude Code:

npx skills add dongshuyan/compass-skills --skill '*' -a codex -a claude-code

After installation, invoke the skills directly in an AI conversation:

$task-clarifier
$task-forest
$session-handoff-prompt
$user-profile-keeper
$run-history-skill-builder
$run-history-skill-upgrader
$academic-humanizer

For manual installation, copy the seven folders under skills/ into the agent's local skills directory and keep their references/, scripts/, evals/, and agents/ subdirectories intact.

Why COMPASS Exists

Long-running agent work needs four kinds of state:

• User context: communication preferences, risk boundaries, recurring omissions, and collaboration style.
• Project context: where the current request fits, what it depends on, and how far it has progressed.
• Goal context: how the current task contributes to the original objective and whether it still matches it.
• Handoff context: what a new AI conversation needs to continue the current task without replaying the whole transcript.

COMPASS organizes that state into four local workflows:

1. A local profile that the user can inspect and correct.
2. A repo-local task graph that survives AI conversation boundaries.
3. A paste-ready continuation prompt for a new AI conversation.
4. A clarification gate before ambiguous or risky execution.

How The Core And Meta Skills Work Together

task-clarifier is the entry point for ambiguous, high-cost, high-risk, evidence-sensitive, or externally visible work. It first identifies the user-owned decisions that must be made, asks 1-3 focused questions with recommended answers, confirms shared understanding, and only then searches or executes.

task-forest records long-running work structure: why a task exists, where it fits, how far it progressed, what changed, and what remains unresolved.

session-handoff-prompt turns the current AI conversation, explicit transcripts, workspace evidence, and optional task-forest exports into a concise prompt for the next AI conversation. It reads task-forest as structured context but never modifies it.

user-profile-keeper stores collaboration preferences locally. Future AI conversations use the profile to ask relevant questions and apply the right risk boundary. Current files, logs, and user-provided context remain the authority; secrets stay out of the profile.

run-history-skill-builder turns a completed or repeatedly refined workflow into a new skill package or a plan-only design. If the request is really about changing an existing skill, it hands the job off instead of editing that skill directly.

run-history-skill-upgrader takes the next step for existing skills: it automatically reads session evidence from real execution, encountered and resolved difficulties, validation results, and user feedback, then produces a concrete upgrade plan and stops. Only after explicit approval of that plan does it edit files. In practice, this is the simplest controlled self-evolution loop for skills: periodically run a target skill, accumulate real session evidence, then let the upgrader turn that evidence into a reviewed upgrade plan and, after approval, an applied change.

academic-humanizer helps authors avoid AI-sounding language while drafting and remove it from existing academic prose. It targets formulaic, vacuous, mechanically repetitive, and process-leaking patterns while protecting claims, evidence strength, quotations, formulas, citations, technical names, modality, logic, and scope. The result aims to read as natural, credible scholarly writing and to reduce the likelihood that readers perceive it as AI-generated; it does not promise a universal authorship judgment.

user-profile-keeper    -> who is the user and how should we collaborate?
task-forest            -> where does this task fit and is it still aligned?
session-handoff-prompt -> what should the next AI conversation know to continue now?
task-clarifier         -> what should the agent do now?
run-history-skill-builder  -> how do we package this proven workflow as a new skill?
run-history-skill-upgrader -> how does a skill self-evolve safely from real session evidence?
academic-humanizer         -> how do we remove AI-sounding prose without changing its claims?

Task Clarifier Example

A vague request is turned into a checked requirement before the agent recommends anything.

Formatted from a live terminal run. Terminal status lines are omitted.

Turn 1: vague request

User

I want to buy a suitcase, can you tell me which one is the best?

$task-clarifier

Before recommending a product, the skill turns "best" into concrete decision criteria:

1. Use case — What will you use the suitcase for most?
   • Options: business travel, leisure vacations, extended travel, or custom situation.
   • Recommendation: start with the primary use case, because it changes size, weight, and feature priorities.
2. Budget — What price range is realistic?
   • Options: under $100, $100-300, $300-600, $600+, or custom budget.
   • Recommendation: $100-300 is often the best durability-to-cost range for most travelers.
3. Meaning of "best" — Which priority wins?
   • Options: durability, light weight, price, warranty/service, organization, or custom priority.
   • Recommendation: durability is the most universal priority.

User answer

1A 2C 3A

Business travel, $300-600, maximum durability.

Turn 2: narrow the product class

$task-clarifier

The first answers narrow the problem, but two choices still change the recommendation:

1. Bag type — Carry-on or checked bag?
   • Recommendation: carry-on for most business trips, faster airport flow, and lower damage risk.
2. Material — Hard shell or soft-sided?
   • Recommendation: hard shell for durability and professional appearance.

User answer

Checked bag, hard shell.

Turn 3: resolve the final size

$task-clarifier

One last decision remains:

1. Checked-bag size — Compact, medium, or full-size?
   • Recommendation: 26-27 inches handles many business