proposals
Skill0 starsChanged 4 months agoMITView on GitHub
Manages research proposals — new methods, implementation changes, approach shifts, validation strategies, or reference steering. Guides the agent through a structured discovery, confirmation, and formalization flow that produces a versioned proposal document under docs/proposals/. Also used to view and edit existing proposals.
2 other projects use a version of this.
Adopted by
Most recently taken up by
- carbon-language/carbon-langtheir own version, first seen Oct 8, 2026
- poorvith-mp/skills-sales-supporttheir own version, first seen Sep 6, 2026
Other versions2 projects use a version of this.
Word for word · 0
None found.
Edited · 0
None found.
Wrote their own version · 2
- carbon-language/carbon-lang★ 34ksame name
- poorvith-mp/skills-sales-support★ 0same name
How matches are found. Word for word: the exact same text. Edited: shares passages with this file (“99% same” means 99% of its five-word phrases also appear here; 10% or more counts). Their own version: similar meaning, or, weakest, the same name. We can’t tell which project had it first. Projects are counted among the 200 most-starred candidates, and mentions are links to the repository we found, up to 50 per site, so both counts are a floor.
In this repository14 other files it gives its agents.
- analysisSkill
- critiqueSkill
- domain-modelingSkill
- fetch-paperSkill
- fixesSkill
- grillingSkill
- grill-with-docsSkill
- handoffSkill
- implementSkill
- literature-reviewSkill
- project-knowledgeSkill
- read-aloudSkill
- referencesSkill
- update-project-knowledgeSkill
The file
Show its rules and text
We split this skill into the rules it gives an agent
18 rules. About 0 are common, 9 are distinctive, and 9 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈9
Distinctive · estimate
This author's own choices. Worth a look.
9
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Very specific: line 16
Every proposal is grounded in scientific evidence via /references before it is formalized.
- Distinctive: line 54
Do not propose alternatives that have no reference support.
- Distinctive: line 62
After presenting the alternatives:
- Distinctive: line 64
Ask the user: "Do you want to formalize a proposal for one of these alternatives?"
- Distinctive: line 65
If yes: ask which alternative (or let them describe their own) and proceed to Phase 2.
- Distinctive: line 66
If no: the skill ends — the interaction was exploratory only, no document is created.
- Distinctive: line 68
If the user references an existing proposal by name or ID, skip to Phase 4 (Edit mode).
- Distinctive: line 86
After collecting answers, summarize the proposal in structured form and ask: "Does this summary reflect your intent?
- Very specific: line 95
Write the proposal document to: docs/proposals/{proposal-id}.md
- Very specific: line 96
Use the template at .claude/skills/proposals/templates/proposal.md.
- Distinctive: line 102
Reframed as hypothesis: if neither of the above applies, rewrite the claim as an explicit hypothesis to be tested (e.g.
- Very specific: line 114
Read the existing proposal from docs/proposals/.
- Very specific: line 116
If the edit touches the Method or References sections, invoke /references to verify or expand the literature grounding.
- Very specific: line 118
Update the Status field if appropriate (e.g., draft → active, active → implemented).
- Distinctive: line 124
All proposals must follow this section order.
- Very specific: line 163
Follow the /references table format.
- Very specific: line 175
All proposals live in docs/proposals/
- Very specific: line 178
When creating a new proposal, check if a similar one already exists before writing (Glob docs/proposals/*.md and scan titles)
≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Purpose
This skill governs how new proposals to the existing research are handled. A proposal is any suggested change to:
- The algorithm or method (e.g., replacing RandomForest with a different Critic)
- The implementation (e.g., refactoring a module, changing a pipeline step)
- The experimental design or evaluation protocol
- The validation strategy or statistical method
- The theoretical framing or reference basis
Every proposal is grounded in scientific evidence via /references before it is formalized.
Always invoke /references before exploring any alternative — no alternative is credible without literature support, and the proposal document's References section must satisfy the /references citation policy.
When to invoke
- User asks "what if we used X instead of Y?"
- User questions the current approach and wants to explore an alternative
- User wants to propose a change to implementation, method, or evaluation
- User wants to view, update, or refer back to an existing proposal
- Invoke explicitly:
/proposalsor/proposals edit <proposal-id>
Flow
The skill runs in five sequential phases. Each phase has a checkpoint — do not proceed until the checkpoint condition is met.
Phase 0: Discovery → invoke /references → ground the topic in literature
Phase 1: Confirmation → present alternatives → confirm user intent
Phase 2: Elicitation → enter plan mode → collect information via questions
Phase 3: Formalization → write proposal document to docs/proposals/
Phase 4: Edit mode → (optional) read existing proposal → targeted editsPhase 0 — Discovery (Prerequisite)
Trigger: User raises a topic, question, or doubt about any aspect of the research.
- Ask the user: "Does this need a literature review first, or is existing grounding (
docs/references/, prior proposals) enough to work from?" Checkdocs/reviews/for an existing review on this topic before asking — if one already covers it, offer to reuse it instead of asking. If the user wants a review, invoke/literature-reviewon the topic and wait for it to complete before continuing; use its References table as the literature base for the steps below instead of searching from scratch. - Identify the domain of the question: method, implementation, evaluation, framing, or references.
- Invoke
/references— pass the topic as context (or the review's References table, if Step 0 produced one). Let it search for relevant literature before any synthesis begins. - Using the grounded references, enumerate the main alternatives available for this topic. Present them to the user as a short list with one-sentence justifications drawn from the literature.
- Do not propose alternatives that have no reference support. If no relevant literature exists, state that explicitly.
Checkpoint: At least one alternative is grounded in at least one peer-reviewed reference before proceeding.
Phase 1 — Confirmation
After presenting the alternatives:
- Ask the user: "Do you want to formalize a proposal for one of these alternatives?"
- If yes: ask which alternative (or let them describe their own) and proceed to Phase 2.
- If no: the skill ends — the interaction was exploratory only, no document is created.
If the user references an existing proposal by name or ID, skip to Phase 4 (Edit mode).
Checkpoint: User has explicitly confirmed they want to open a proposal before any document is created or plan mode is entered.
Phase 2 — Elicitation (Plan Mode)
Enter plan mode immediately after confirmation.
In plan mode, interact with the user to collect the information needed for all proposal sections. Ask targeted questions — do not ask for information you can infer from context. Suggested question sequence:
- Motivation: "What is the limitation or gap in the current approach that motivates this proposal?"
- Impact: "Which files, functions, or experimental stages would need to change?"
- Method details: "How would the alternative integrate into the existing pipeline? Are there known hyperparameters or tweaks to explore first?"
- Plan scope: "How would you describe the effort — is this a small tweak, a module replacement, or a larger architectural change?"
- References: "Are there specific papers you have in mind, or should we rely on what
/referencessurfaced?"
After collecting answers, summarize the proposal in structured form and ask: "Does this summary reflect your intent? Shall I write the proposal document?"
Checkpoint: User approves the summary before the document is written.
Phase 3 — Formalization
- Generate a unique proposal ID using the format:
YYYY-MM-DD-{topic-slug}(e.g.,2026-04-03-gp-surrogate-critic). The slug is 3–5 words in kebab-case describing the proposed change. - Write the proposal document to:
docs/proposals/{proposal-id}.md - Use the template at
.claude/skills/proposals/templates/proposal.md. - Fill all sections — do not leave placeholder text. Every section must contain substantive content derived from the elicitation in Phase 2 and the references from Phase 0.
- The References section must follow the
/referencestable format exactly. Before writing, audit every mechanistic or directional claim (e.g. "X improves Y", "increasing Z reduces W", "larger N leads to better Q"). Each such claim must satisfy exactly one of:
- Cited: backed by a specific, verifiable claim in a peer-reviewed paper included in the References section — cite it inline with author/year.
- Empirical: derived from a concrete result already observed in this project — state the metric and experiment it comes from.
- Reframed as hypothesis: if neither of the above applies, rewrite the claim as an explicit hypothesis to be tested (e.g. "we hypothesize that...", "the expected effect — to be verified — is..."). Never state a hypothesis as fact.
Claims that cannot be cited, grounded empirically, or honestly reframed as hypotheses must be removed entirely.
Announce the file path to the user after writing: Proposal written to docs/proposals/{proposal-id}.md.
Phase 4 — Edit Mode
Triggered when the user references an existing proposal by ID, filename, or topic.
- Read the existing proposal from
docs/proposals/. - Identify which section(s) the user wants to change.
- If the edit touches the Method or References sections, invoke
/referencesto verify or expand the literature grounding. - Apply edits using targeted replacements — do not rewrite the whole document.
- Update the
Statusfield if appropriate (e.g.,draft → active,active → implemented). No other bookkeeping is required — theStatusfield alone tracks where a proposal stands.
Proposal document structure
All proposals must follow this section order. No section may be omitted.
1. Motivation
Why is this change being proposed? What limitation, observed result, or research gap drives it? Be specific — cite concrete evidence (a metric, a result, a paper finding) rather than vague dissatisfaction.
2. Impact
Which parts of the code and research methodology must change if this proposal is implemented?
- Code impact: list files, classes, or functions affected and the nature of each change (replace, extend, remove, add).
- Methodology impact: describe how the research method, experimental design, or evaluation protocol is affected. Point to specific experiment conditions, training stages, or evaluation metrics that change.
3. Description
High-level description of what is being proposed. What does the proposed change do, and what is the expected outcome? This should be readable without deep technical knowledge — it is the executive summary of the proposal.
4. Method
The technical core of the proposal. This section must address three sub-questions:
Integration — How does the proposed alternative connect to the existing framework? Which existing interfaces/modules does it touch, extend, or replace?
How it works — Explain the alternative method clearly. Include the key algorithmic idea, any relevant equations, and the intuition behind it. Ground in the cited references.
Relevant tweaks and tests — What hyperparameters need exploration? What ablation experiments or validation tests should be run first to assess feasibility before full integration? Be specific: which experiment conditions, which environments, which metrics.
5. Plan
A brief, ordered list of implementation steps. Each step should be actionable and scoped. Include an effort estimate per step if meaningful.
Format:
1. [step description] — effort: low | medium | high
2. ...6. References
Follow the /references table format. Every claim in the proposal that is not common knowledge must be backed by a cited paper or book. Do not include references that are not cited in the body of the document.
Proposal template
See .claude/skills/proposals/templates/proposal.md.
Naming and indexing
- All proposals live in
docs/proposals/ - File name:
{YYYY-MM-DD}-{topic-slug}.md - Status field values:
draft,active,implemented,rejected - When creating a new proposal, check if a similar one already exists before writing (
Glob docs/proposals/*.mdand scan titles)
Synergy with other skills
| Skill | When to invoke |
/references | Phase 0 (always), Phase 4 edits to Method or References sections |
/project-knowledge | When the proposal touches core algorithm/architecture — load full project context before eliciting Method details |
References
| # | Title | Authors | Year | Venue | Relevance |
| 1 | Design Thinking: Understanding How Designers Think and Work | Cross, N. | 2011 | Book. Berg Publishers. ISBN: 978-1847886361 | Grounds the discovery-confirmation-formalization flow in established design methodology; the three-phase structure (problem framing, concept development, specification) maps directly to Phases 0–3 of this skill |
| 2 | Good Enough Practices in Scientific Computing | Wilson, Bryan, Cranston, Kitzes, Nederbragt, Teal | 2017 | PLOS Computational Biology 13(6): e1005510. DOI: 10.1371/journal.pcbi.1005510 | Recommends maintaining a versioned record of design decisions and alternatives considered — the proposal document serves exactly this function for research-code decisions |
| 3 | A Rational Design Process: How and Why to Fake It | Parnas, D.L.; Clements, P.C. | 1986 | IEEE Transactions on Software Engineering 12(2): 251–257. DOI: 10.1109/TSE.1986.6312940 | Argues that formalizing design decisions after the fact — even when discovery is exploratory — produces more maintainable and communicable artifacts; motivates the formalization step (Phase 3) even for proposals born of informal discussion |
| 4 | Best Practices for Scientific Computing | Wilson, Aruliah, Brown, Chue Hong, Davis, Guy et al. | 2014 | PLOS Biology 12(1): e1001745. DOI: 10.1371/journal.pbio.1001745 | Defines the "make the change easy, then make the easy change" principle; informs the Plan section's step-by-step format and effort classification |
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

