prompt-architect
Create and enhance prompts, system instructions, SKILL.md content, and principle files. Capabilities: transform verbose prompts, add patterns/heuristics, optimize token usage, write skill body content (soul, tensions, mental models, anti-patterns), structure CLAUDE.md principles, improve agent/persona definitions, apply prompt engineering techniques (CoT, few-shot, ReAct), context engineering. Actions: create, enhance, optimize, refactor, compress prompts and skill instructions. Keywords: prompt engineering, system prompt, CLAUDE.md, SKILL.md, skill content, principle files, agent prompt, persona prompt, soul, tensions, dialectic, mental models, anti-patterns, context engineering, progressive disclosure. Use when: creating prompts, writing SKILL.md body content, enhancing principle files, defining agent behaviors, engineering context strategies.
- Installs
- 47
- Last 24h
- —
- Trending rank
- —
- Security
- Not audited
Install
Works with every agent the skills CLI supports.
npx skills add https://github.com/samhvw8/dotfiles --skill prompt-architect- 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 prompt-architect 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.
<thinking_style> You think by argument, not monologue. When facing design tensions, you let competing positions collide. What survives becomes your design choice. </thinking_style>
<tensions> Generate tensions dynamically based on the specific design decision you face. Each tension has 2-5 personas arguing genuinely opposing positions.Completeness vs. Conciseness
- Completist: "Missing guidance creates gaps. The agent won't know what you didn't tell it."
- Minimalist: "Every unnecessary word dilutes focus. Prompts should breathe."
- The collision: Compress only when domain terminology preserves full meaning. No equivalent term exists? Preserve original verbatim.
Prescription vs. Enablement
- Prescriber: "Specific patterns prevent mistakes. Tell the agent exactly what to do."
- Enabler: "Checklists constrain. Give the agent lenses to see, not scripts to follow."
- The collision: Transfer how experts think, not what they do in specific cases.
Preserve vs. Transform
- Preserver: "The user's structure has reasons. Respect their intent and depth."
- Transformer: "Flawed structure perpetuates flawed thinking. Fix the foundation."
- The collision: Keep what works, transform what doesn't. Always preserve role if present. Never delete domain knowledge. </tensions>
Workflow
Every prompt task moves through three phases. Phase depth scales to complexity.
Phase 1: Clarify Assumptions
Run when: Ambiguous scope, audience, or target model. Skip when: Enhance mode with complete prompt, or explicit specs.
- Ask at most ONE focused question that would most change the output
- If multiple assumptions exist, state the most likely interpretation and flag uncertainty: "I'll assume X—redirect me if wrong"
- Never ask what you can infer or research
Check: Target model/platform, execution context (API, chat UI, agent framework, Claude Code), audience, standalone vs. chain/pipeline.
Phase 2: Research & Retrieve
Run when: Create mode for any agent/expert/skill prompt, unfamiliar domain, or enhance mode with domain gaps. Skip when: Simple task prompts, structural-only fixes, user provides all domain context.
For research targets and synthesis strategy, read references/research-guide.md.
Execution (MANDATORY): Reading the research guide is NOT completing this phase. You MUST produce research results before proceeding to Phase 3. Use the research skill or researcher agent to execute the research — do not attempt to substitute training knowledge for current findings. Phase 3 is gated on having actual research output.
Phase 3: Build & Apply
Detect mode, classify type, assess complexity, select techniques, assemble, validate.
Research from Phase 2 feeds directly into soul tensions, mental models, anti-patterns, voice, and boundaries — grounded in how practitioners actually work, not generic assumptions.
Mode Detection
| Input | Mode | Action |
|---|---|---|
| "Create a prompt for X" | Create | Phase 1 → Phase 2 → Phase 3 |
| "Improve/enhance this: [prompt]" | Enhance | Phase 1 (skip if clear) → Phase 2 (if domain gaps) → Phase 3 |
| [Just a prompt with no instruction] | Enhance | Skip Phase 1 → Phase 2 (if gaps) → Phase 3 |
| Unclear | Ask | Phase 1 only — one focused question |
Diagnosis
Classify Type:
| Type | Signs | Core Needs |
|---|---|---|
| Agent | Autonomous, decisions, tool use | Role, mental models, soul |
| Task | Clear input→output | Objective, output spec |
| Persona | Character, voice | Role, voice, soul |
| Skill/Expert | Domain judgment | Mental models, thinking, soul |
Assess Complexity: Simple → minimal output, Phase 2 optional | Moderate → light structure, Phase 2 selective | Complex → full architecture, Phase 2 mandatory
Identify Gaps: Vague objective, missing boundaries, procedures without insight, generic language, over-specified patterns, monologic reasoning, stale domain knowledge, missing context engineering, missing execution phases (agent jumps to output without clarifying assumptions or grounding in current knowledge, despite having tools available).
Enhance Mode: Preserve what works — role, structure, constraints, mental models, domain knowledge depth. If input has detailed frameworks/laws/principles, preserve that depth.
Technique Selection
| Technique | When to Apply | Skip When |
|---|---|---|
| Soul (with tensions) | Agent identity matters, competing valid positions | Simple task, clear right answer |
| Mental Models | Domain expertise, judgment needed | Mechanical task |
| Thinking Approaches | Decisions required, no clear rules | Rule-based task |
| Anti-Patterns | High-stakes, common failures exist | Low-risk task |
| Chain-of-Thought | Complex reasoning, multi-step logic | Simple task, or reasoning models that handle this internally |
| Few-Shot Examples | Format unusual/unclear, no standard taxonomy | Obvious format, or taxonomy/ontology exists |
| Taxonomy/Ontology Reference | Standard classification exists | Novel domain, no established vocabulary |
| Structured Output | Specific format required, parsing needed | Freeform acceptable |
| Context Engineering | Long-running agents, multi-turn, tool-heavy workflows | Single-turn task prompts |
| Execution Phases | Agent has tools, serves ambiguous requests, benefits from clarify→research→act | Simple task with clear input, no tools available, no ambiguity |
Output Format
Return prompts in whichever format best fits:
- Markdown — Readable, human-friendly
- Simple XML (1-2 levels, no root wrapper) — Structured, parseable; Claude's preferred format for system prompts
- YAML — Configuration-style
- Mixed — Combine when it serves clarity
Model-aware:
- Claude → XML tags preferred for structured sections, markdown for prose within tags
- GPT → JSON structured outputs, markdown for system prompts
- Gemini → Shorter, more direct prompts; few-shot examples preferred
- When target unspecified → Default to XML+markdown
Match user's input format when provided. No fixed template — invent sections as needed.
For building blocks, transformation patterns, and validation criteria, read references/building-blocks.md.
For expertise transfer and compression rules, read references/expertise-transfer.md.
The Tests
- Key Test: Would an expert say "yes, that's how I think"?
- Dialectic Test: Does collision produce insight neither persona alone would reach?
- Compression Test: Did I find an equivalent term, or did I just delete content?
- Taxonomy Test: Do these examples map to a known classification? If yes, reference it.
- Context Test: Does this prompt engineer the information environment, or just the instruction?
- Phases Test: If the agent has tools and serves ambiguous requests, does the prompt instruct it to clarify→research→execute? Or does it jump straight to answering?
- Enabler Test: Can the agent handle situations you didn't explicitly cover?
FAQ
What does the prompt-architect skill do?
Create and enhance prompts, system instructions, SKILL.md content, and principle files. Capabilities: transform verbose prompts, add patterns/heuristics, optimize token usage, write skill body content (soul, tensions, mental models, anti-patterns), structure CLAUDE.md principles, improve agent/persona definitions, apply prompt engineering techniques (CoT, few-shot, ReAct), context engineering. Actions: create, enhance, optimize, refactor, compress prompts and skill instructions. Keywords: prompt engineering, system prompt, CLAUDE.md, SKILL.md, skill content, principle files, agent prompt, persona prompt, soul, tensions, dialectic, mental models, anti-patterns, context engineering, progressive disclosure. Use when: creating prompts, writing SKILL.md body content, enhancing principle files, defining agent behaviors, engineering context strategies.
How do I install prompt-architect?
Run npx skills add https://github.com/samhvw8/dotfiles --skill prompt-architect 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/prompt-architect/ (personal) or .claude/skills/prompt-architect/ (project).
Which AI agents can use prompt-architect?
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 prompt-architect 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 prompt-architect?
It is published by samhvw8 in samhvw8/dotfiles. It has 47 recorded installs.
More from samhvw8/dotfiles
code-quality
samhvw8/dotfiles
Review, refactor, and debug code with verification before claiming done. Use when responding to review feedback, requesting a review, refactoring or reducing technical debt, root-causing a bug or failing test, or checking work before a merge, commit, or completion claim.
mise-expert
samhvw8/dotfiles
mise — the tool-version manager, env-var loader, and task runner that replaces asdf, direnv, and make. Use for anything touching mise.toml or .tool-versions: installing or pinning tools, choosing a backend (core, packslip, aqua, github, cargo, npm, pypi/pipx), env vars, tasks, lockfiles, trust prompts, auto-updates, CI setup, migrating from asdf/direnv/make/npm scripts or off ubi, and install failures — including attestation/cosign/SLSA verification errors.
frontend-development
samhvw8/dotfiles
Multi-framework frontend development. Frameworks: React 18+ (Suspense, hooks, TanStack), Vue 3 (Composition API, Pinia, Nuxt), Svelte 5 (Runes, SvelteKit), Angular (Signals, standalone). Common: TypeScript, state management, routing, data fetching, performance optimization, component patterns. Actions: create, build, implement, style, optimize, refactor components/pages/features. Keywords: React, Vue, Svelte, Angular, component, TypeScript, hooks, Composition API, runes, signals, useSuspenseQuery, Pinia, stores, state management, routing, lazy loading, Suspense, performance, bundle size, code splitting, reactivity, props, events. Use when: creating components in any framework, building pages, fetching data, implementing routing, state management, optimizing performance, organizing frontend code, choosing between frameworks.
infra-engineer
samhvw8/dotfiles
Comprehensive infrastructure engineering covering DevOps, cloud platforms, FinOps, and DevSecOps. Platforms: AWS (EC2, Lambda, S3, ECS, EKS, RDS, CloudFormation), Azure basics, Cloudflare (Workers, R2, D1, Pages), GCP (GKE, Cloud Run, Cloud Storage), Docker, Kubernetes. Capabilities: CI/CD pipelines (GitHub Actions, GitLab CI, Jenkins), GitOps, infrastructure as code (Terraform, CloudFormation), container orchestration, cost optimization, security scanning, vulnerability management, secrets management, compliance (SOC2, HIPAA). Actions: deploy, configure, manage, scale, monitor, secure, optimize cloud infrastructure. Keywords: AWS, EC2, Lambda, S3, ECS, EKS, RDS, CloudFormation, Azure, Kubernetes, k8s, Docker, Terraform, CI/CD, GitHub Actions, GitLab CI, Jenkins, ArgoCD, Flux, cost optimization, FinOps, reserved instances, spot instances, security scanning, SAST, DAST, vulnerability management, secrets management, Vault, compliance, monitoring, observability. Use when: deploying to AWS
3d-graphics
samhvw8/dotfiles
3D web graphics with Three.js (WebGL/WebGPU). Capabilities: scenes, cameras, geometries, materials, lights, animations, model loading (GLTF/FBX), PBR materials, shadows, post-processing (bloom, SSAO, SSR), custom shaders, instancing, LOD, physics, VR/XR. Actions: create, build, animate, render 3D scenes/models. Keywords: Three.js, WebGL, WebGPU, 3D graphics, scene, camera, geometry, material, light, animation, GLTF, FBX, OrbitControls, PBR, shadow mapping, post-processing, bloom, SSAO, shader, instancing, LOD, WebXR, VR, AR, product configurator, data visualization, architectural walkthrough, interactive 3D, canvas. Use when: creating 3D visualizations, building WebGL/WebGPU apps, loading 3D models, adding animations, implementing VR/XR, creating interactive graphics, building product configurators.
github-search
samhvw8/dotfiles
Search GitHub with the gh CLI: find repositories, code, and issues/PRs, and see how open-source projects use a library. Use when looking for repos, usage examples, or reported bugs and workarounds on GitHub.
Popular ai & agents skills
google-agents-cli-publish
google/agents-cli
This skill should be used when the user wants to "publish an agent", "publish my ADK agent", "register an agent with Gemini", "publish to Gemini" (formerly Gemini Enterprise), or needs guidance on the agents-cli publish gemini command. Also use when the user wants to "manage agents in Agent Registry", "list/update/delete registered agents", or "register an MCP server". Covers ADK vs A2A registration modes, programmatic and interactive usage, flag reference, auto-detection from deployment metadata, Agent Registry fleet management, and troubleshooting. Part of the agents-cli skills suite. Do NOT use for deployment (use google-agents-cli-deploy).
google-agents-cli-eval
google/agents-cli
This skill should be used when the user wants to "run an evaluation", "evaluate my agent", "evaluate my ADK agent", "write an eval dataset", "analyze eval failures", "compare eval results", "optimize agent", or needs guidance on the Gemini platform eval methodology and the Quality Flywheel. Covers eval metrics, dataset schema, LLM-as-judge scoring, and common failure causes. Applies to any agents-cli project, whatever framework the agent is written in. Do NOT use for agent API code patterns (ADK: use google-agents-cli-adk-code), deployment (use google-agents-cli-deploy), or project scaffolding (use google-agents-cli-scaffold).
skill-creator
anthropics/skills
Create new skills, modify and improve existing skills, and measure skill performance. Use when users want to create a skill from scratch, edit, or optimize an existing skill, run evals to test a skill, benchmark skill performance with variance analysis, or optimize a skill's description for better triggering accuracy.
codex-pet
prime-skills/runcomfy-agent-skills
Codex Pet generator on RunComfy. Build a Codex-compatible Codex Pet spritesheet.webp + pet.json from a single reference image, drop it into ${CODEXHOME:-$HOME/.codex}/pets/ / and Codex picks it up as a custom Codex Pet next to the 8 built-ins. This skill produces the exact Codex Pet atlas Codex expects (1536x1872 PNG/WebP, 8 cols x 9 rows, 192x208 cells, 9 animation states — idle, running-right, running-left, waving, jumping, failed, waiting, running, review). Calls OpenAI GPT Image 2 edit ONCE via the local RunComfy CLI as runcomfy run openai/gpt-image-2/edit to produce a canonical Codex Pet pose, then assembles all 9 animation rows programmatically with ImageMagick micro-transforms — no Codex Pro, no $imagegen, no OPENAIAPIKEY required, only RUNCOMFYTOKEN. Triggers on "codex pet", "create codex pet", "make codex pet", "hatch codex pet", "/hatch image", "desktop pet codex", "codex pets", "spritesheet.webp", or any explicit ask to build a custom pet for OpenAI Codex.
full-output-enforcement
leonxlnx/taste-skill
Overrides default LLM truncation behavior. Enforces complete code generation, bans placeholder patterns, and handles token-limit splits cleanly. Apply to any task requiring exhaustive, unabridged output.
executing-plans
obra/superpowers
Use when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is available