build-proposal

Researches vague ideas and authors decision-complete proposal documents for planning handoff.

Updated Jun 8, 2026
One-click install
npx skills add https://github.com/shawn-sandy/agentics-kit --skill build-proposal-shawn-sandy
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: build-proposal
Source: https://github.com/shawn-sandy/agentics-kit/tree/main/kit/plugins/plan-agent/skills/build-proposal
Command: npx skills add https://github.com/shawn-sandy/agentics-kit --skill build-proposal-shawn-sandy

SYSTEM DOCUMENTATION & REQUIREMENTS

💡 This Skill includes references (resource) components.

What problem does it solve? Half-formed ideas like "should we adopt X" or "how would we build Y" often get answered from memory, turn into endless option surveys, or lose their decisions in chat history. This Skill turns a vague idea into a grounded, decision-complete proposal by researching the web and codebase, separating established facts from human decisions, and converging on a saved prompt artifact ready for the planning layer. ## Core Features & Use Cases - Tiered right-sizing: A triage gate classifies ideas as Tier 0 (answer directly), Tier 1 (lightweight single-round proposal), or Tier 2 (full multi-round loop), so small ideas never get bloated documents. - Parallel grounded research: Fans out web research (WebSearch/WebFetch or the optional deep-research skill) and codebase exploration agents concurrently, quantifying real surfaces instead of estimating. - Human decision cadence: Uses recommendation-first AskUserQuestion gates to confirm the objective, choose among candidate approaches, and resolve open decisions, recording each answer in the artifact. - Living artifact with planning handoff: Authors a date-free proposal-<slug>.md saved prompt via the plan-agent:prompt skill, then hands off to /plan-agent:implementation-plan with --from-prompt. - Use Case: A developer asks "should we align our markdown components with Google's DESIGN.md spec?" The skill fetches the real spec, maps the codebase's token layer, presents candidate approaches, locks decisions, and produces a proposal with workstreams, risks, and a sized roadmap. ## Quick Start Ask the agent to turn your idea into a proposal, for example: run /plan-agent:build-proposal with a description of the idea you want evaluated.

Frequently Asked Questions about build-proposal

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I turn a vague feature idea into a proposal?▼

Invoke /plan-agent:build-proposal with your idea, or simply float the idea in conversation and the skill activates. It restates the objective, confirms it with you, researches the web and codebase, and writes a decision-complete proposal document.

What is the difference between a proposal and an implementation plan?▼

The proposal answers should-we and what, grounding facts and locking human decisions. The implementation plan answers how, with concrete steps and tests. This skill stops at the proposal and hands off to /plan-agent:implementation-plan using the --from-prompt flag.

Does build-proposal require the deep-research skill?▼

No, deep-research is an optional delegate for the web-research phase. When it is unavailable or only a quick fact check is needed, the skill falls back to WebSearch and WebFetch directly, plus Explore agents for codebase research.

Where are proposal files saved?▼

Proposals are saved as proposal-<slug>.md in the prompts directory, resolved from the --dir flag, the promptsDirectory setting in Claude Code settings files, or docs/prompts/ by default. The filename carries no date so the living document keeps one stable path.

When should I not use the proposal workflow?▼

Skip it for single-fact questions or well-specified tasks like fixing a specific bug, which the triage classifies as Tier 0 and answers or routes directly. The loop is meant for ambiguous ideas with real decisions to make, not known work.