Intent Compiler Skill

Intent Compiler is an Agent Skill for converting vague, compressed, raw thoughts into the most useful next artifact: a direct answer, rewrite, prompt, Codex-ready task, structured plan, PRD, architecture, workflow, research plan, message draft, evaluation checklist, or reusable spec.

This skill does not make the model smarter by itself. It packages a repeatable procedure for turning vague intent into useful artifacts.

Why It Exists

Users often think in fragments. They say "make this Codex ready", "this API docs thing feels weak", or "mobile checkout goes blank sometimes" because they are trying to move work forward, not because they have already chosen the right format. Models are good at expansion, but expansion without routing often creates the wrong thing at the wrong depth.

Intent Compiler treats raw thought as source material. Its core job is abstraction control: infer intent, classify the task, choose the lowest useful depth, generate the right artifact, and avoid turning every request into a heavy framework.

What It Solves

• Short notes that need structure.
• Prompts that should actually be plans, specs, or checklists.
• Product ideas that need analysis instead of polish.
• Coding ideas that need implementation-ready handoff.
• Agent or skill concepts that need decomposition.
• Tiny communication requests that should stay tiny.

Install As An Agent Skill

The root directory is the skill directory. SKILL.md lives at the repository root.

Install directly with npx from the root of the project where you want the skill available:

npx --yes intent-compiler copy .agents/skills/intent-compiler

This copies the packaged skill into .agents/skills/intent-compiler.

Or install the helper globally:

npm install -g intent-compiler
intent-compiler copy .agents/skills/intent-compiler

Or print the installed package path and copy/symlink it yourself:

npx --yes intent-compiler path
intent-compiler path

For clients that load skills from .agents/skills, copy or symlink this folder:

mkdir -p .agents/skills
cp -R /path/to/intent-compiler .agents/skills/intent-compiler

Or symlink it while developing:

mkdir -p .agents/skills
ln -s /path/to/intent-compiler .agents/skills/intent-compiler

Use

After installation, ask for transformations such as:

• "ack with sounds good"
• "turn this into a prompt: evaluate whether our API docs are enough for new integrators"
• "make this Codex ready: add resumable CSV import to the existing admin app"
• "think through this product idea"
• "can this be a skill?"

The skill will infer the target artifact, choose an abstraction depth, fill reasonable gaps, and produce a copy-pasteable result.

Validate, Test, Package

No external dependencies are required.

python scripts/validate_skill.py .
python -m unittest discover -s tests
python scripts/package_skill.py
make all
npm pack --dry-run

The package command writes dist/intent-compiler.zip.

Ten Short Examples

1. "make this less vague: we'll try to get the dashboard stuff done soon" -> clearer status update.
2. "turn this into a prompt: evaluate whether our API docs are enough for new integrators" -> refined evaluation prompt.
3. "make this Codex ready: add resumable CSV import to the existing admin app" -> implementation prompt with files, tests, and acceptance criteria.
4. "idea: a personal decision log that turns messy notes into tradeoff memos" -> product framing and MVP experiment.
5. "i want an agent that watches production errors and drafts incident updates" -> operational agent workflow.
6. "tell the team the launch slips because billing edge cases, but don't make it sound like panic" -> message draft.
7. "do developers actually trust generated migration plans?" -> research plan.
8. "could we make a skill for turning meeting notes into tickets?" -> skill architecture.
9. "mobile checkout goes blank after login only sometimes" -> debugging plan.
10. "ack with sounds good" -> Sounds good.

See examples/ for complete versions.

Design Principles

• Infer and proceed when the missing details are non-blocking.
• Use the lowest depth that creates useful output.
• Make assumptions visible but lightweight.
• Keep internal reasoning rigorous and the user surface simple.
• Optimize for artifacts the user can immediately use.
• Treat prompts as intermediate representations, not the default destination.
• Escalate to architectures, workflows, and agents only when scope justifies it.

Prior Art

Intent Compiler is not claiming to invent prompting, agents, planning, or reflection. It builds on prompt engineering, metaprompting, Chain-of-Thought, Plan-and-Solve, ReAct, Tree of Thoughts, Reflexion, Generative Agents, DSPy, early autonomous agent systems, and filesystem-packaged Agent Skills.

Its contribution is packaging intent compilation as a lightweight skill with explicit depth control, artifact recipes, anti-overengineering rules, examples, and evals. See references/prior-art.md.

What Is Novel And What Is Not

Novel enough to be useful:

• A compact routing procedure for choosing the best next representation.
• An explicit depth ladder that stops small tasks from becoming large systems.
• Artifact recipes that make outputs operational instead of merely polished.

Not novel:

• Prompt writing.
• Planning.
• Reflection.
• Agent decomposition.
• Storing procedural knowledge in files.

Future Work

Possible extensions include a typed intent IR schema, CLI demo, web UI, browser extension, Codex integration helpers, local memory of user task patterns, a model-graded eval harness, artifact-specific subskills, workflow DAG compilation, multi-agent execution, prompt comparison tools, traces for transformations, and export to PRD/Codex/Linear/GitHub issues.

Repository Structure

intent-compiler/
  SKILL.md
  README.md
  references/
  examples/
  evals/evals.json
  package.json
  bin/intent-compiler.js
  scripts/validate_skill.py
  scripts/package_skill.py
  tests/test_validate_skill.py