Doc Coauthoring
aws-samples/sample-strands-agent-with-agentcore
Guide users through a structured workflow for co-authoring documentation.
How to write comprehensive architectural proposals that drive alignment before code is written
Install Architectural Proposals
$ npx skills add FritzAndFriends/SharpSite --skill architectural-proposals -a claude-codeProject install by default; add -g for ~/.claude/skills/.
$ gh skill install FritzAndFriends/SharpSite architectural-proposals --agent claude-codeProject scope by default; add --scope user for a personal install. Needs GitHub CLI 2.90.0 or later (public preview).
$ git clone --depth 1 https://github.com/FritzAndFriends/SharpSite.git skills-src && mkdir -p .claude/skills && cp -r skills-src/.copilot/skills/architectural-proposals .claude/skills/architectural-proposals && rm -rf skills-srcUse ~/.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/
Install the "architectural-proposals" agent skill from https://github.com/FritzAndFriends/SharpSite/tree/main/.copilot/skills/architectural-proposals into .claude/skills/architectural-proposals/ in this project. Copy the whole folder (SKILL.md and every file beside it), keep the folder name "architectural-proposals", then confirm the skill loads.Claude Code copies the folder itself, the same result as the manual copy. Check what it changed before you commit it.
$skill-installer install https://github.com/FritzAndFriends/SharpSite/tree/main/.copilot/skills/architectural-proposalsType this inside Codex. $skill-installer <name> installs a curated skill from openai/skills. The installer writes to $CODEX_HOME/skills (default ~/.codex/skills). Restart Codex if the skill does not show up.
$ npx skills add FritzAndFriends/SharpSite --skill architectural-proposals -a codexProject install goes to .agents/skills/; add -g for ~/.codex/skills/.
$ gh skill install FritzAndFriends/SharpSite architectural-proposals --agent codexProject scope by default (.agents/skills/); add --scope user for a personal install.
$ git clone --depth 1 https://github.com/FritzAndFriends/SharpSite.git skills-src && mkdir -p .agents/skills && cp -r skills-src/.copilot/skills/architectural-proposals .agents/skills/architectural-proposals && rm -rf skills-srcUse ~/.agents/skills/ instead of .agents/skills for a personal install.
Codex skills documentation · loads skills from .agents/skills/
Install the "architectural-proposals" agent skill from https://github.com/FritzAndFriends/SharpSite/tree/main/.copilot/skills/architectural-proposals into .agents/skills/architectural-proposals/ in this project. Copy the whole folder (SKILL.md and every file beside it), keep the folder name "architectural-proposals", then confirm the skill loads.Codex copies the folder itself, the same result as the manual copy. Check what it changed before you commit it.
$ npx skills add FritzAndFriends/SharpSite --skill architectural-proposals -a cursorProject install goes to .agents/skills/; add -g for ~/.cursor/skills/.
$ gh skill install FritzAndFriends/SharpSite architectural-proposals --agent cursorProject scope by default (.agents/skills/); add --scope user for a personal install.
$ git clone --depth 1 https://github.com/FritzAndFriends/SharpSite.git skills-src && mkdir -p .cursor/skills && cp -r skills-src/.copilot/skills/architectural-proposals .cursor/skills/architectural-proposals && rm -rf skills-srcUse ~/.cursor/skills/ instead of .cursor/skills for a personal install.
Cursor skills documentation · loads skills from .cursor/skills/, .agents/skills/, .claude/skills/, .codex/skills/
Install the "architectural-proposals" agent skill from https://github.com/FritzAndFriends/SharpSite/tree/main/.copilot/skills/architectural-proposals into .cursor/skills/architectural-proposals/ in this project. Copy the whole folder (SKILL.md and every file beside it), keep the folder name "architectural-proposals", then confirm the skill loads.Cursor copies the folder itself, the same result as the manual copy. Check what it changed before you commit it.
$ gemini skills install https://github.com/FritzAndFriends/SharpSite.git --path .copilot/skills/architectural-proposals--scope user (default) or --scope workspace; --path is the subfolder of the repo that holds the skill; --consent skips the security confirmation prompt.
$ npx skills add FritzAndFriends/SharpSite --skill architectural-proposals -a gemini-cliProject install goes to .agents/skills/; add -g for ~/.gemini/skills/.
$ gh skill install FritzAndFriends/SharpSite architectural-proposals --agent gemini-cliProject scope by default (.agents/skills/); add --scope user for a personal install.
$ git clone --depth 1 https://github.com/FritzAndFriends/SharpSite.git skills-src && mkdir -p .gemini/skills && cp -r skills-src/.copilot/skills/architectural-proposals .gemini/skills/architectural-proposals && rm -rf skills-srcUse ~/.gemini/skills/ instead of .gemini/skills for a personal install, then run /skills reload.
Gemini CLI skills documentation · loads skills from .gemini/skills/, .agents/skills/
Install the "architectural-proposals" agent skill from https://github.com/FritzAndFriends/SharpSite/tree/main/.copilot/skills/architectural-proposals into .gemini/skills/architectural-proposals/ in this project. Copy the whole folder (SKILL.md and every file beside it), keep the folder name "architectural-proposals", then confirm the skill loads.Gemini CLI copies the folder itself, the same result as the manual copy. Check what it changed before you commit it.
$ gh skill install FritzAndFriends/SharpSite architectural-proposalsInstalls for Copilot at project scope by default; add --scope user for a personal install. Preview a skill first with gh skill preview. Needs GitHub CLI 2.90.0 or later (public preview).
$ npx skills add FritzAndFriends/SharpSite --skill architectural-proposals -a github-copilotProject install goes to .agents/skills/; add -g for ~/.copilot/skills/.
$ git clone --depth 1 https://github.com/FritzAndFriends/SharpSite.git skills-src && mkdir -p .github/skills && cp -r skills-src/.copilot/skills/architectural-proposals .github/skills/architectural-proposals && rm -rf skills-srcUse ~/.copilot/skills/ instead of .github/skills for a personal install. Commit .github/skills so cloud agent and code review can use it.
GitHub Copilot skills documentation · loads skills from .github/skills/, .claude/skills/, .agents/skills/
Install the "architectural-proposals" agent skill from https://github.com/FritzAndFriends/SharpSite/tree/main/.copilot/skills/architectural-proposals into .github/skills/architectural-proposals/ in this project. Copy the whole folder (SKILL.md and every file beside it), keep the folder name "architectural-proposals", then confirm the skill loads.GitHub Copilot copies the folder itself, the same result as the manual copy. Check what it changed before you commit it.
$ npx skills add FritzAndFriends/SharpSite --skill architectural-proposals -a opencodeOpenCode documents no install command of its own. Project install goes to .agents/skills/; add -g for ~/.config/opencode/skills/.
$ gh skill install FritzAndFriends/SharpSite architectural-proposals --agent opencodeProject scope by default (.agents/skills/); add --scope user for a personal install.
$ git clone --depth 1 https://github.com/FritzAndFriends/SharpSite.git skills-src && mkdir -p .opencode/skills && cp -r skills-src/.copilot/skills/architectural-proposals .opencode/skills/architectural-proposals && rm -rf skills-srcUse ~/.config/opencode/skills/ instead of .opencode/skills for a personal install.
OpenCode skills documentation · loads skills from .opencode/skills/, .claude/skills/, .agents/skills/
Install the "architectural-proposals" agent skill from https://github.com/FritzAndFriends/SharpSite/tree/main/.copilot/skills/architectural-proposals into .opencode/skills/architectural-proposals/ in this project. Copy the whole folder (SKILL.md and every file beside it), keep the folder name "architectural-proposals", then confirm the skill loads.OpenCode copies the folder itself, the same result as the manual copy. Check what it changed before you commit it.
Facts
- Skill name
architectural-proposals- GitHub stars
- 145
- Used in
- 2 other repos
- Token cost
- ~1.6k tokens
- SKILL.md length
- 567 words
- Files
- 1
- Skills in repo
- 18
- Repo updated
- First seen
- Licence
- MIT
At a glance
How to write comprehensive architectural proposals that drive alignment before code is written
- Works in 7 steps: Problem Statement — Why current state is… → Proposed Architecture — Solution with… → What Changes — Impact on existing work… → …
- Tasks that involve Proposals and quotes
- SKILL.md covers Context, Patterns, Examples and Anti-Patterns
- Instructions only: no scripts, shell commands, URLs or credentials in SKILL.md
What it does
Architectural Proposals is an agent skill from FritzAndFriends/SharpSite. How to write comprehensive architectural proposals that drive alignment before code is written
Its SKILL.md is about 1.6k tokens, which your agent loads only when the skill is triggered. It is a single SKILL.md file with no bundled scripts.
It sits in Sales & Support, covering Proposals and quotes. The repository describes itself as: A basic CMS built with .NET 9 and Blazor. The licence is MIT.
When your agent uses it
- Tasks that involve Proposals and quotes
Example prompts
- “/architectural-proposals”
Workflow steps
7 steps, taken from the first numbered list in SKILL.md.
- Problem Statement — Why current state is broken (specific, measurable evidence)
- Proposed Architecture — Solution with technical specifics (not hand-waving)
- What Changes — Impact on existing work (waves, milestones, modules)
- What Stays the Same — Preserve existing functionality (no regression)
- Key Decisions Needed — Explicit choices with recommendations
- Risks and Mitigations — Likelihood + impact + mitigation strategy
- Scope — What's in v1, what's deferred (timeline clarity)
What it can do on your machine
Read from SKILL.md and the folder at commit c35e5e0. 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
Architectural Proposals loads about 1.6k tokens when it runs. Until then it costs about 30 tokens; SKILL.md has 567 words of instructions outside code blocks.
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 FritzAndFriends/SharpSite at commit c35e5e0, republished under its MIT licence (© FritzAndFriends). 567 words, ~1,569 tokens.
Download SKILL.mdSave it as
.claude/skills/architectural-proposals/SKILL.md (or your agent's skills folder).- name
- architectural-proposals
- description
- How to write comprehensive architectural proposals that drive alignment before code is written
- domain
- architecture, product-direction
- confidence
- high
- source
- earned (2026-02-21 interactive shell proposal)
Context
Proposals create alignment before code is written. Cheaper to change a doc than refactor code. Use this pattern when:
- Architecture shifts invalidate existing assumptions
- Product direction changes require new foundation
- Multiple waves/milestones will be affected by a decision
- External dependencies (Copilot CLI, SDK APIs) change
Patterns
Proposal Structure (docs/proposals/)
Required sections:
- Problem Statement — Why current state is broken (specific, measurable evidence)
- Proposed Architecture — Solution with technical specifics (not hand-waving)
- What Changes — Impact on existing work (waves, milestones, modules)
- What Stays the Same — Preserve existing functionality (no regression)
- Key Decisions Needed — Explicit choices with recommendations
- Risks and Mitigations — Likelihood + impact + mitigation strategy
- Scope — What's in v1, what's deferred (timeline clarity)
Optional sections:
- Implementation Plan (high-level milestones)
- Success Criteria (measurable outcomes)
- Open Questions (unresolved items)
- Appendix (prior art, alternatives considered)
Tone Ceiling Enforcement
Always:
- Cite specific evidence (user reports, performance data, failure modes)
- Justify recommendations with technical rationale
- Acknowledge trade-offs (no perfect solutions)
- Be specific about APIs, libraries, file paths
Never:
- Hype ("revolutionary", "game-changing")
- Hand-waving ("we'll figure it out later")
- Unsubstantiated claims ("users will love this")
- Vague timelines ("soon", "eventually")
Wave Restructuring Pattern
When a proposal invalidates existing wave structure:
- Acknowledge the shift: "This becomes Wave 0 (Foundation)"
- Cascade impacts: Adjust downstream waves (Wave 1, Wave 2, Wave 3)
- Preserve non-blocking work: Identify what can proceed in parallel
- Update dependencies: Document new blocking relationships
Example (Interactive Shell):
- Wave 0 (NEW): Interactive Shell — blocks all other waves
- Wave 1 (ADJUSTED): npm Distribution — shell bundled in cli.js
- Wave 2 (DEFERRED): SquadUI — waits for shell foundation
- Wave 3 (ADJUSTED): Public Docs — now documents shell as primary interface
Decision Framing
Format: "Recommendation: X (recommended) or alternatives?"
Components:
- Recommendation (pick one, justify)
- Alternatives (what else was considered)
- Decision rationale (why recommended option wins)
- Needs sign-off from (which agents/roles must approve)
Example:
### 1. Terminal UI Library: `ink` (recommended) or alternatives?
**Recommendation:** `ink`
**Alternatives:** `blessed`, raw readline
**Decision rationale:** Component model enables testable UI. Battle-tested ecosystem.
**Needs sign-off from:** Brady (product direction), Fortier (runtime performance)Risk Documentation
Format per risk:
- Risk: Specific failure mode
- Likelihood: Low / Medium / High (not percentages)
- Impact: Low / Medium / High
- Mitigation: Concrete actions (measurable)
Example:
### Risk 2: SDK Streaming Reliability
**Risk:** SDK streaming events might drop messages or arrive out of order.
**Likelihood:** Low (SDK is production-grade).
**Impact:** High — broken streaming makes shell unusable.
**Mitigation:**
- Add integration test: Send 1000-message stream, verify all deltas arrive in order
- Implement fallback: If streaming fails, fall back to polling session state
- Log all SDK events to `.squad/orchestration-log/sdk-events.jsonl` for debuggingShow full SKILL.md (237 more words)Show less
Examples
File references from interactive shell proposal:
- Full proposal:
docs/proposals/squad-interactive-shell.md - User directive:
.squad/decisions/inbox/copilot-directive-2026-02-21T202535Z.md - Team decisions:
.squad/decisions.md - Current architecture:
docs/architecture/module-map.md,docs/prd-23-release-readiness.md
Key patterns demonstrated:
- Read user directive first (understand the "why")
- Survey current architecture (module map, existing waves)
- Research SDK APIs (exploration task to validate feasibility)
- Document problem with specific evidence (unreliable handoffs, zero visibility, UX mismatch)
- Propose solution with technical specifics (ink components, SDK session management, spawn.ts module)
- Restructure waves when foundation shifts (Wave 0 becomes blocker)
- Preserve backward compatibility (squad.agent.md still works, VS Code mode unchanged)
- Frame decisions explicitly (5 key decisions with recommendations)
- Document risks with mitigations (5 risks, each with concrete actions)
- Define scope (what's in v1 vs. deferred)
Anti-Patterns
Avoid:
- ❌ Proposals without problem statements (solution-first thinking)
- ❌ Vague architecture ("we'll use a shell") — be specific (ink components, session registry, spawn.ts)
- ❌ Ignoring existing work — always document impact on waves/milestones
- ❌ No risk analysis — every architecture has risks, document them
- ❌ Unbounded scope — draw the v1 line explicitly
- ❌ Missing decision ownership — always say "needs sign-off from X"
- ❌ No backward compatibility plan — users don't care about your replatform
- ❌ Hand-waving timelines ("a few weeks") — be specific (2-3 weeks, 1 engineer full-time)
Red flags in proposal reviews:
- "Users will love this" (citation needed)
- "We'll figure out X later" (scope creep incoming)
- "This is revolutionary" (tone ceiling violation)
- No section on "What Stays the Same" (regression risk)
- No risks documented (wishful thinking)
© FritzAndFriends, MIT. Rendered from Markdown: HTML in the file is shown as text, images as links, and headings moved down two levels. Raw file
Files
Just SKILL.md in .copilot/skills/architectural-proposals of FritzAndFriends/SharpSite.
Open the folder on GitHubat commit c35e5e0
Used in 2 other repositories
We found 3 copies of this SKILL.md (exact, near-identical or edited) in other folders, from 2 other GitHub owners. This page covers the copy in FritzAndFriends/SharpSite, which our catalogue first saw on October 7, 2026.
Compare with similar skills
Architectural Proposals 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.
| Skill | Stars | Used in | Tokens | Auto-check | Licence | Repo updated |
|---|---|---|---|---|---|---|
| Architectural Proposals this skillFritzAndFriends/SharpSite | 145 | 2 repos | ~1.6k | Automated safety check: Pass | MIT | |
| Doc Coauthoringaws-samples/sample-strands-agent-with-agentcore | 195 | 40 repos | ~3.2k | Automated safety check: Pass | MIT | |
| Audit Onboarding Proposalhoangnb24/repository-harness | 1.2k | — | ~4k | Automated safety check: Pass | MIT | |
| No Negative EchoLB623/no-negative-echo | 900 | — | ~965 | Automated safety check: Pass | MIT | |
| GEO Service Proposal Generatorzubair-trabzada/geo-seo-claude | 11k | — | ~3k | Automated safety check: Notes | MIT | |
| Counter Proposal Generatorzubair-trabzada/ai-legal-claude | 1.8k | — | ~2.4k | Automated safety check: Pass | None |
Similar skills
- Official
Audit Onboarding Proposal
hoangnb24/repository-harness
Use only when the user explicitly invokes $audit-onboarding-proposal.
No Negative Echo
LB623/no-negative-echo
Prevent 此地无银三百两式 residue: finalize artifacts without echoing rejected session-only alternatives into labels, metadata, commits, PRs, or handoffs.
GEO Service Proposal Generator
zubair-trabzada/geo-seo-claude
Builds a client-ready AI-search-optimization proposal from an existing GEO audit, with pricing tiers, an ROI estimate and a markdown document ready to send.
Counter Proposal Generator
zubair-trabzada/ai-legal-claude
Generates specific counter-proposals for every unfavorable clause, with replacement language, negotiation talking points, and a ready-to-send email template
Task Profile
techwolf-ai/ai-first-toolkit
Mine the user's Claude Code + Cowork session history into a structured task profile, what they do with AI, how often, how successfully where friction lives, then propose atomic skills that would…
More from FritzAndFriends/SharpSite
All 18 skills in this repoClient Compatibility
FritzAndFriends/SharpSite
Platform detection and adaptive spawning for CLI vs VS Code vs other surfaces
Distributed Mesh
FritzAndFriends/SharpSite
How to coordinate with squads on different machines using git as transport
Docs Standards
FritzAndFriends/SharpSite
Microsoft Style Guide + Squad-specific documentation patterns
Economy Mode
FritzAndFriends/SharpSite
Shifts Layer 3 model selection to cost-optimized alternatives when economy mode is active.
External Comms
FritzAndFriends/SharpSite
PAO workflow for scanning, drafting, and presenting community responses with human review gate
Gh Auth Isolation
FritzAndFriends/SharpSite
Safely manage multiple GitHub identities (EMU + personal) in agent workflows
Related
Categories
Questions about Architectural Proposals
What does Architectural Proposals do?
How to write comprehensive architectural proposals that drive alignment before code is written. Architectural Proposals is an agent skill from FritzAndFriends/SharpSite.
When should I use Architectural Proposals?
Architectural Proposals fits situations like: tasks that involve Proposals and quotes.
How do I install Architectural Proposals in Claude Code?
Run `npx skills add FritzAndFriends/SharpSite --skill architectural-proposals -a claude-code`. Or copy the skill folder (.copilot/skills/architectural-proposals in FritzAndFriends/SharpSite) into .claude/skills/architectural-proposals in your project. Claude Code loads it when a task matches its description.
How do I install Architectural Proposals in Codex?
Run `npx skills add FritzAndFriends/SharpSite --skill architectural-proposals -a codex`. Or copy the skill folder (.copilot/skills/architectural-proposals in FritzAndFriends/SharpSite) into .agents/skills/architectural-proposals in your project. Codex loads it when a task matches its description.
Can I use Architectural Proposals 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 FritzAndFriends/SharpSite --skill architectural-proposals -a cursor` (or -a gemini-cli, github-copilot or opencode for the others). To copy it by hand, put the folder in .cursor/skills/architectural-proposals, .gemini/skills/architectural-proposals, .github/skills/architectural-proposals and .opencode/skills/architectural-proposals in your project.
What does Architectural Proposals need to run?
SKILL.md names no scripts, command-line tools or credentials: Architectural Proposals is instructions for the agent only.
Does Architectural Proposals 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 Architectural Proposals 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 Architectural Proposals use?
Architectural Proposals is published under the MIT licence (the repository's licence). It allows redistribution, so the full SKILL.md is shown on this page.
How many tokens does Architectural Proposals use?
About 1.6k tokens (SKILL.md is roughly 6.3k characters). Agents keep only the skill's name and description in context until a task matches; then they load SKILL.md in full.
What are the alternatives to Architectural Proposals?
Skills that share tags, products or a category with Architectural Proposals: Doc Coauthoring (aws-samples/sample-strands-agent-with-agentcore, 195 stars), Audit Onboarding Proposal (hoangnb24/repository-harness, 1.2k stars), No Negative Echo (LB623/no-negative-echo, 900 stars) and GEO Service Proposal Generator (zubair-trabzada/geo-seo-claude, 11k stars). The comparison table on this page puts their stars, adoption, token cost, safety result and licence side by side.
Who maintains Architectural Proposals?
FritzAndFriends (a GitHub organization) maintains it in FritzAndFriends/SharpSite, which has 145 GitHub stars. The repository holds 18 skills in this directory. The repository was last updated on April 30, 2026.
Source: FritzAndFriends/SharpSite on GitHub. Facts on this page come from the repository at the commit we read; the author's words are quoted as theirs.