CoMPaSS-prompt-framework

🧭 CoMPaSS Prompt Framework

Analysis-first prompting for consequential prompts, agent briefs, and decisions.

Understand what the user is doing and why, before you write a word of the prompt. Then define what done looks like.

Explore the skill · Read the paper · Documentation · Contribute · Get help · Security

Prompts that solve the wrong problem

A well-formed prompt can still fail completely. Asked to "write something to tell my team we're switching to a weekly on-call rotation," a model writes a tidy announcement, and misses that the team is already annoyed about pager load and has to be won over. Asked to "fix" a flaky test, an agent adds a retry, CI turns green, and a race condition ships to production.

Most prompt frameworks (RTF, CO-STAR, RISEN, CRISPE) start at prompt-writing and assume the author already knows the real objective. CoMPaSS adds the missing step: a short, mandatory use-case analysis before construction, then a prompt whose optional parts appear only when a stated rule fires, and which always defines how the result is verified.

Before writing a prompt, work out the Action (what is the user doing?), the Intention (why?), the Deliverable or Decision (what must exist at the end?), and the Efficient path (what is the cheapest reliable route?).

Status: research-grade. CoMPaSS is an original proposal grounded in published prompting research and vendor guidance. It has not been benchmarked, and nothing in this repository claims it beats other frameworks. A pre-registered evaluation plan defines how to test it.

⚙️ What the skill brings to your agent

🧩 How it works

flowchart TD
    A[Raw requirement] --> B[C: Comprehend<br/>Action · Intention · Deliverable · Path]
    B --> C{Tier gate C-1}
    C -- Tier 0 --> D[Answer or ask directly]
    C -- Tier 1 or 2 --> E{Ambiguity gate C-2}
    E -- Low --> F[Ask up to 3 questions]
    F --> B
    E -- Medium or high --> G[Mission → Provisions → order? → anchors? → Scope → Success spec]
    G --> H[Run, check against the Success spec, revise the failing component]

Uppercase letters are mandatory; lowercase letters are optional. The component reference gives each one a full page.

📥 Get started

The skill lives in skills/compass-prompt-framework/. Keep that folder intact (SKILL.md, references/, assets/, scripts/, tests/) so the skill can resolve its resources.

Claude Code: plugin

/plugin install compass-prompt-framework --marketplace YourAKShaw/CoMPaSS-prompt-framework

That one-step form needs Claude Code 2.1.275 or later. On earlier versions, add the marketplace first:

/plugin marketplace add YourAKShaw/CoMPaSS-prompt-framework
/plugin install compass-prompt-framework@compass-prompt-framework

Claude Code: personal or project skill

git clone https://github.com/YourAKShaw/CoMPaSS-prompt-framework.git
mkdir -p ~/.claude/skills
cp -R CoMPaSS-prompt-framework/skills/compass-prompt-framework ~/.claude/skills/

For a project installation, copy it to .claude/skills/ in that project instead. The entry point must be ~/.claude/skills/compass-prompt-framework/SKILL.md (or .claude/skills/compass-prompt-framework/SKILL.md). Then type /compass-prompt-framework in Claude Code, or describe a high-stakes prompt and let Claude select the skill. See the Claude Code skills documentation.

Claude apps: upload a ZIP

1. Download compass-prompt-framework-<version>.zip from the latest release, or build it from a clone:

   cd CoMPaSS-prompt-framework/skills
   zip -r ../compass-prompt-framework.zip compass-prompt-framework -x '*/node_modules/*'
   

   The archive must contain one top-level compass-prompt-framework/ folder with SKILL.md directly inside it.

2. Enable Code execution and file creation under Settings → Capabilities. Organization accounts also need Skills enabled by an administrator.

3. Open Customize → Skills, select + → Create skill → Upload a skill, and upload the ZIP. Switch it on.

See Claude's upload instructions.

Skills CLI: other agents

npx skills add YourAKShaw/CoMPaSS-prompt-framework

Claude API

Upload the skill folder to /v1/skills and reference it in container.skills with the code execution tool. The usage guide has the exact requests.

Check the package

node ~/.claude/skills/compass-prompt-framework/scripts/validate-skill.ts

This offline check needs Node.js 22.18 or later. A pass confirms the package is intact; confirm activation in your host separately. The installation commands follow the linked host and CLI documentation, and the plugin manifests pass claude plugin validate; installation has not been exercised on every host.

💬 Put it to work

Brief an agent

Use CoMPaSS to brief a subagent: "The checkout-service CI keeps failing on test_apply_discount at random. Fix it." Tests run with pytest.

Frame a decision

Use CoMPaSS to write the prompt for this decision: should we move our analytics dashboards from Postgres to ClickHouse? Table sizes and slow queries are below.

Draft a deliverable

Use CoMPaSS to write a prompt for an announcement telling my team we're moving to a weekly on-call rotation. People are already annoyed about pager load.

Review a prompt

Review this system prompt against CoMPaSS and list the mandatory gaps first.

These show the analysis the skill performs; they are not claims of evaluated performance. For a trivial question, the skill's first rule is to skip itself.

Optional helpers

Zero-dependency TypeScript scripts, run directly by Node.js 22.18+:

node skills/compass-prompt-framework/scripts/analyze-requirement.ts "Should we move to ClickHouse?"
node skills/compass-prompt-framework/scripts/scaffold-prompt.ts "Fix the flaky checkout test."
node skills/compass-prompt-framework/scripts/validate-prompt.ts prompt.md
node skills/compass-prompt-framework/scripts/evaluate-skill.ts plan

They draft analysis cards and prompt skeletons from keyword heuristics, check a prompt's structure, and score evaluation runs. Treat their drafts as starting points.

📚 Inside the skill

📂 Inside the repository

CoMPaSS-prompt-framework/
├── skills/compass-prompt-framework/   # The Agent Skill (what gets installed)
│   ├── SKILL.md                       # Entry point
│   ├── references/                    # Paper, generated extracts, component reference
│   ├── assets/                        # Component table, templates, decision tree, examples
│   ├── scripts/                       # Helpers, validators, evaluation harness, generator
│   └── tests/                         # node:test suites and fixtures
├── docs/                              # Usage, architecture, evaluation, maintenance
├── .claude-plugin/                    # Claude Code plugin and marketplace manifests
├── .github/                           # Workflows, issue forms, PR template, contributing, support
├── CHANGELOG.md
├── SECURITY.md                        # Vulnerability reporting policy
└── LICENSE                            # MIT License

Validate the package

From the repository root, with Node.js 22.18+ and Python 3.9+:

npm ci
npm run check

This runs the package validator, the reference drift check, the test suite, and lint. It checks package integrity and consistency with the paper. Prompt quality and agent behavior need the evaluation plan.

🤝 Contributing and support

Real failure cases are the most valuable contribution: a request where CoMPaSS misread intent, or where a simpler framework would have done better. So are clearer rules, new examples, and evaluation runs. Start with the contribution guide, use the issue forms, or read the support guide. Report vulnerabilities privately as described in the security policy, not in a public issue.

License

Distributed under the MIT License. See LICENSE for details.