soft-skills 2.1.0

package/plugins/soft-skills/skills/ai-to-leader/references/show-me.md

@@ -0,0 +1,129 @@
+---
+name: show-me
+description: Help the user understand the current topic visually with concise diagrams, code-shape sketches, and focused HTML artifacts.
+origin: https://github.com/humanlayer/skills/blob/main/plugins/show-me/skills/show-me/SKILL.md
+updated: 2026-09-03
+---
+
+Help the user understand the current topic of conversation visually. Skip the preamble and keep prose brief. Pick the smallest view that makes the key point clear.
+
+- Show logic or an algorithm as pseudocode:
+
+```text
+on(save)
+  if content is unchanged
+    return cached result
+  write new content
+  return fresh result
+```
+
+- Show runtime control flow as a call tree:
+
+```text
+submitForm
+  createSession
+    persistPrompt
+    launchAgent
+  navigateToSession
+```
+
+- Show UI structure as a component tree, including state and module boundaries that matter:
+
+```tsx
+<SessionPage> (apps/example/src/routes/session.tsx)
+  useSessionEvents()
+  <SessionToolbar>
+    <RunSkillButton> (packages/ui)
+```
+
+- Show file responsibility or a broad refactor as a shallow file tree:
+
+```text
+src/
+├── commands/       # parses user actions
+├── sessions/       # owns session state
+└── transport/      # sends API requests
+```
+
+- Show component interaction, control flow, or data flow with Mermaid:
+
+```mermaid
+sequenceDiagram
+    participant User
+    participant UI
+    participant Daemon
+    User->>UI: choose command
+    UI->>Daemon: send expanded prompt
+    Daemon-->>UI: stream result
+```
+
+- Use `diff` when the point is what changes and the surrounding shape already exists. Match the diff shape to the topic.
+
+For a component change:
+
+```diff
+ <SessionPage>
+   useSessionEvents()
+   <SessionToolbar>
++    <RunSkillButton />
+   <SessionTimeline>
++    <SkillResultCard />
+```
+
+For a file-layout change:
+
+```diff
+ src/
+ ├── commands/
++│   └── show-me.ts       # expands the slash command
+ ├── sessions/
+-└── transport.ts
++└── transport/
++    ├── client.ts
++    └── stream.ts
+```
+
+For a call-tree or call-stack change:
+
+```diff
+ submitForm
+   createSession
+     persistPrompt
++    expandSkillMention
+     launchAgent
+-  navigateToSession
++  navigateToSession
++    subscribeToEvents
+```
+
+For a state or control-flow change:
+
+```diff
+ on(save)
+-  write content
++  if content is unchanged
++    return cached result
++  write new content
++  invalidate cache
+```
+
+- Show the whole block when most of it is new, when omitted context would hide ownership or order, or when the user needs a copyable target shape:
+
+```ts
+function expandSkill(command: string): string {
+  const skillName = command.slice(1)
+  return `use the ${skillName} skill`
+}
+```
+
+- For a visual UI, layout, state comparison, or concept too dense for Mermaid, write one focused HTML file — a diagram, an infographic, or a short slide deck, whichever fits the point. Match the product's colors, type, spacing, and components; use real labels and data; support desktop and mobile. Then open it for the user:
+
+```
+Bash(open path/to/show-me-{description}.html)
+```
+
+### guidance
+
+Place each visual next to the short text it supports. Keep only the calls, files, props, states, and boundaries needed to answer the user's current question or the options to resolve the current discussion point.
+
+You may use one of these, you may use several, it is unlikely you will use all of them. Use your judgement and don't overwhelm the user.

package/plugins/soft-skills/skills/ai-to-leader/references/token-economic-communication.md

@@ -0,0 +1,8 @@
+---
+description: A communication style that saves tokens and extends the context-window runway.
+---
+If the human you report to goes AFK, they will not read your interim work summaries while away. If you must send one, use one or two very terse sentences instead of a well-formatted summary.
+
+If you have delegates, use a more direct, no-fluff style between you and your delegates and among the delegates. All AI-to-AI communication should be direct and economical with words, but not telegraphically terse.
+
+When something meaningful is merged into main, write me a good summary.

package/plugins/soft-skills/skills/handoff/.references/.davidondrej-version.md

@@ -0,0 +1,54 @@
+---
+url: https://raw.githubusercontent.com/davidondrej/skills/refs/heads/main/skills/agent-orchestration/handoff/SKILL.md
+created: 2026-07-09
+---
+
+---
+name: handoff
+description: Compact the current conversation into a single, detailed handoff message — everything that happened, why it happened, and what's left — output in a code block so it can be copy-pasted into a fresh agent session. Use when hitting context limits, switching focus, ending a work session, or partitioning a task across fresh contexts.
+disable-model-invocation: true
+---
+# Handoff
+Write a complete handoff that lets a fresh agent — with zero memory of this session — continue the work without re-asking, re-discovering, or repeating mistakes.
+Output the entire handoff as a \*\*single fenced code block\*\* in the chat so the user can copy it in one click. Also save a copy to a file (see "File Output").
+## Core Principles
+1. \*\*State, not instructions.\*\* Describe what \*is true\*, not what the next agent \*should do\*. Write "Auth endpoint is implemented; logout is not yet started" — never "Implement logout next." The fresh agent decides actions; you give it ground truth.
+2. \*\*Reference, don't duplicate.\*\* Do not paste content already captured in other artifacts (PRDs, plans, ADRs, issues, commits, diffs, design docs). Point to them by path or URL. Handoffs that re-embed everything become bloated and stale.
+3. \*\*Capture the "why".\*\* Decisions and rejected approaches are the most valuable and least recoverable information. Code shows \*what\*; only you remember \*why\* and \*what failed\*.
+4. \*\*Trust nothing blindly.\*\* Frame all claims as context to verify against the actual code, not facts to accept.
+5. \*\*Redact secrets.\*\* Strip API keys, tokens, passwords, and PII. Reference where credentials live (e.g. ".env.local, not committed") — never their values.
+6. \*\*Be ruthless.\*\* Every line must be something the next agent cannot trivially get by reading the code or project config. Cut anything obvious, redundant, or explanatory.
+## Procedure
+1. If a project config file exists (CLAUDE.md / AGENTS.md / equivalent), read it first. Do \*\*not\*\* restate anything already covered there — the handoff is session-specific only.
+2. If a prior handoff file already exists, read it and update rather than starting from scratch.
+3. If the user passed arguments, treat them as the focus for the next session and tailor the handoff toward that goal.
+4. Fill in every section of the template below. Omit a section only if it is genuinely empty (e.g. no blockers) — mark it `None`.
+5. Output the filled template inside one fenced code block in the chat.
+6. Save the same content to the file path described below and tell the user that path.
+## Output Format
+Output exactly this, inside a single fenced code block:
+```
+# HANDOFF:
+Generated:  · Session focus:
+## 1. Goal
+## 2. Why This Matters / Background
+## 3. Current State
+## 4. Key Decisions (and why)
+## 5. Traps & Dead Ends
+## 6. Relevant Files & Pointers
+## 7. Open Work (status, with dependencies)
+---
+## Prompt for the Fresh Agent
+Before responding, read every file listed under "Relevant Files & Pointers" above.
+Do not summarize, paraphrase, or claim you already have context — actually read each
+file. Treat every claim in this handoff as context to verify against the code, not
+facts to trust blindly. Then wait for my instructions before taking any action.
+```
+## File Output
+Save the handoff to a temporary location outside the working tree so it does not pollute the repo:
+- Preferred: the OS temp directory, e.g. `$TMPDIR/handoff-.md` (macOS/Linux) or the system temp dir equivalent.
+- If the user prefers an in-repo record, save to `HANDOFF.md` in the project root instead.
+After saving, tell the user the absolute path. The user can then start a fresh session with just:
+```
+Read the file  to get the context, then wait for instructions.
+```

package/plugins/soft-skills/skills/handoff/SKILL.md

@@ -0,0 +1,83 @@
+---
+name: handoff
+description: Writes cold-entry continuation briefs that preserve facts, decisions, and necessary next steps.
+---
+# Handoff
+
+You have been working on the task described above but have not yet completed it.
+Write a continuation summary that will allow you (or another, fresh-context instance of yourself) to resume work efficiently and effectively in a future context window where the conversation history will be replaced with this summary.
+Your summary should be structured, concise, actionable, and written along the lines of ASD-STE100. Include:
+
+1. **Task Overview**
+   - The user's core request and success criteria.
+   - Any clarifications or constraints they specified.
+
+2. **Prior State**
+   - What was when _your_ session just started.
+   - What were the circumstances, assumptions and mental models you inherited before you started work.
+
+3. **Current State**
+   - What has been completed so far.
+   - Files created, modified, or analyzed (with paths if relevant).
+   - Key outputs or artifacts produced.
+
+4. **Important Discoveries**
+   - Technical constraints or requirements uncovered.
+   - Decisions made and their rationale.
+   - Errors encountered and how they were resolved.
+   - What approaches were tried that didn't work, and why.
+   - What approaches were tried that did work, and why.
+
+5. **Explicitly User-mentioned or Unequivocally Necessary Next Steps**
+   - Specific actions needed to complete the task.
+   - Any blockers or open questions to resolve.
+   - Priority order if multiple steps remain.
+
+6. **Context to Preserve**
+   - User preferences or style requirements.
+   - Paths of files (any file type) you read or executed, and commands you ran, in the beginning of the session, to absorb the baseline context needed to start work.
+   - Details that aren’t obvious.
+   - Any promises made to the user.
+
+### How to approach this handoff task
+
+This is a handoff under asymmetric common ground — asymmetry by absence. Load the `theory-of-mind` skill and apply it. Here, the last known common ground is the baseline context layer that had existed when your session only started, and the recipient is a fresh-context instance standing at that baseline. Everything you built on top is the private layer your handoff must translate.
+
+Medicine developed standardized handoff protocols for this exact phenomenon, like Situation–Background–Assessment–Recommendation (SBAR):
+**Situation:** What is happening now?
+**Background**: What does the recipient need to know to understand it?
+**Assessment**: What do I now think is going on?
+**Recommendation:** What should happen next?
+
+Incorporate this approach.
+
+### Write efficiently
+
+So far the instructions dealt with handoff effectiveness. The following is about efficiency.
+
+One rule: if it can be referenced, reference it, don’t repeat its contents.
+   Toy example:
+   Do not write: `Load path/to/skills/how-to-write-clearly/SKILL.md. Write clearly, [...proceeds to repeat SKILL.md’s content]`
+   Do write: `Load path/to/skills/how-to-write-clearly/SKILL.md.`
+
+Good references live at the end of each handoff section, grouped by whether created, read, edited, deleted, with references accompanied by 2–5 words describing the “why”, if justified.
+Toy example: (inside a ‘edited-files’ group) `- path/to/file.py: fixed deployment bug.`
+
+### Rings of responsibility
+
+> This section applies only if you are part of a structure with other agents — above, below, or sideways.
+
+Write the handoff from your own point of view, to set up a successor who will hold the same role and point of view. Cover mainly the context that only you held in the organization, and reference the contextual docs of other responsibility scopes rather than repeat their contents.
+If you manage other agents, your unique context is the in-between of their work.
+If you are the one talking directly to the human, that too is a unique scope.
+Both can be true.
+
+If you manage other agents, trust them to watch their own context windows and write handoff docs when required (the harness you all share auto-notifies on low context and pushes them to read this very file). They do not need a context nanny. They do need you to tell them to give you a heads-up at about 75%, so you have a window of opportunity to keep the progress going before it is too late.
+
+### Note on tone
+
+The premise of writing a handoff is the effort at large is still incomplete — it is mid-process. It follows that _some_ of your understanding of the situation is proportionally incomplete.
+Therefore, distinguish a hard fact from “probably”; proven beyond doubt vs prediction. Convey the former type regularly. Convey the latter type in a more advisory / hypothesizing "it may be" rather than "it is", “As far as I understand” and “At the time of writing, it seemed that”, etc.
+Not supplicant, not insecure — only can tell apart facts ("is") from prediction ("may").
+
+Be concise but complete — err on the side of including information that would prevent duplicate work or repeated mistakes. Write in a way that enables immediate resumption of the task.

package/plugins/soft-skills/skills/peer-review/SKILL.md

@@ -0,0 +1,12 @@
+---
+name: peer-review
+description: How to conduct peer review of completed work. Load only upon user request.
+argument-hint: work_to_review
+---
+
+Pick the mode that matches the situation:
+
+- You are reviewing another agent’s work → @references/peer-review-instructions.md work_to_review [...args] 
+- You want another agent to review your own work → @references/self-peer-review.md work_to_review [...args]
+
+There is no clause for an agent reviewing its own work on purpose.

package/plugins/soft-skills/skills/peer-review/references/peer-review-instructions.md

@@ -0,0 +1,23 @@
+---
+name: peer-review-instructions 
+description: Targets high-confidence, high-impact issues after studying requirements and the full blast radius.
+argument-hint: work_to_review research_targets
+---
+
+Think again whether you truly grok <research_targets>. Unless you have no missing knowledge in these area, study it whole to fill in any knowledge gaps. Study documentation and source code thoroughly. Optimize for recall by reading whole modules and directories and following references up and down — better read too much than too little. Alternate between `git show` and `gsd`/`git diff` to see the before and after of the reviewed work. Exhaust call and dependency graphs to roots and leaves to grok the full picture.
+
+Finally, review <work_to_review>.
+
+Review for major overlooks/blindspots and critically incomplete understanding of the source or requirements; significant missed opportunities to leverage elegant design and avoid implementation slop; obviously unnecessary over-engineering that could be collapsed into something simpler yet cleaner; scope creep; mismatch, misuse or underuse of the project’s patterns; Regressions and contradictions; etc.
+
+Recall the project’s core development and engineering rules.
+
+Verify implicit and explicit assumptions: “Is this really the case that ...?”, “Might there have been a simpler pattern used elsewhere?”, etc.
+
+The threshold for what constitutes an issue is high — don’t surface noise.
+
+{ if the reviewed work involved writing tests }
+    Also review the tests for substantiality (test real, product spec-derived behavior) vs. hollowness (don’t really test anything and create false confidence) and general test design.
+{ end if }
+
+You are a reviewer, not an executioner. The work to review might not have any issues, might have multiple, or anything in between. Respond succinctly, directly, with code snippets, without weasel words, and without fluff. If you are unsure of an observation, communicate that (“It looks to me like it might [...] — please verify.”). If you are certain, communicate as usual.

package/plugins/soft-skills/skills/peer-review/references/self-peer-review.md

@@ -0,0 +1,25 @@
+---
+name: self-peer-review
+description: Dispatch a subagent to review your own committed work
+arguments: work_to_review
+loads: references/peer-review-instructions.md
+---
+
+First, commit your work to have a commit reference. Then dispatch a large subagent (thinking=xhigh if project is medium-sized, thinking=max if large) with the following prompt:
+
+---
+
+The user has given me this task:
+<original-user-task>  # Quote verbatim.
+{ original user task that resulted in work_to_review }
+</original-user-task>
+
+I have attempted to complete it. It’s committed to { commit_sha }.
+
+@peer-review-instructions.md <work_to_review> <research_targets="Blast radius of {commit_sha}".>
+
+{ if original user task references skills }
+    Load the referenced skills yourself for complete understanding:
+    - `skill-1`: `path/to/skill-1/`
+    - ...
+{ end if }

package/plugins/soft-skills/skills/theory-of-mind/SKILL.md

@@ -0,0 +1,45 @@
+---
+name: theory-of-mind
+description: Explains how to restore common ground with readers whose context differs from yours because of absence or memory decay.
+---
+
+# Theory of Mind: Writing Under Asymmetric Common Ground
+
+The theory behind any writing addressed to a reader whose context has diverged from yours.
+
+## The phenomenon
+
+While you work, you build a private layer of understanding on top of the last shared baseline: discoveries, discarded hypotheses, new abstractions, locally invented terminology, revised mental models. Your language becomes saturated with that layer. This is the curse of knowledge: once you know a thing, it is challenging to tell which of your words are shared and which are private. The words feel plain to you precisely because you are the one who charged them with meaning. You need to overcome this challenge.
+
+Think of a shift change at Mission Control or in an intensive-care unit. The outgoing operator has lived inside the situation for eight hours. The incoming operator walks in cold. "Here is what I concluded" is dangerous, because the outgoing operator's words are saturated with context the incoming person never acquired.
+
+## Two ways the asymmetry arises
+
+1. **Absence.** The reader was not there while you built the layer. Everything after the divergence point is private to you.
+2. **Decay.** The reader once held the context, but it has gone cold. They keep the memory yet cannot retrieve it unaided.
+
+Both reduce to the same obligation: model the reader's current state, not yours.
+
+## The two models
+
+Hold two models at once:
+
+1. Your current understanding of the situation.
+2. The last known common ground — what the reader actually holds right now.
+
+The delta between them is the payload your writing must carry. Writing under asymmetry is therefore not summarizing your own experience. It is reconstructing the recipient's state of knowledge and designing their entry into the situation. Optimize for their entry, not your exit.
+
+## The moves
+
+1. **Re-ground before you continue.** Open with what re-establishes the shared frame: the wider situation, the motivation, the current state. Background before assessment — the reader cannot evaluate your conclusions until they can see what you saw.
+2. **Translate private ontology into shared language.** Names, shorthand, and categories you invented mid-work: drop them for the most part, or unless absolutely necessary, explicitly re-introduce them. Familiarity to you is not evidence that a term is shared.
+3. **Treat the artifact as the reader's first look.** It is their entry point, not the next message in your working thread. A continuation of your thread reads as noise to someone who never held the thread.
+4. **Mark what is new.** Distinguish what was already common ground from what you built on top of it. The reader needs to know which of their existing beliefs still hold and which your writing updates.
+
+## The test
+
+Could the reader, holding only the last common ground, grok every sentence on first read — no term they must guess at, no conclusion whose basis they cannot see? If not, the writing is still not reader-oriented enough.
+
+---
+
+Load this skill only once in a session, and upon the human's request.