proposal-review
Facilitate methodical review of proposals (technical designs, product specs, feature requests). Use when asked to "review this proposal", "give feedback on this doc", "help me review this RFC", or when presented with a document that needs structured feedback. Handles markdown files, GitHub gists/issues/PRs, and other text formats. Chunks proposals intelligently, predicts reviewer reactions, and produces feedback adapted to the proposal's format.
- Installs
- 72
- Last 24h
- —
- Trending rank
- —
- Security
- Not audited
Install
Works with every agent the skills CLI supports.
npx skills add https://github.com/petekp/agent-skills --skill proposal-review- 01
Install
Run the command in your project. The CLI asks which agents to install for.
- 02
Describe the task
Ask your agent for something this skill covers. It loads proposal-review automatically when relevant.
- 03
Review the result
The agent follows the SKILL.md steps, scripts and references bundled with the skill.
SKILL.md
The instructions your agent reads when the skill is triggered.
Proposal Review
Methodically review proposals by chunking content, predicting feedback, and producing actionable output for the proposer.
Workflow
┌─────────────────────────────────────────────────────────────┐
│ 1. INTAKE: Read entire proposal, identify source format │
├─────────────────────────────────────────────────────────────┤
│ 2. CHUNK: Split into reviewable sections (smart hybrid) │
├─────────────────────────────────────────────────────────────┤
│ 3. REVIEW LOOP: For each chunk: │
│ • Present chunk content │
│ • Predict 3-4 likely reactions │
│ • Use AskUserQuestion for feedback │
│ • Record response │
├─────────────────────────────────────────────────────────────┤
│ 4. SYNTHESIZE: Compile feedback, infer overall sentiment │
├─────────────────────────────────────────────────────────────┤
│ 5. OUTPUT: Generate feedback document matching source │
└─────────────────────────────────────────────────────────────┘
Phase 1: Intake
Read the entire proposal. Identify:
- Source format: Local file, GitHub PR/issue/gist, Google Doc export, etc.
- Structure: Headers, sections, numbered lists, or flowing prose
- Length: Estimate chunk count (aim for 3-8 chunks for typical proposals)
Do not summarize or share initial impressions. Proceed directly to chunking.
Phase 2: Chunking Strategy
Use smart hybrid chunking:
| Proposal Structure | Chunking Approach |
|---|---|
| Clear headers/sections | One chunk per major section |
| Large section (>500 words) | Split at natural paragraph breaks |
| Small adjacent sections (<100 words each) | Merge into single chunk |
| Numbered lists of items | Group 3-5 related items per chunk |
| Flowing prose without structure | Split at topic transitions (~300-400 words) |
Chunk ordering: Present in document order unless there's a clear dependency (e.g., "Alternatives" before "Proposed Solution" if alternatives inform the solution review).
Phase 3: Review Loop
For each chunk:
3.1 Present the Chunk
Quote or summarize the chunk content. For longer chunks, quote key sentences and summarize the rest. Use a clear header like:
### Chunk 2 of 5: Technical Architecture
3.2 Predict Reactions
Generate 3-4 predicted reactions spanning these categories:
| Category | Example Predictions |
|---|---|
| Clarification | "This is unclear—what does X mean?", "How does this interact with Y?" |
| Concern | "This scope seems too large", "Have you considered Z risk?" |
| Approval | "This approach makes sense", "Good tradeoff analysis" |
| Suggestion | "Consider alternative A", "This needs more detail on B" |
Select predictions that feel most relevant to this specific chunk. Not every chunk needs all categories.
3.3 Collect Feedback
Use AskUserQuestion with:
- Predicted reactions as options (2-4 most likely)
- User can select one OR provide custom feedback via "Other"
- Keep option labels concise (under 10 words), use description for detail
Example:
question: "What's your reaction to this technical architecture section?"
header: "Architecture"
options:
- label: "Looks good"
description: "The proposed architecture is sound and well-reasoned"
- label: "Scope concern"
description: "This feels too ambitious for the timeline"
- label: "Need clarification"
description: "Some technical details are unclear or missing"
- label: "Consider alternative"
description: "There may be a simpler or better approach"
3.4 Record Response
Store each response with:
- Chunk identifier (number + title)
- Selected option or custom text
- Any quoted content the feedback references
Phase 4: Synthesis
After all chunks reviewed:
- Group feedback by theme: Consolidate similar concerns across chunks
- Infer overall sentiment: Based on feedback distribution:
- Mostly approvals → Positive with minor suggestions
- Mixed → Conditional support, needs revisions
- Mostly concerns → Significant issues to address
- Identify patterns: Note if same concern appears multiple times
Then ask:
question: "Would you like me to include suggested next steps for the proposer?"
header: "Next Steps"
options:
- label: "Yes, include action items"
description: "Generate concrete next steps based on feedback"
- label: "No, just the feedback"
description: "Keep output to observations and reactions only"
Phase 5: Output Generation
Adapt output format to source:
| Source | Output Format |
|---|---|
| GitHub PR | PR review comment with quoted lines and threaded feedback |
| GitHub Issue | Comment with sections matching issue structure |
| Markdown file | Companion *-feedback.md with inline references |
| Google Doc | Structured comment list with section references |
| Generic/unknown | Structured markdown with clear sections |
Output Structure
## Feedback Summary
**Overall**: [Inferred sentiment - 1 sentence]
## Section-by-Section Feedback
### [Section Name]
[Feedback with quotes where relevant]
### [Section Name]
...
## Key Themes
- [Theme 1]: [Consolidated feedback]
- [Theme 2]: ...
## Next Steps (if requested)
- [ ] [Action item 1]
- [ ] [Action item 2]
Tone Guidelines
- Direct but constructive
- Quote specific text when critiquing
- Frame concerns as questions when possible ("Have you considered..." vs "This won't work")
- Acknowledge what works, not just what doesn't
Edge Cases
Very short proposals (<300 words): Skip chunking, review as single unit with 4-5 predicted reactions.
Very long proposals (>3000 words): Cap at 8-10 chunks. Merge aggressively or offer to focus on specific sections.
Unclear structure: Ask user which sections matter most before chunking.
Multiple proposals: Review one at a time. Ask user for order preference if not obvious.
FAQ
What does the proposal-review skill do?
Facilitate methodical review of proposals (technical designs, product specs, feature requests). Use when asked to "review this proposal", "give feedback on this doc", "help me review this RFC", or when presented with a document that needs structured feedback. Handles markdown files, GitHub gists/issues/PRs, and other text formats. Chunks proposals intelligently, predicts reviewer reactions, and produces feedback adapted to the proposal's format.
How do I install proposal-review?
Run npx skills add https://github.com/petekp/agent-skills --skill proposal-review in your project. The skills CLI detects the agents you use and copies the skill into the right folder. For Claude Code you can also place the skill folder at ~/.claude/skills/proposal-review/ (personal) or .claude/skills/proposal-review/ (project).
Which AI agents can use proposal-review?
Any agent that supports the open Agent Skills format (a folder with a SKILL.md file), including Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, Windsurf, Cline, OpenCode and more.
Is proposal-review safe to install?
No partner security audit is available yet. Skills can run commands and scripts, so read the SKILL.md and any bundled files before installing.
Who maintains proposal-review?
It is published by petekp in petekp/agent-skills. It has 72 recorded installs.
More from petekp/agent-skills
typography
petekp/agent-skills
Apply professional typography principles to create readable, hierarchical, and aesthetically refined interfaces. Use when setting type scales, choosing fonts, adjusting spacing, designing text-heavy layouts, implementing dark mode typography, or when asked about readability, font pairing, line height, measure, typographic hierarchy, variable fonts, font loading, or OpenType features.
macos-app-design
petekp/agent-skills
Open the skill to read its SKILL.md instructions.
optimize-agent-docs
petekp/agent-skills
Build a retrieval-optimized knowledge layer over agent documentation in dotfiles (.claude, .codex, .cursor, .aider). Use when asked to "optimize docs", "improve agent knowledge", "make docs more efficient", or when documentation has accumulated and retrieval feels inefficient. Generates a manifest mapping task-contexts to knowledge chunks, optimizes information density, and creates compiled artifacts for efficient agent consumption.
codebase-study-guide
petekp/agent-skills
Generate a pedagogically-grounded study guide for learning an unfamiliar codebase. Use when the user wants to onboard onto a codebase, understand a project's architecture, create learning materials for a team, or asks things like "help me learn this codebase", "create an onboarding guide", "I'm new to this project", "how does this system work", "study guide for this repo", or "explain this codebase to me". Produces a structured document that builds understanding from purpose to systems to patterns, using evidence-based learning techniques (elaborative interrogation, concept mapping, threshold concepts, worked examples, progressive disclosure).
unix-macos-engineer
petekp/agent-skills
Expert Unix and macOS systems engineer for shell scripting, system administration, command-line tools, launchd, Homebrew, networking, and low-level system tasks. Use when the user asks about Unix commands, shell scripts, macOS system configuration, process management, or troubleshooting system issues.
explainer-visuals
petekp/agent-skills
Create high-quality animated explainer visuals for essays and blog posts. Use when the user wants to visualize concepts, processes, data, or ideas with interactive web animations. Triggers on requests like "create a visual for", "animate this concept", "make an explainer", "visualize this idea", "diagram this process", "show this data", or when essay content would benefit from visual explanation. Handles abstract concepts (mental models, frameworks), technical processes (algorithms, systems), and data visualization (trends, comparisons). Outputs self-contained HTML/CSS/JS that embeds directly in web content.
Popular code quality & workflow skills
grill-me
mattpocock/skills
A relentless interview to sharpen a plan or design.
improve-codebase-architecture
mattpocock/skills
Scan a codebase for deepening opportunities, present them as a visual HTML report, then grill through whichever one you pick.
handoff
mattpocock/skills
Compact the current conversation into a handoff document for another agent to pick up.
domain-modeling
mattpocock/skills
Build and sharpen a project's domain model. Use when discussing codebase terminology, writing or editing a GLOSSARY.md, or recording or editing an ADR.
codebase-design
mattpocock/skills
Shared vocabulary for designing deep modules. Use when the user wants to design or improve a module's interface, find deepening opportunities, decide where a seam goes, make code more testable or AI-navigable, or when another skill needs the deep-module vocabulary.
diagnosing-bugs
mattpocock/skills
Diagnosis loop for hard bugs and performance regressions. Use when the user says "diagnose"/"debug this", or reports something broken/throwing/failing/slow.