dongshuyan/compass-skills

COMPASS Skills – A Toolkit of Re‑usable Agent Skills

What it is

• A collection of ten self‑contained SKILL.md packages that can be added to any LLM‑powered “harness” (e.g., Claude Code, OpenAI Codex). Each package describes, in plain Markdown, how an AI agent should behave for a specific piece of workflow‑management or writing work.
• The skills are designed to help long‑running AI agents keep track of context that normally gets lost when a conversation ends – things like user preferences, task dependencies, pause points, and hand‑off information.

Core ideas

Skill	Main purpose
task-clarifier	Turns vague, high‑risk requests into concrete, agreed‑upon requirements before any execution.
task-forest	Maintains a repo‑local DAG of goals, subtasks, dependencies, progress, and conversation history.
pause-and-resume	Saves a safe checkpoint inside the same conversation so work can be paused and later continued without re‑doing work.
session-handoff-prompt	Summarises the current conversation, task‑forest, and evidence into a copy‑‑and‑paste prompt for a brand‑new AI session.
user-profile-keeper	Stores a local, auditable profile of the user’s communication style, risk tolerance, and recurring context.
run-history-skill-builder	Converts a finished workflow (or a repeatedly refined one) into a new reusable skill package or a design plan.
run-history-skill-upgrader	Analyses real execution evidence and proposes a concrete upgrade plan for an existing skill, applying changes only after explicit approval.
clear-communication	Turns raw source material into a reader‑friendly explanation, report, or instruction while preserving facts, uncertainties, and verification state.
academic-humanizer	Rewrites English/Chinese academic prose to sound natural and scholarly, removing “AI‑sounding” patterns without altering claims.
assess-interview-candidate	Generates an auditable interview‑prep package (resume portrait, timeline estimates, question list) from a resume and job description.

How you get the skills

• The repository ships the skills as plain folders under skills/. Each folder contains a SKILL.md description, optional references/, scripts/, assets/, and a YAML file (agents/*.yaml) that tells a harness how to expose the skill.
• Installation is done with the provided CLI wrapper:

  npx skills add dongshuyan/compass-skills --skill '*' -a claude-code   # all skills for Claude Code
  npx skills add dongshuyan/compass-skills --skill clear-communication -a codex -g   # single skill, user‑wide
  

• For environments that don’t support the wrapper, you can copy the desired skill folder into the host’s skill directory (e.g., .claude/skills/ or .agents/skills/).

Typical workflow

1. Start with task-clarifier to make sure the request is well defined.
2. Record the resulting plan in task-forest so the DAG survives conversation boundaries.
3. If you need to stop mid‑stream, invoke pause-and-resume – it writes a checkpoint in the conversation log.
4. When you must switch to a fresh AI session, run session-handoff-prompt to generate a concise prompt that contains the essential context.
5. Throughout the project, the user-profile-keeper keeps the user’s preferences in sync.
6. After a run finishes, use run-history-skill-builder to turn the whole workflow into a reusable skill, or run-history-skill-upgrader to evolve an existing skill based on real evidence.
7. For any explanatory output, pipe the result through clear-communication; for academic drafts, add academic-humanizer.
8. If you’re hiring, assess-interview-candidate prepares a structured interview brief.

Why it matters

• State persistence: AI agents normally forget everything once the chat ends. COMPASS gives them a lightweight, file‑based way to persist user, project, goal, pause, and hand‑off state.
• Safety & alignment: By forcing a clarification step before costly actions, the toolkit reduces the chance of ambiguous or risky outputs.
• Self‑evolution: The run‑history builder/upgrader pair implements a controlled “learn from real runs” loop without any hidden online training.
• Modular: You install only the skills you need; each skill is just markdown + optional assets, so it works with any LLM harness that understands the SKILL.md format.

Maturity & status

• The repository is marked alpha – the core concepts are functional, but the author notes that the skills are still experimental and may change.
• No compiled binaries or external services are required; the only dependency is the host harness’s ability to read SKILL.md and optionally the agents/*.yaml metadata.

License

• Distributed under the repository’s LICENSE (the badge shows a permissive open‑source license, likely MIT or Apache‑2.0 – see the LICENSE file for exact terms).

Who might use it

• Developers building custom AI assistants that need to survive multi‑step projects.
• Teams that want a reproducible “agent‑operating‑system” for internal tooling.
• Researchers exploring safe, stateful LLM workflows.

---

All information above is taken directly from the repository’s README; no additional features have been inferred.