New: 98,000+ skills indexed from GitHub repos with 100+ stars · every skill safety-checkedBrowse top skillsTop skills
Esc to closeBrowse all skills
Submit a skillBrowse skills
Submit a skillBrowse skills

Agent skill

Prompt Optimizer

by Cranot in Cranot/roam-code

Optimize a vague subagent brief into a structured Agent task brief carrying falsifier, invariant, source-citation rule, and concrete-noun anchors.

Apache-2.0Auto-check passedAgent Workflows

Install Prompt Optimizer

skills CLI
$ npx skills add Cranot/roam-code --skill prompt-optimizer -a claude-code

Project install by default; add -g for ~/.claude/skills/.

GitHub CLI
$ gh skill install Cranot/roam-code prompt-optimizer --agent claude-code

Project scope by default; add --scope user for a personal install. Needs GitHub CLI 2.90.0 or later (public preview).

Manual copy
$ git clone --depth 1 https://github.com/Cranot/roam-code.git skills-src && mkdir -p .claude/skills && cp -r skills-src/.claude/skills/prompt-optimizer .claude/skills/prompt-optimizer && rm -rf skills-src

Use ~/.claude/skills/ instead of .claude/skills for a personal install. The folder must contain SKILL.md.

Claude Code skills documentation · loads skills from .claude/skills/

Facts

Skill name
prompt-optimizer
GitHub stars
517
Token cost
~1.1k tokens
SKILL.md length
449 words
Files
2 (incl. references)
Skills in repo
9
Repo updated
First seen
Licence
Apache-2.0

At a glance

Optimize a vague subagent brief into a structured Agent task brief carrying falsifier, invariant, source-citation rule, and concrete-noun anchors.

  • Works in 3 steps: Preserve the vanilla brief verbatim.… → Apply the 6-field template. Load → Iterate v1 → v2 → final. Each pass names…
  • Tasks that involve Prompt engineering
  • SKILL.md covers When to invoke, Three rules, Roam-code dispatch matrix and Epistemic tags, plus 3 more sections
  • Instructions only: no scripts, shell commands, URLs or credentials in SKILL.md

What it does

Prompt Optimizer is an agent skill from Cranot/roam-code. Optimize a vague subagent brief into a structured Agent task brief carrying falsifier, invariant, source-citation rule, and concrete-noun anchors. Invoke before Agent tool dispatch (Explore / general-purpose / Plan), before drafting research-wave specs, before writing HANDOVER memos, before composing /loop self-prompts. Source: agi-in-md Comparator-Aware Prompt Diagnostics paper + 81-prism Twinks catalog.

Its SKILL.md is about 1.1k tokens, which your agent loads only when the skill is triggered. The skill folder holds 2 other files, including reference files (for example `references/optimized-prompt-template.md`).

It sits in Agent Workflows, covering Prompt engineering, Subagents and Citation management. It works with Model Context Protocol. The repository describes itself as: Local codebase intelligence CLI + MCP server for AI coding agents: SQLite code graph, 28 languages, 287 commands, 246 MCP tools, change-safety gates, audit evidence, zero API keys. The licence is Apache-2.0.

When your agent uses it

  • Tasks that involve Prompt engineering
  • Tasks that involve Subagents
  • Tasks that involve Citation management

Example prompts

  • “/prompt-optimizer”

Workflow steps

3 steps, taken from the first numbered list in SKILL.md.

  1. Preserve the vanilla brief verbatim. Copy the original first.
  2. Apply the 6-field template. Load
  3. Iterate v1 → v2 → final. Each pass names one ornament removed

What it can do on your machine

Read from SKILL.md and the folder at commit 4856519. It shows what the files ask for, not the result of running them.

  • Tool permissions

    Pre-approves nothing: there is no allowed-tools line, so your agent's usual permission prompts apply.

    From allowed-tools in the SKILL.md frontmatter.

  • Runs code

    No scripts in the folder and no shell commands in SKILL.md.

    From the folder's file list and the shell code blocks in SKILL.md.

  • Network

    No URLs in SKILL.md.

    From URLs in SKILL.md, links to its own repository left out.

  • Credentials

    Names no API keys, tokens, secrets or passwords.

    From names ending in _API_KEY, _TOKEN, _SECRET, _KEY or _PASSWORD in SKILL.md.

Context cost

Prompt Optimizer loads about 1.1k tokens when it runs, and up to ~2.2k if it reads all its reference files. Until then it costs about 106 tokens; SKILL.md has 449 words of instructions outside code blocks.

Always · name and description, kept in context so the agent knows when to use it
~106
When it runs · the whole SKILL.md, loaded when a task matches
~1.1k
With references · SKILL.md plus every file in references/, read only if the agent opens them
~2.2k

Estimates: characters ÷ 4, the usual rule of thumb; real counts depend on the model's tokenizer. Scripts and assets cost tokens only if the agent reads them.

Safety

Auto-check passed

The automated check found no risky patterns in SKILL.md.

Automated static check — not a guarantee. Review scripts before installing. It scans the text of SKILL.md for risky patterns (piping downloads into a shell, reading credential files, hidden Unicode, destructive commands); files beside SKILL.md are not scanned.

SKILL.md

The full file from Cranot/roam-code at commit 4856519, republished under its Apache-2.0 licence (© Cranot). 449 words, ~1,054 tokens.

Download SKILL.mdSave it as .claude/skills/prompt-optimizer/SKILL.md (or your agent's skills folder). This skill also uses 1 other file; get the full folder from GitHub.
name
prompt-optimizer
description
Optimize a vague subagent brief into a structured Agent task brief carrying falsifier, invariant, source-citation rule, and concrete-noun anchors. Invoke before Agent tool dispatch (Explore / general-purpose / Plan), before drafting research-wave specs, before writing HANDOVER memos, before composing /loop self-prompts. Source: agi-in-md Comparator-Aware Prompt Diagnostics paper + 81-prism Twinks catalog.

Prompt Optimizer

A structured-assignment generator for subagent dispatch. The brief is the dominant variable for subagent quality, not the model (agi-in-md LAW 1). This skill forces every dispatch through a stable 6-field shape so subagents return source-grounded findings instead of summary-mode paragraphs.

When to invoke

  • Before any Agent dispatch (Explore / general-purpose / Plan)
  • Before drafting a dev/SPEC-*.md research wave
  • Before writing a HANDOVER memo a future agent reads cold
  • Before composing a /loop self-pacing prompt

Skip for maximally-specific requests (one-symbol fact lookup, single-line continuation, conversational reply with full context already in window).

Three rules

  1. Preserve the vanilla brief verbatim. Copy the original first. Normalize only path quoting. Without the vanilla as comparator, A/B scoring is meaningless.

  2. Apply the 6-field template. Load references/optimized-prompt-template.md and fill every field: Task, Target, Grounding rules, Process, Final output, Falsifier. Anchor every claim on concrete-noun terminals per LAW 4 (see roam-code/CLAUDE.md "Concrete-noun anchor vocabulary" for the accepted set).

  3. Iterate v1 → v2 → final. Each pass names one ornament removed or one anchor sharpened. Stop when the next edit would not change the next agent's action (CLAUDE.md maintenance contract: Behavioral Coverage × Token Cost = Constant).

Roam-code dispatch matrix

SubagentBrief shapeFalsifier example
Explorebreadth (quick / medium / very thorough) + exact symbol or pattern"If you do not find X, that is the answer — do not invent it"
general-purposefile paths + line numbers + exact API up front"Every claim cites file:line; unsourced claims get deleted"
Plantrade-off matrix + rejected alternatives + chosen path with rationale"Name two rejected paths; if none, design space was too narrow"

When dispatching ≥4 agents in parallel (memory: feedback_continuous_saturation_refill_to_four), optimize each brief independently — subagents share no context.

claude subagent is BANNED on this host (memory: feedback_no_claude_subagent, W1072 worktree-MAX_PATH); route every optimized brief to Explore / general-purpose / Plan.

Show full SKILL.md (157 more words)Show less

Epistemic tags

Every claim in the optimized brief carries one tag:

  • [SOURCE] — directly read from file/log/output (maps to roam direct confidence)
  • [DERIVED] — computed from sources (maps to derived)
  • [ASSUMED] — working hypothesis pending verification (maps to inferred)
  • [UNVERIFIABLE] — out-of-scope or unprovable from artifacts at hand (maps to legacy_fallback)

Canonical vocabulary: src/roam/evidence/_vocabulary.py → CLAIM_CONFIDENCES (4-member closed enum).

Output shape

For a rewrite return:

  • vanilla — original brief verbatim
  • optimized_final — dispatch-ready text
  • iteration_notes — concise v1 / v2 / final diff rationale
  • measurement_plan — 8-axis scoring plan when A/B was requested

For an A/B return:

  • Dispatch parameters (subagent_type, working dir, identical context)
  • 8-axis comparison from references/optimized-prompt-template.md
  • Final opinion + caveats

Reference

references/optimized-prompt-template.md carries the 6-field skeleton, the Codex CLI cross-family pattern, the 8-axis scoring rubric, and the documented failure modes.

Upstream

Source: agi-in-md/.agents/skills/prompt-optimizer/. Empirical backing: the 81-prism catalog with 22 top-tier "Twinks" scored on production code + the Comparator-Aware Prompt Diagnostics paper. The 12 agi-in-md laws are already imported into roam-code/CLAUDE.md; this skill operationalizes them at dispatch time.

© Cranot, Apache-2.0. Rendered from Markdown: HTML in the file is shown as text, images as links, and headings moved down two levels. Raw file

Files

SKILL.md and 1 other file (references) in .claude/skills/prompt-optimizer of Cranot/roam-code.

  • SKILL.md
  • references/optimized-prompt-template.md

Open the folder on GitHubat commit 4856519

Compare with similar skills

Prompt Optimizer next to the 5 skills that share the most tags, products or categories with it. Stars are the repository's; “used in” counts other GitHub owners with a copy.

Prompt Optimizer compared with similar skills
SkillStarsUsed inTokensAuto-checkLicenceRepo updated
Prompt Optimizer this skillCranot/roam-code517—~1.1kAutomated safety check: PassApache-2.0
Agentforce GenerateSalesforceAIResearch/agentforce-adlc1141 repos~7.4kAutomated safety check: PassCustom licence
Pi AgentK-Dense-AI/scientific-agent-skills48k1 repos~2.1kAutomated safety check: PassMIT
Tapd Story PlanTencentBlueKing/bk-bcs840—~886Automated safety check: PassCustom licence
Tapd Story TasksTencentBlueKing/bk-bcs840—~900Automated safety check: PassCustom licence
Claude Code Agent Developmentanthropics/claude-plugins-official38k8 repos~2.8kAutomated safety check: PassApache-2.0

Similar skills

  • Agentforce Generate

    SalesforceAIResearch/agentforce-adlc

    Build, modify, audit, repair, optimize, debug, and deploy agents with Agentforce Agent Script.

    114 GitHub starsUsed in 1 repo~7.4k tokens
    Agent WorkflowsAuto-check passed

  • Pi Agent

    K-Dense-AI/scientific-agent-skills

    Builds with and operates Pi, the minimal terminal coding harness.

    48k GitHub starsUsed in 1 repo~2.1k tokens
    AI & LLM EngineeringAuto-check passed

  • Tapd Story Plan

    TencentBlueKing/bk-bcs

    迭代执行流水线开发计划阶段。基于 spec.md 调用 /speckit.plan 以测试驱动开发模式构建 开发计划、技术调研与数据模型，并在同一 subagent 内就地做文档级合规自检，产出 plan-report.md。

    840 GitHub stars~886 tokensUpdated today
    Agent WorkflowsAuto-check passed

  • Tapd Story Tasks

    TencentBlueKing/bk-bcs

    迭代执行流水线任务生成阶段。基于 plan.md / research.md 调用 /speckit.tasks 生成全量任务， 随后调用 /speckit.analyze 验证产物合规。两段命令通过两次 subagent 隔离执行。

    840 GitHub stars~900 tokensUpdated today
    Agent WorkflowsAuto-check passed

  • Claude Code Agent Development

    anthropics/claude-plugins-official

    Official

    Explains how to write agents for Claude Code plugins: the markdown file with YAML frontmatter, trigger descriptions, model and color settings, and system prompt design.

    38k GitHub starsUsed in 8 repos~2.8k tokens
    Agent WorkflowsAuto-check passed

  • Clone App Pat Pro

    per-simmons/clone-app-pat-pro-public

    Clones any web app pixel-for-pixel from a URL. An agent skill from per-simmons/clone-app-pat-pro-public.

    259 GitHub stars~1.9k tokensUpdated 4 mo ago
    Agent WorkflowsAuto-check: notes

More from Cranot/roam-code

All 9 skills in this repo

  • Roam

    Cranot/roam-code

    Codebase comprehension via roam-code CLI. An agent skill from Cranot/roam-code.

    517 GitHub stars~2.4k tokensUpdated 4 days ago
    Auto-check passed

  • Roam Agent Guidance

    Cranot/roam-code

    Review and maintain the technical instructions Roam gives coding agents: shipped skills, tool descriptions, preset guidance and generated instruction blocks.

    517 GitHub stars~1.3k tokensUpdated 4 days ago
    Auto-check passed

  • Roam Evidence Hardening

    Cranot/roam-code

    Investigate and harden Roam detectors, CLI/MCP result contracts, and evidence consumers when dogfooding or correcting incomplete, misleading, or inconsistent analysis.

    517 GitHub stars~1.5k tokensUpdated 4 days ago
    Auto-check passed

  • Roam Lesson Maintenance

    Cranot/roam-code

    Turn a reproduced or recurring Roam failure into a durable correction, regression control or narrowly scoped project skill, and reconcile conflicting lessons.

    517 GitHub stars~1.2k tokensUpdated 4 days ago
    Auto-check passed

  • Roam Measurement Design

    Cranot/roam-code

    Design or interpret a comparison of Roam performance, detector accuracy, retrieval or workflow value.

    517 GitHub stars~1.2k tokensUpdated 4 days ago
    Auto-check passed

  • Roam Milestone Planning

    Cranot/roam-code

    Define or revise a Roam product milestone and its engineering, adoption and offer-readiness sequence.

    517 GitHub stars~1.2k tokensUpdated 4 days ago
    Auto-check passed

Works with

Categories

Questions about Prompt Optimizer

What does Prompt Optimizer do?

Optimize a vague subagent brief into a structured Agent task brief carrying falsifier, invariant, source-citation rule, and concrete-noun anchors. Prompt Optimizer is an agent skill from Cranot/roam-code. Optimize a vague subagent brief into a structured Agent task brief carrying falsifier, invariant, source-citation rule, and concrete-noun anchors.

When should I use Prompt Optimizer?

Prompt Optimizer fits situations like: tasks that involve Prompt engineering; tasks that involve Subagents; tasks that involve Citation management.

How do I install Prompt Optimizer in Claude Code?

Run `npx skills add Cranot/roam-code --skill prompt-optimizer -a claude-code`. Or copy the skill folder (.claude/skills/prompt-optimizer in Cranot/roam-code) into .claude/skills/prompt-optimizer in your project. Claude Code loads it when a task matches its description.

How do I install Prompt Optimizer in Codex?

Run `npx skills add Cranot/roam-code --skill prompt-optimizer -a codex`. Or copy the skill folder (.claude/skills/prompt-optimizer in Cranot/roam-code) into .agents/skills/prompt-optimizer in your project. Codex loads it when a task matches its description.

Can I use Prompt Optimizer in Cursor, Gemini CLI or GitHub Copilot?

Cursor, Gemini CLI, GitHub Copilot and OpenCode also load SKILL.md folders. With the skills CLI, run `npx skills add Cranot/roam-code --skill prompt-optimizer -a cursor` (or -a gemini-cli, github-copilot or opencode for the others). To copy it by hand, put the folder in .cursor/skills/prompt-optimizer, .gemini/skills/prompt-optimizer, .github/skills/prompt-optimizer and .opencode/skills/prompt-optimizer in your project.

What does Prompt Optimizer need to run?

SKILL.md names no scripts, command-line tools or credentials: Prompt Optimizer is instructions for the agent only.

Does Prompt Optimizer access the network?

SKILL.md contains no URLs. Any network use would come from the scripts or tools the agent runs. This is read from the text; nothing was executed.

Is Prompt Optimizer safe to install?

Our automated static check of SKILL.md found no risky patterns, such as piping downloads into a shell, reading credential files or hidden Unicode. It is not a guarantee. Review the folder before installing.

What licence does Prompt Optimizer use?

Prompt Optimizer is published under the Apache-2.0 licence (the repository's licence). It allows redistribution, so the full SKILL.md is shown on this page.

How many tokens does Prompt Optimizer use?

About 1.1k tokens (SKILL.md is roughly 4.2k characters). Agents keep only the skill's name and description in context until a task matches; then they load SKILL.md in full. Its references folder adds about 1.1k tokens, read only when the agent opens those files.

What are the alternatives to Prompt Optimizer?

Skills that share tags, products or a category with Prompt Optimizer: Agentforce Generate (SalesforceAIResearch/agentforce-adlc, 114 stars), Pi Agent (K-Dense-AI/scientific-agent-skills, 48k stars), Tapd Story Plan (TencentBlueKing/bk-bcs, 840 stars) and Tapd Story Tasks (TencentBlueKing/bk-bcs, 840 stars). The comparison table on this page puts their stars, adoption, token cost, safety result and licence side by side.

Who maintains Prompt Optimizer?

Cranot (a GitHub user) maintains it in Cranot/roam-code, which has 517 GitHub stars. The repository holds 9 skills in this directory. The repository was last updated on October 3, 2026.

Source: Cranot/roam-code on GitHub. Facts on this page come from the repository at the commit we read; the author's words are quoted as theirs.