compass-skills

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.

The project currently ships ten SKILL.md skills:

Skill	Purpose
task-clarifier	Aligns goals, scope, evidence, acceptance criteria, and risk boundaries before ambiguous, costly, or externally visible work.
task-forest	Maintains a repo-local task forest / DAG with goals, subtasks, dependencies, progress, deviations, todos, decisions, and conversation history.
pause-and-resume	Cooperatively pauses unfinished work at a safe boundary and resumes it from a precise checkpoint in the same AI conversation.
session-handoff-prompt	Compresses the current AI conversation's goal, progress, constraints, and next steps into a paste-ready prompt for a new AI conversation.
user-profile-keeper	Maintains a local, auditable, correctable collaboration profile for communication preferences, risk style, and recurring working context.
run-history-skill-builder	Turns completed or repeatedly refined run history into a new reusable skill package or a reviewed skill-design plan.
run-history-skill-upgrader	Automatically turns session evidence from real execution, encountered and resolved difficulties, validation results, and user feedback into an upgrade plan for an existing skill, forming the simplest controlled self-evolution loop; it applies changes only after explicit approval.
clear-communication	Organizes explanations, reports, comparisons, and instructions around the reader’s task while preserving facts, conditions, uncertainty, and verification state.
academic-humanizer	Helps write or revise English and Chinese academic prose by removing formulaic AI-like patterns and restoring a natural scholarly voice while preserving claims, evidence strength, and logical relations.
assess-interview-candidate	Turns an authorized resume and job description into an auditable evidence layer and a concise three-part offline interviewer report, with locally sanitized resume portraits and bounded timeline-age estimates kept outside scoring.

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 chec