compass-skills

中文 · Security · License

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 ten local skills: five runtime collaboration skills, two run-history skill-engineering skills, two writing and communication skills, and one local hiring-support skill. It also includes an optional Codex session-title plugin, installed separately.

The project currently ships ten SKILL.md skills:

The optional Agent Clarity title plugin lives under plugins/clarity-session-titles/; it has a separate installer and is not one of these ten portable skills.

For multi-skill repositories, install only the functions you actually need. Use pause-and-resume when the same AI conversation will remain available; use session-handoff-prompt when work must move to a fresh conversation. The run-history pair supports skill engineering. Use clear-communication to organize explanations for the reader, and academic-humanizer to improve academic prose without changing its claims.

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
$pause-and-resume
$session-handoff-prompt
$user-profile-keeper
$run-history-skill-builder
$run-history-skill-upgrader
$clear-communication
$academic-humanizer
$assess-interview-candidate

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

Why COMPASS Exists

Long-running agent work needs five 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.
• Pause context: the safe stopping point, remaining work, non-repeatable effects, and first action when the same AI conversation resumes.
• Handoff context: what a new AI conversation needs to continue the current task without replaying the whole transcript.

COMPASS organizes that state into five 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 cooperative pause checkpoint for continuing in the same AI conversation.
4. A paste-ready continuation prompt for a new AI conversation.
5. 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.

pause-and-resume stops an unfinished task at the nearest safe boundary, records what must and must not be repeated, and continues from that checkpoint when the user returns to the same AI conversation. It creates no file solely for pausing.

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.

assess-interview-candidate prepares human recruiters for a structured interview. It keeps detailed evidence and validation data in a local audit layer while presenting only a candidate overview, job-relevant resume uncertainties, and 12-18 directly readable questions in the offline HTML. It never authorizes automatic hiring, rejection, or ranking.

user-profile-keeper    -> who is the user and how should we collaborate?
task-forest            -> where does this task fit and is it still aligned?
pause-and-resume       -> where should this AI conversation stop and continue later?
session-handoff-prompt -> what should the next AI conversation know to continue now?
task-clarifier         -> what should the agent do now?
clear-communication    -> what does this reader need to understand or do?
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?
assess-interview-candidate -> how do we prepare a focused, evidence-bounded human interview?

Clear communication

clear-communication helps an agent turn source material into explanations, progress reports, comparisons, instructions, and documents that a reader can understand and use. It preserves facts, important conditions, uncertainty, and what has actually been checked. Use it when the material is accurate but hard to follow, or when a detailed record needs to become a useful explanation.

The package contains the writing workflow, hypothetical examples, source notes, and retained license notices. Its optional agents/openai.yaml supplies interface metadata. The writing workflow itself has no script or external-service dependency.

Install one skill, in the scope you need

Install into the current project for Codex and Claude Code:

npx skills add dongshuyan/compass-skills --skill clear-communication -a codex -a claude-code

Add -g for a user-level installation across that user's projects:

npx skills add dongshuyan/compass-skills --skill clear-communication -a codex -a claude-code -g

For manual installation, copy the entire skill folder, including references/ and its license notices. Use the host's actual discovery directory: