Skip to content

owenob1/prompt-improver / skills/prompt-improver

prompt-improver

Verified

Transform vague prompts into precise, verifiable structured XML prompts that coding agents execute reliably. Modes: execute (default — generate then run) and plan (generate XML for review first). Use when the user says improve prompt, make this work better, prompt engineer, structure a request, plan a complex change before coding, or when a rough request needs verification criteria before execution. Do not use when the input is already a well-structured XML prompt or detailed implementation spec — skip generation and execute directly.

FileKindSize
SKILL.mdskill md10.8 KB
assets/generation-agent-prompt.mdmarkdown8.7 KB
config/runtime-defaults.jsonconfig13.5 KB
config/settings.default.jsonconfig4.6 KB
config/settings.example.jsonconfig4.8 KB
examples/before-after.mdmarkdown23.5 KB
examples/fixtures/invalid-prompt.xmlconfig176 B
examples/fixtures/valid-prompt.xmlconfig1.7 KB
references/models-supported.mdmarkdown10.1 KB
references/prompt-chaining.mdmarkdown7.2 KB
references/prompting-principles.mdmarkdown21.6 KB
references/xml-template.mdmarkdown12.0 KB
scripts/assemble-generation-prompt.shexecutablescript4.2 KB
scripts/backends/agy.shexecutablescript815 B
scripts/backends/amp.shexecutablescript708 B
scripts/backends/claude.shexecutablescript1.2 KB
scripts/backends/cline.shexecutablescript1.0 KB
scripts/backends/codex.shexecutablescript2.0 KB
scripts/backends/copilot.shexecutablescript860 B
scripts/backends/cursor.shexecutablescript785 B
scripts/backends/droid.shexecutablescript693 B
scripts/backends/gemini.shexecutablescript1.3 KB
scripts/backends/grok.shexecutablescript1.4 KB
scripts/backends/kimi.shexecutablescript879 B
scripts/backends/kiro.shexecutablescript750 B
scripts/backends/opencode.shexecutablescript694 B
scripts/backends/qwen.shexecutablescript936 B
scripts/gather-context.shexecutablescript10.8 KB
scripts/generate-prompt.shexecutablescript20.0 KB
scripts/lib/backend-common.shscript4.8 KB
scripts/lib/settings.shexecutablescript36.0 KB
scripts/smoke-test.shexecutablescript40.1 KB
scripts/standalone-improve.shexecutablescript995 B
scripts/validate-prompt.shexecutablescript11.7 KB

references/prompt-chaining.md

View on GitHub
# Prompt Chaining

When a single prompt grows too large (>80 lines, 5+ tasks, or cross-cutting concerns), split it into sequential phases. Each phase is self-contained and builds on the output of the previous phase.

## When to chain

- **>5 tasks** — a single prompt with 5+ task blocks dilutes focus
- **Cross-cutting concerns** — changes that touch multiple layers (API + database + UI + tests)
- **Research-then-build** — when the implementation depends on research findings
- **Large migrations** — framework swaps, major refactors, platform moves
- **Uncertain scope** — when Phase 1 findings determine Phase 2 approach

## Phase structure

The canonical chain is: **Research -> Implement -> Polish**

| Phase | Purpose | Typical tasks |
|-------|---------|---------------|
| Research | Understand scope, audit current state, evaluate options | Audit files, read docs, evaluate libraries, create checklist |
| Implement | Build the core changes | Create/modify files, write logic, add tests |
| Polish | Verify, clean up, document | Run full test suite, fix edge cases, update docs |

Not every chain needs all three phases. Simple features may only need Implement + Polish. Complex migrations may need Research + multiple Implement phases + Polish.

## Phase prompt template

Each phase prompt is self-contained — it includes everything needed to execute without prior context:

```xml
<context>
  <project>{tech stack, framework, key libraries}</project>
  <scope>{what this phase covers}</scope>
  <phase>Phase {N} of {total}: {phase name}</phase>
  <prior-phase-output>
    {Summary of what previous phases produced — files created/modified, decisions made, findings}
    {Only include for Phase 2+. Be specific: list file paths, key decisions, test results.}
  </prior-phase-output>
</context>

<done>{observable finish line for this phase. One sentence.}</done>

<task id="1" name="{task-name}">
  <description>{what this task accomplishes}</description>
  <requirements>
    - {specific requirement}
  </requirements>
  <verification>
    - {how to check it worked}
  </verification>
</task>

<execution>
  <strategy>
    {sequential or parallel}
    Keep the checklist in TASKS.md. Tick each item. Add findings there.
    One subagent per independent unit. Check its evidence before accepting it.
  </strategy>
  <constraints>
    - {phase-specific constraints}
  </constraints>
  <stops>
    - If a step needs no input, keep going. Put status in the same message as the next action.
    - Stop only when blocked on the user, or before deleting data, force-pushing, or writing outside this repository.
    - Do not end the turn by asking whether to continue.
  </stops>
  <escape>
    If a requirement is contradictory or infeasible, name it once and continue
    with the rest of this phase. Do not invent a workaround.
  </escape>
  <next-phase>
    Phase {N+1} will cover: {brief description of what comes next}
  </next-phase>
</execution>

<check>
  - Re-read changed files — verify no placeholders or empty functions
  - Run {typecheck command}
  - Run {test command}
  - Review the diff. List only merge-blocking problems: file, line, why, how to show it fails.
  - Report status for each requirement
  - Report: Blocked on me / Changed / Found / Unconfirmed
</check>
```

## Passing context between phases

The `<prior-phase-output>` tag carries forward what matters:

```xml
<prior-phase-output>
  Phase 1 (Research) completed:
  - Audited 12 route files in src/api/
  - Identified 3 Express-specific middleware: cors, helmet, body-parser
  - Hono equivalents: hono/cors (built-in), @hono/helmet (npm), built-in body parsing
  - Decision: migrate routes alphabetically, leaf routes first
  - Created migration checklist at docs/migration-checklist.md
</prior-phase-output>
```

Be specific about:
- Files created or modified
- Decisions made and why
- Test results (what passes, what is currently broken)
- Anything the next phase needs to know

## Example: 3-phase migration (Express to Hono)

### Phase 1: Research and audit

```xml
<context>
  <project>Express.js, TypeScript, PostgreSQL</project>
  <scope>Full framework migration: Express to Hono</scope>
  <phase>Phase 1 of 3: Research and Audit</phase>
</context>

<research>
  Search before starting:
  - Hono routing API, middleware patterns, and Node.js adapter
  - Known Express-to-Hono migration pitfalls
  - Hono equivalent for each Express middleware in use
</research>

<task id="1" name="audit-express-usage">
  <description>Catalog all Express-specific APIs and middleware used across the codebase.</description>
  <requirements>
    - List every route file with HTTP methods and paths
    - List every middleware with its Express-specific signature
    - Map each Express API to its Hono equivalent
    - Identify third-party Express middleware and find Hono alternatives
    - Output: migration checklist document
  </requirements>
  <verification>
    - Every .ts file in src/api/ and src/middleware/ is accounted for
    - Every Express-specific import has a mapped Hono equivalent
    - Checklist document created at docs/migration-checklist.md
  </verification>
</task>

<execution>
  <escape>
    If any Express middleware has no Hono equivalent, flag it rather than
    building a custom replacement without approval.
  </escape>
</execution>

<check>
  - Re-read the migration checklist and verify completeness
  - Run typecheck to confirm no changes broke the build
</check>
```

### Phase 2: Core migration

```xml
<context>
  <project>Express.js to Hono, TypeScript, PostgreSQL</project>
  <scope>Server setup and route migration</scope>
  <phase>Phase 2 of 3: Core Migration</phase>
  <prior-phase-output>
    Phase 1 completed:
    - 12 route files, 4 middleware files identified
    - Migration checklist at docs/migration-checklist.md
    - Hono equivalents confirmed for all middleware
    - Decision: migrate in order — server setup, global middleware, routes (alphabetical)
  </prior-phase-output>
</context>

<task id="1" name="hono-server-setup">
  <description>Replace Express server entry point with Hono.</description>
  <requirements>
    - Install hono and @hono/node-server
    - Replace src/index.ts server setup
    - Migrate global middleware (cors, body parsing, error handler)
  </requirements>
  <verification>
    - Server starts without errors
    - Health check endpoint responds
  </verification>
</task>

<task id="2" name="migrate-routes" depends-on="1">
  <description>Migrate all route handlers from Express to Hono patterns.</description>
  <requirements>
    - Follow docs/migration-checklist.md order
    - Replace req/res patterns with Hono context (c.req, c.json)
    - Run tests after each file
  </requirements>
  <verification>
    - All existing API tests pass
    - No Express imports remain in migrated files
  </verification>
</task>

<check>
  - Re-read all migrated files
  - Run full test suite
  - Run typecheck
</check>
```

## Guidelines

- Each phase should be executable in one session — if too large, split further
- Be explicit about what carries forward — `<prior-phase-output>` is the handoff mechanism
- Present Phase 1 first — let the user review before generating subsequent phases
- Phases can be adjusted — Phase 1 findings may change the Phase 2 plan
- Generate Phase 2 only after Phase 1 is complete, using actual results
reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis.Stars: 472kUpdated Claude CodeCodexVerifiedInstall
diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness.Stars: 322kUpdated Claude CodeCodexVerifiedInstall
dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependenciesStars: 322kUpdated Claude CodeCodexVerifiedInstall
executing-plansobra/superpowersUse when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is availableStars: 322kUpdated Claude CodeCodexVerifiedInstall