diff --git a/.agent/project-context.md b/.agent/project-context.md index 0dd6405..9b29119 100644 --- a/.agent/project-context.md +++ b/.agent/project-context.md @@ -1,115 +1,32 @@ # Project Context Pack -Generated: 2026-07-16 -Root: /home/sjb/Projects/personal/ws-sjb-skills/wt-master -Working directory: . -Status: fresh - ## Purpose -A collection of agent skills (slash commands and behaviors) loaded into Steve Beaulac's AI coding agents. Each skill is a SKILL.md file that teaches the agent how to handle a specific task — from codebase design and TDD to Obsidian PKM workflows and tmux agent launching. - -## Project type - -- **Agent skill repository** — markdown-defined agent instructions -- Languages: Markdown (100%), one Bash script (detect-agent), one shell script (tmux-open) -- Package managers: none -- Build/test tools: none -- Agent guidance: `AGENTS.md` at root, `docs/invocation.md` for invocation conventions, `docs/agents/` for issue tracker / triage labels / ADR wiki / domain docs +Repository of agent skills: each skill is a folder with a `SKILL.md` plus optional references, scripts, or assets. ## Structure -``` -. -├── AGENTS.md # Top-level agent instructions for this repo -├── README.md # Project overview, lists user-invoked and model-invoked skills -├── .gitignore # Excludes docs/adr/ -├── .agent/ -│ └── project-context.md # This file -├── docs/ -│ ├── invocation.md # Model-invoked vs user-invoked definitions -│ ├── agents/ -│ │ ├── adr-wiki.md # ADR wiki setup docs -│ │ ├── domain.md # Domain docs layout -│ │ ├── issue-tracker.md # Gitea issue tracker docs -│ │ └── triage-labels.md # Five-label triage vocabulary -│ └── adr/ # ADR wiki clone (gitignored) -└── common/ - ├── README.md # Lists all common skills by invocation type - ├── engineering/ # Model-invoked: lsp-code-analysis, pkm-curation; User-invoked: commit-staged, implement-issue, project-context-pack, setup-skills - ├── productivity/ # (currently only README.md) - ├── pkm/ # User-invoked: conversation-summary, crit, research-vault, youtube-video-capture; Model-invoked: pkm-curation - ├── personal/ # (currently only README.md) - ├── misc/ # User-invoked: tmux-launch-agent - ├── in-progress/ # User-invoked: agent-handoff, knowledge-gardener - └── deprecated/ # Deprecated forge-* and dsp-* skills -``` +- `skills/` — skills grouped by category; each bucket has a README index. +- `skills/setup-skills/` — one-time repo configuration skill and its supporting guides. +- `README.md` — complete index of skills by invocation type and category. +- `AGENTS.md` — repository conventions and pointers to agent documentation. +- `docs/invocation.md` — user-invoked vs model-invoked behavior. +- `docs/agents/` — issue tracker, triage labels, ADR wiki, and domain-document conventions. +- `docs/engineering/` — reusable engineering process references. +- `docs/adr/` — ADR wiki clone; gitignored. +- `.agent/project-context.md` — this context pack. -## Important files +## Skill categories -- `AGENTS.md` — Agent entry point that describes structure, categories, and references docs -- `README.md` — Index of all skills divided into user-invoked and model-invoked -- `docs/invocation.md` — Defines the invocation model (disable-model-invocation frontmatter key, human vs model reachability, dependency rules) -- `docs/agents/` — Agent documentation for issue tracker, triage labels, ADR wiki, domain docs -- `common/engineering/project-context-pack/SKILL.md` — The skill that generated this file -- `common/misc/tmux-launch-agent/SKILL.md` — Fork agent CLI into new tmux window (user-invoked) -- `common/misc/tmux-launch-agent/tmux-open` — Reusable script that opens a command in a new tmux window/session +`engineering`, `in-progress`, `misc`, `personal`, `pkm`, `pstack`, `productivity`, `setup-skills`, `skill-authoring`, and `thinking-and-docs`. -## Commands +## Conventions -- Build: none -- Test: none -- Lint/typecheck: none -- Run/dev: skills are invoked by AI agents — no server or dev command +- Skills are user-invoked when frontmatter sets `disable-model-invocation: true`; otherwise they are model-invoked. +- Keep root and bucket README indexes synchronized with `SKILL.md` frontmatter and file paths. +- Read `docs/invocation.md` for invocation rules; read the relevant `docs/agents/` guide for tracker, triage, ADR, or domain-doc work. +- Source files in this repository are authoritative; global installed copies are separate. -## Entry points +## Validation -- `AGENTS.md` — loaded by the AI agent as project instructions (referred to in pi's agent config) -- Each `SKILL.md` under `common/` — referenced by agents via slash commands or auto-invocation - -## Search and symbol notes - -- All skills are `SKILL.md` files — search with `fd SKILL.md` -- Bucket READMEs: `fd README.md common/` -- Skills are classified as **user-invoked** (`disable-model-invocation: true` in frontmatter) or **model-invoked** (default, no frontmatter flag) -- Dependencies between skills use prose invocation ("Run the `/grilling` skill"), not file cross-references -- Shared reference docs live inside the owning skill's directory; other skills reach that material by invoking the skill - -## Files inspected - -- `AGENTS.md` — root agent instructions — fresh -- `README.md` — project overview and skill index — fresh -- `docs/invocation.md` — invocation model definitions — fresh -- `.gitignore` — excludes docs/adr/ — fresh -- `common/README.md` — common bucket index — fresh -- `common/misc/README.md` — misc bucket index — fresh -- `.agent/project-context.md` — this file (refreshed from stale 2026-06-25 version) - -## Exclusions - -- `.git/` — VCS data -- `docs/adr/` — gitignored ADR wiki clone -- `node_modules/`, `dist/`, `build/`, `target/`, `.venv/`, `__pycache__/`, `vendor/`, `coverage/` — not present, but excluded by policy -- `/home/sjb/.agents/skills/` — global install, NOT the source of truth for this repo -- Binary files, large artifacts, credentials, secrets, personal data - -## Navigation rules for future agents - -- Start with `fd SKILL.md` to find all skills, then narrow by `fd SKILL.md common//` -- To understand a skill's purpose, read its `SKILL.md` and the bucket `README.md` that indexes it -- For invocation rules (user-invoked vs model-invoked), read `docs/invocation.md` -- For agent-level docs (issue tracker, triage, ADR, domain), check `docs/agents/` -- Do not browse directories file-by-file; use `fd` and `rg` first -- Track every inspected file in this cache -- Re-read a file only when it changed, the cache is stale, or exact details are needed - -## Edit boundaries - -When cwd is inside this repo, all file edits MUST be scoped to paths under the repo root (`/home/sjb/Projects/personal/ws-sjb-skills/wt-master`). Do NOT touch files under `/home/sjb/.agents/skills/` or `/home/sjb/.pi/` — those are the installed/runtime copies, not the source of truth. The global install is synced separately; this repo is where source edits happen. - -## Refresh notes - -- This is a markdown-only repo with no build artifacts; refreshes are rarely needed unless skills are added or removed -- To refresh, re-run `tree -a -I '.git' -L 4` and re-read any changed bucket READMEs or SKILL.md files -- The `docs/adr/` directory is gitignored — if ADR data is needed, check the Gitea wiki directly -- If a skill is moved between buckets, update all README.md files that reference it (root, common, source bucket, destination bucket) +There is no build or test suite. For index changes, verify every `SKILL.md` appears once in the root index and its category index, links resolve, and invocation grouping matches frontmatter. diff --git a/AGENTS.md b/AGENTS.md index 75467c1..b041b7f 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -1,28 +1,19 @@ # Steve Beaulac Skills -A collection of agent skills (slash commands and behaviors) loaded into my agent. +A collection of agent skills (slash commands and behaviors) loaded into AI coding agents. Skills live under `skills/`, grouped by purpose; each bucket README and the root README index its `SKILL.md` files by invocation type. -# Structure - -Skills are organized into buckets based on where they can be used and their category. - -- Use `/common/` for skills that work in all CLI agents. -- Use `/common/misc/` for skills that work in all CLI agents and are in the misc category. -- Use an agent-specific bucket only when a skill is intended for a specific agent. - -Skill are organized into categories based on their function. For example, `/common/misc/` is a bucket for miscellaneous skills that work in all CLI agents. - -If we have a skill that is only relevant to a specific agent, we can put it in an agent-specific bucket. For example, if we have a skill that is only relevant to the `opencode` agent, we can put it in `/opencode/misc`. - -## list of categories +## Skill buckets - `engineering/` — daily code work -- `productivity/` — daily non-code workflow tools -- `misc/` — kept around but rarely used -- `personal/` — tied to my own setup, not promoted -- `pkm/` — personal knowledge management - `in-progress/` — drafts not yet ready to ship -- `deprecated/` — no longer used +- `misc/` — kept around but rarely used +- `personal/` — tied to the user's own setup, not promoted +- `pkm/` — personal knowledge management +- `pstack/` — personal agent workflow skills +- `productivity/` — general workflow tools +- `setup-skills/` — one-time repository setup skill and its references +- `skill-authoring/` — create and maintain agent skills +- `thinking-and-docs/` — decisions and documentation workflows Each bucket folder has a `README.md` that lists every skill in the bucket with a one-line description, with the skill name linked to its `SKILL.md`. Bucket `README.md`s and the top-level `README.md` group entries into **User-invoked** and **Model-invoked**. @@ -48,7 +39,7 @@ Gitea wiki at `git@gitea.sagacity.ca:steve/Skills.wiki.git`, cloned into `docs/a ## Project Context Pack -Agent memory file that describes the repo's context, codebase, and navigation rules. See `.agents/project-context.md`. +Agent memory file that describes the repo's context, codebase, and navigation rules. See `.agent/project-context.md`. ### Agent CLI diff --git a/README.md b/README.md index 913e3da..e6d9e27 100644 --- a/README.md +++ b/README.md @@ -4,116 +4,134 @@ Agent skills (slash commands and behaviors) loaded into AI coding agents. Skills are grouped by invocation type. [User-invoked](docs/invocation.md) skills run only when a person invokes them; model-invoked skills can also be selected automatically. -# Credits +## Credits + Many of these skills were created or originated by the following people and organizations: -- [mattpocock](http://mattpocock.com) +- [Matt Pocock](http://mattpocock.com) - [poteto](https://github.com/poteto?tab=repositories) ## User-invoked +### Setup + +- [setup-skills](skills/setup-skills/SKILL.md) — Configure this repo for the engineering skills, issue tracker, triage label vocabulary, and domain doc layout. + ### Engineering +- [thermo-nuclear-code-quality-review](skills/engineering/code-quality-review/SKILL.md) — Run an extremely strict maintainability review for abstraction quality, giant files, and spaghetti-condition growth. Use for a thermo-nuclear code quality review, thermonuclear review, deep code quality audit, or especially harsh maintainability review. - [commit-staged](skills/engineering/commit-staged/SKILL.md) — Commit staged files with a conventional commit message. -- [grill-with-docs](skills/engineering/grill-with-docs/SKILL.md) — Interview the user to sharpen a plan or design while creating ADRs and glossary docs. -- [implement](skills/engineering/implement/SKILL.md) — Implement a piece of work from a spec or set of tickets. -- [implement-isolation](skills/engineering/implement-isolation/SKILL.md) — Implement a piece of work from a spec or set of tickets in isolation. -- [implement-isolation-tmux](skills/engineering/implement-isolation-tmux/SKILL.md) — Dispatch an isolated worktree agent to implement work from a PRD or issues. -- [improve-codebase-architecture](skills/engineering/improve-codebase-architecture/SKILL.md) — Find and work through opportunities to deepen a codebase's architecture. +- [grill-with-docs](skills/engineering/grill-with-docs/SKILL.md) — A relentless interview to sharpen a plan or design, which also creates docs (ADR's and glossary) as we go. +- [implement](skills/engineering/implement/SKILL.md) — Implement a piece of work based on a spec or set of tickets. +- [implement-isolation](skills/engineering/implement-isolation/SKILL.md) — Implement a piece of work based on a spec or set of tickets in isolation. +- [implement-isolation-tmux](skills/engineering/implement-isolation-tmux/SKILL.md) — Dispatch a child agent in an isolated git worktree to implement a piece of work based on a PRD or set of issues. +- [implement-spec](skills/engineering/implement-spec/SKILL.md) — Implement the result of /to-spec and /to-tickets in code. +- [implementation-orchestrator](skills/engineering/implementation-orchestrator/SKILL.md) — Implements ready-for-agent tracker tickets through isolated worktrees, pull requests, review, conflict resolution, and merge. Use after wayfinder and planning have produced tickets, with or without a ticket ID/URL; no ticket ID/URL means process available tickets. Does not create planning tickets. +- [improve-codebase-architecture](skills/engineering/improve-codebase-architecture/SKILL.md) — Scan a codebase for deepening opportunities, present them as a visual HTML report, then grill through whichever one you pick. - [orchestrate-herdr](skills/engineering/orchestrate-herdr/SKILL.md) — Drive a plan from context or @file through a published spec, linked tickets, and one-at-a-time isolated implementation to a merged PR using Herdr and Pi agents. -- [project-context-pack](skills/engineering/project-context-pack/SKILL.md) — Build a bounded project context pack for later agent work. -- [recipe-diagrams](skills/engineering/recipe-diagrams/SKILL.md) — Convert recipes into high-resolution process-flow diagrams. -- [setup-skills](skills/setup-skills/SKILL.md) — Configure engineering skills, issue tracking, triage labels, and domain docs. -- [to-spec](skills/engineering/to-spec/SKILL.md) — Turn the current conversation into a spec and publish it to the issue tracker. -- [to-tickets](skills/engineering/to-tickets/SKILL.md) — Break a plan or spec into tracer-bullet tickets with dependencies. -- [triage](skills/engineering/triage/SKILL.md) — Triage issues and external PRs through the project workflow. -- [wayfinder](skills/engineering/wayfinder/SKILL.md) — Plan large work as decision tickets and resolve them step by step. +- [project-context-pack](skills/engineering/project-context-pack/SKILL.md) — Use when the user wants a bounded repo context pack, project map, codebase index, or cached memory file so later work uses fd/rg/tree-sitter/LSP instead of repeated browsing. +- [recipe-diagrams](skills/engineering/recipe-diagrams/SKILL.md) — Recipe diagrams: convert any recipe into a high-resolution Cooking for Engineers-style PNG process-flow table with aligned ingredient streams, preparation branches, joins, temperatures, timings, and finish steps. Use when the user asks for a recipe diagram. +- [security-audit](skills/engineering/security-audit/SKILL.md) — Comprehensive security and correctness audit of a branch's changes. Use for deep review requests, or branch/PR diff audits focused on bugs, breaking changes, security issues, devex regressions, and feature-gate leaks. +- [triage](skills/engineering/triage/SKILL.md) — Move issues and external PRs through a state machine of triage roles, categorise, verify, grill if needed, and write agent-ready briefs. +- [wayfinder](skills/engineering/wayfinder/SKILL.md) — Plan a huge chunk of work (more than one agent session can hold) as a shared map of decision tickets on your issue tracker, and resolve them one at a time until the way to the destination is clear. -### In-progress +### In Progress -- [agent-handoff](skills/in-progress/agent-handoff/SKILL.md) — Hand the current conversation to a fresh background agent. -- [knowledge-gardener](skills/in-progress/knowledge-gardener/SKILL.md) — Run vault-aware search, synthesis, note creation, and linking workflows. +- [agent-handoff](skills/in-progress/agent-handoff/SKILL.md) — Hand the current conversation off to a fresh background agent that picks up the work immediately. +- [knowledge-gardener](skills/in-progress/knowledge-gardener/SKILL.md) — Run vault-aware semantic search, synthesis, note creation, linking, and Zettelkasten workflows for this Obsidian vault. -### Miscellaneous +### Misc -- [bro](skills/misc/bro/SKILL.md) — Restate the last message in plain human language. -- [show-me](skills/misc/show-me/SKILL.md) — Help explain topics visually with concise diagrams and artifacts. -- [tmux-launch-agent](skills/misc/tmux-launch-agent/SKILL.md) — Fork a new agent CLI session into a new tmux window. -- [visual-verification](skills/misc/visual-verification/SKILL.md) — Verify running desktop UI changes with screenshots and recordings. +- [bro](skills/misc/bro/SKILL.md) — Restate the last message in plain human language, with no jargon. +- [show-me](skills/misc/show-me/SKILL.md) — Help the user understand the current topic visually with concise diagrams, code-shape sketches, and focused HTML artifacts. +- [tmux-launch-agent](skills/misc/tmux-launch-agent/SKILL.md) — Fork a new agent CLI session into a new tmux window, detected from the current agent. +- [visual-verification](skills/misc/visual-verification/SKILL.md) — Verify running desktop UI changes with screenshots and recordings. Use when changing shell styling, layout, panels, menus, notifications, animations, transitions, or capture flows; inspect the artifacts before reporting completion. ### Personal -- [arch-maintenance](skills/personal/arch-maintenance/SKILL.md) — Keep an Arch/CachyOS system updated and healthy with status, check, and update workflows. -- [arch-troubleshooting](skills/personal/arch-troubleshooting/SKILL.md) — Diagnose and repair Arch/CachyOS system problems. +- [arch-maintenance](skills/personal/arch-maintenance/SKILL.md) — Keep an Arch or CachyOS system updated and healthy with status, check, and update workflows. +- [arch-troubleshooting](skills/personal/arch-troubleshooting/SKILL.md) — Diagnose and repair Arch or CachyOS system problems. -### PKM +### Pkm -- [conversation-summary](skills/pkm/conversation-summary/SKILL.md) — Save the current conversation as a report note in an Obsidian vault. -- [crit](skills/pkm/crit/SKILL.md) — Run the CRIT framework through context, role, interview, and task. -- [research-vault](skills/pkm/research-vault/SKILL.md) — Research a topic through a guided conversation and save a linked vault packet. -- [youtube-video-capture](skills/pkm/youtube-video-capture/SKILL.md) — Capture a YouTube video's subtitles and summary in an Obsidian vault. +- [conversation-summary](skills/pkm/conversation-summary/SKILL.md) — Save the current conversation as a comprehensive report note in your Obsidian vault, following OKF v0.1 conventions. +- [crit](skills/pkm/crit/SKILL.md) — Run the CRIT framework — give the AI Context, assign it a Role, let it Interview you one question at a time, then issue the Task. +- [research-vault](skills/pkm/research-vault/SKILL.md) — Research a topic through a one-question-at-a-time learning conversation, answer directly, share resources when useful, and save a linked OKF-conformant research packet in the Obsidian vault. +- [youtube-video-capture](skills/pkm/youtube-video-capture/SKILL.md) — Fetch subtitles from a YouTube video, summarize the content, and save both the summary and raw subtitles to the Video bundle in the Obsidian vault. Use when the user wants to capture a YouTube video, mentions "summarize this video", "capture this talk", or pastes a YouTube URL wanting it saved to vault. ### Productivity -- [grill-me](skills/productivity/grill-me/SKILL.md) — Interview the user to sharpen a plan or design. -- [handoff](skills/productivity/handoff/SKILL.md) — Compact the current conversation into a handoff document. -- [teach](skills/productivity/teach/SKILL.md) — Teach the user a new skill or concept within the workspace. -- [to-questionnaire](skills/productivity/to-questionnaire/SKILL.md) — Turn an unresolved decision into a questionnaire. -- [wait-what](skills/productivity/wait-what/SKILL.md) — Re-pitch the last message in clearer terms. +- [grill-me](skills/productivity/grill-me/SKILL.md) — A relentless interview to sharpen a plan or design. +- [handoff](skills/productivity/handoff/SKILL.md) — Compact the current conversation into a handoff document for another agent to pick up. +- [to-questionnaire](skills/productivity/to-questionnaire/SKILL.md) — Turn a decision you can't fully answer into a questionnaire for someone else to fill in. +- [wait-what](skills/productivity/wait-what/SKILL.md) — Stop. That last message did not land: re-pitch it. -### Skill authoring +### Pstack -No user-invoked skills. +- [bugfix-regression-test](skills/pstack/bugfix-regression-test/SKILL.md) — Fix bugs test-first with a focused regression test when practical. +- [interrogate](skills/pstack/interrogate/SKILL.md) — Use for "interrogate", "adversarial review", "multi-model review", "challenge this", "stress test this code", "find blind spots", or "tear this apart". Uses available subagents for independent, evidence-backed review. -### Thinking and docs +### Thinking And Docs -- [before-building](skills/thinking-and-docs/before-building/SKILL.md) — Surface consequential choices when the user proposes a build. -- [decisions](skills/thinking-and-docs/decisions/SKILL.md) — List choices made during the current work that remain uncertain. -- [level-up](skills/thinking-and-docs/level-up/SKILL.md) — Assess technical and product knowledge and grow a learning plan. -- [read-all-adrs](skills/thinking-and-docs/read-all-adrs/SKILL.md) — Read every ADR in the project's `docs/adr/` folder. -- [remind](skills/thinking-and-docs/remind/SKILL.md) — Rewrite the last response more simply and briefly. -- [short](skills/thinking-and-docs/short/SKILL.md) — Compress the current answer while keeping its substance. -- [teach](skills/thinking-and-docs/teach/SKILL.md) — Teach the user a new skill or concept within the workspace. +- [before-building](skills/thinking-and-docs/before-building/SKILL.md) — Fire the moment the user proposes a build. Instantly surface the 1-3 consequential choices hidden in his idea. Can also be invoked with /before-building. +- [decisions](skills/thinking-and-docs/decisions/SKILL.md) — Ask the agent to list all choices it made during the current work that it is not confident of. Manual-only; invoke with /decisions. +- [level-up](skills/thinking-and-docs/level-up/SKILL.md) — Gauge the user''s technical + product knowledge through 7 adaptive questions, log verbatim answers with honest ratings, and grow a learning plan from the gaps found. Use when the user says "level up", "level-up session", "quiz me", "gauge my knowledge", or wants a new assessment round. Differentiator: this finds and maps gaps; the `teach` skill delivers lessons on them. +- [read-all-adrs](skills/thinking-and-docs/read-all-adrs/SKILL.md) — Read every ADR markdown file in the project's docs/adr/ folder so you have full context on past decisions. Use only when the user explicitly calls it. +- [remind](skills/thinking-and-docs/remind/SKILL.md) — Rewrite the last response simpler and shorter in plain English, prefixed with a 3-5 sentence TLDR of the conversation so far. Manual-only, invoked as /remind. +- [short](skills/thinking-and-docs/short/SKILL.md) — Manually-invoked skill that forces the agent to compress its current answer — strip filler, simplify wording, and cut length while keeping the substance. Use when the user says "short", "shorter", "simpler", "too long", "tl;dr", or wants a more concise version of the previous response. +- [teach](skills/thinking-and-docs/teach/SKILL.md) — Teach the user a new skill or concept, within this workspace. ## Model-invoked ### Engineering -- [code-review](skills/engineering/code-review/SKILL.md) — Review changes against repository standards and the originating specification. -- [codebase-design](skills/engineering/codebase-design/SKILL.md) — Design and improve deep module interfaces and seams. -- [dual-review](skills/engineering/dual-review/SKILL.md) — Run parallel correctness/security and maintainability reviews of a branch diff, then synthesize findings. -- [diagnosing-bugs](skills/engineering/diagnosing-bugs/SKILL.md) — Diagnose hard bugs and performance regressions. -- [domain-modeling](skills/engineering/domain-modeling/SKILL.md) — Build and sharpen a project's domain model. -- [lsp-code-analysis](skills/engineering/lsp-code-analysis/SKILL.md) — Navigate code and analyze it semantically with LSP. -- [prototype](skills/engineering/prototype/SKILL.md) — Build a throwaway prototype to answer a design question. -- [research](skills/engineering/research/SKILL.md) — Investigate a question using high-trust sources and capture the findings. -- [resolving-merge-conflicts](skills/engineering/resolving-merge-conflicts/SKILL.md) — Resolve an in-progress Git merge or rebase conflict. -- [tdd](skills/engineering/tdd/SKILL.md) — Use test-driven development for features, bugs, and integration tests. -- [wizard](skills/engineering/wizard/SKILL.md) — Generate an interactive wizard for steps only a human can perform. -- [worktrees](skills/engineering/worktrees/SKILL.md) — Manage Git worktrees in a canonical repository root. -- [write-discoverable-code](skills/engineering/write-discoverable-code/SKILL.md) — Write code agents and humans can find through plain-text search. +- [code-review](skills/engineering/code-review/SKILL.md) — Review the changes since a fixed point (commit, branch, tag, or merge-base) along two axes: Standards (does the code follow this repo's documented coding standards?) and Spec (does the code match what the originating issue/spec asked for?). Runs both reviews in parallel sub-agents and reports them side by side. Use when the user wants to review a branch, a PR, work-in-progress changes, or asks to "review since X". +- [codebase-design](skills/engineering/codebase-design/SKILL.md) — Shared vocabulary for designing deep modules. Use when the user wants to design or improve a module's interface, find deepening opportunities, decide where a seam goes, make code more testable or AI-navigable, or when another skill needs the deep-module vocabulary. +- [diagnosing-bugs](skills/engineering/diagnosing-bugs/SKILL.md) — Diagnosis loop for hard bugs and performance regressions. Use when the user says "diagnose"/"debug this", or reports something broken/throwing/failing/slow. +- [domain-modeling](skills/engineering/domain-modeling/SKILL.md) — Build and sharpen a project's domain model. Use when discussing codebase terminology, writing or editing a CONTEXT.md, or recording or editing an ADR. +- [dual-review](skills/engineering/dual-review/SKILL.md) — Run two independent, read-only reviews of a branch diff in parallel — correctness/security and maintainability — then synthesize prioritized findings. Use for a second review axis alongside code-review, a combined deep plus code-quality audit, or when the user asks for dual review. Runs both axes as parallel sub-agents so they do not pollute each other's context. +- [forge-cli](skills/engineering/forge-cli/SKILL.md) — Provides copy-paste, non-interactive tea, gh, and glab commands for issue and pull or merge request work. Use whenever a task needs tracker inspection, assignment, labels, comments, reviews, CI, or merge operations. +- [lsp-code-analysis](skills/engineering/lsp-code-analysis/SKILL.md) — Semantic code analysis via LSP. Navigate code (definitions, references, implementations), search symbols, preview refactorings, and get file outlines. Use for exploring unfamiliar codebases or performing safe refactoring. +- [pr](skills/engineering/pr/SKILL.md) — Use when writing a PR body. +- [prototype](skills/engineering/prototype/SKILL.md) — Build a throwaway prototype to answer a design question. Use when the user wants to sanity-check whether a state model or logic feels right, or explore what a UI should look like. +- [research](skills/engineering/research/SKILL.md) — Investigate a question against high-trust primary sources and capture the findings as a Markdown file in the repo. Use when the user wants a topic researched, docs or API facts gathered, or reading legwork delegated to a background agent. +- [resolving-merge-conflicts](skills/engineering/resolving-merge-conflicts/SKILL.md) — Use when you need to resolve an in-progress git merge/rebase conflict. +- [tdd](skills/engineering/tdd/SKILL.md) — Test-driven development. Use when the user wants to build features or fix bugs test-first, mentions "red-green-refactor", or wants integration tests. +- [to-spec](skills/engineering/to-spec/SKILL.md) — Turn the current conversation into a spec and publish it to the project issue tracker: no interview, just synthesis of what you've already discussed. Use when the user wants a spec from the current conversation or an orchestration workflow needs to publish one from context. +- [to-tickets](skills/engineering/to-tickets/SKILL.md) — Break a plan, spec, or the current conversation into tracer-bullet tickets with blocking edges, published to the configured tracker. Use when the user wants tickets from a plan or spec, or an orchestration workflow needs agent-grabbable tickets. +- [wizard](skills/engineering/wizard/SKILL.md) — Generate an interactive bash wizard that walks a human through steps only they can perform. Use when provisioning infrastructure, setting up credentials or CI secrets, walking an unfamiliar third-party dashboard, or running a one-off migration or cutover. Don't invoke this for steps the agent can perform itself. +- [worktrees](skills/engineering/worktrees/SKILL.md) — Manage Git worktrees in a canonical `.bare` repository root. Use when creating, reusing, listing, removing, or repairing worktrees, or when setting up a repository to keep all branch checkouts under one root. +- [write-discoverable-code](skills/engineering/write-discoverable-code/SKILL.md) — | -### Miscellaneous +### Misc -- [migrate-to-shoehorn](skills/misc/migrate-to-shoehorn/SKILL.md) — Migrate test assertions from `as` to `@total-typescript/shoehorn`. -- [scaffold-exercises](skills/misc/scaffold-exercises/SKILL.md) — Create linted exercise directories with problems, solutions, and explainers. -- [setup-pre-commit](skills/misc/setup-pre-commit/SKILL.md) — Set up Husky, lint-staged, type checking, and tests. +- [migrate-to-shoehorn](skills/misc/migrate-to-shoehorn/SKILL.md) — Migrate test files from `as` type assertions to @total-typescript/shoehorn. Use when user mentions shoehorn, wants to replace `as` in tests, or needs partial test data. +- [scaffold-exercises](skills/misc/scaffold-exercises/SKILL.md) — Create exercise directory structures with sections, problems, solutions, and explainers that pass linting. Use when user wants to scaffold exercises, create exercise stubs, or set up a new course section. +- [setup-pre-commit](skills/misc/setup-pre-commit/SKILL.md) — Set up Husky pre-commit hooks with lint-staged (Prettier), type checking, and tests in the current repo. Use when user wants to add pre-commit hooks, set up Husky, configure lint-staged, or add commit-time formatting/typechecking/testing. -### PKM +### Pkm -- [pkm-curation](skills/pkm/pkm-curation/SKILL.md) — Curate an Obsidian vault with classification, links, and atomic notes. +- [pkm-curation](skills/pkm/pkm-curation/SKILL.md) — Curate an Obsidian vault — classify notes, normalize frontmatter, add links, extract atomic notes. Use when curating, batch-processing, reviewing, or doing a serendipity pick. ### Productivity -- [grilling](skills/productivity/grilling/SKILL.md) — Grill the user relentlessly about a plan or design. -- [writing-for-agents](skills/productivity/writing-for-agents/SKILL.md) — Write effective documents for agents. +- [grilling](skills/productivity/grilling/SKILL.md) — Grill the user relentlessly about a plan, decision, or idea. Use when the user wants to stress-test their thinking, or uses any 'grill' trigger phrases. +- [writing-for-agents](skills/productivity/writing-for-agents/SKILL.md) — Writing documents for agents. Use when creating or editing skills, or modifying AGENTS.md or CLAUDE.md. -### Skill authoring +### Pstack -- [effective-agent-skills](skills/skill-authoring/effective-agent-skills/SKILL.md) — Write, review, and debug effective agent skills. +- [fix-merge-conflicts](skills/pstack/fix-merge-conflicts/SKILL.md) — Resolve merge conflicts non-interactively, validate build and tests, and finalize conflict resolution +- [how](skills/pstack/how/SKILL.md) — Use for "how does X work", code walkthroughs before changing something, and placement / ownership / layering questions ("where should this live", "which package owns this", "is this the right layer"). Explains subsystem architecture, runtime flow, onboarding mental models. Can critique architecture. Use why for motivation. +- [reflect](skills/pstack/reflect/SKILL.md) — Review a conversation for durable learnings and propose targeted edits to existing agent skills. Use when the user says "reflect", or when a complex workflow, correction, or recoverable dead end produced a reusable lesson. +- [unslop](skills/pstack/unslop/SKILL.md) — Cut AI writing patterns while preserving meaning and voice. Use when drafting, editing, or polishing prose, messages, or documentation. +- [why](skills/pstack/why/SKILL.md) — Investigate why code exists or behaves this way using cited historical evidence. Use for design rationale, tradeoffs, regressions, postmortems, and data-backed thresholds. Distinguishes motivation from how the code currently works. -### Thinking and docs +### Skill Authoring -- [brain-to-docs](skills/thinking-and-docs/brain-to-docs/SKILL.md) — Extract project vision, decisions, and preferences into documentation. -- [next-decision](skills/thinking-and-docs/next-decision/SKILL.md) — Drill into the next unresolved decision with choices and a recommendation. -- [prompt-me](skills/thinking-and-docs/prompt-me/SKILL.md) — Ask pointed questions to extract project priorities and concerns. -- [save-idea](skills/thinking-and-docs/save-idea/SKILL.md) — Capture content ideas in the user's content backlog. +- [effective-agent-skills](skills/skill-authoring/effective-agent-skills/SKILL.md) — How to write effective agent skills — what to do, what not to do, anatomy, progressive disclosure, design patterns, anti-patterns, testing, security. Read this whenever a skill (Claude Skill, Agent Skill, SKILL.md) is being created, edited, reviewed, or debugged. Use when the user says "create a skill", "new skill", "update this skill", "improve a skill", "why isn't my skill triggering", or anything else involving authoring or editing SKILL.md files. + +### Thinking And Docs + +- [brain-to-docs](skills/thinking-and-docs/brain-to-docs/SKILL.md) — Use when the user wants to extract project vision, decisions, and preferences from his head into clear documentation (README + ADRs) through a back-and-forth Q&A loop. Triggers on "brain-to-docs", "build out the docs", "extract the vision", "let's document this project". +- [next-decision](skills/thinking-and-docs/next-decision/SKILL.md) — Drill open decisions one at a time — present the most important decision not yet clarified, give the top four choices, state a preference, ask the user. Use when the user says "next decision", "one decision at a time", or a plan has several unresolved choices. Differentiator: forward-looking; the decisions skill is retrospective (choices already made). Can be invoked with /next-decision. +- [prompt-me](skills/thinking-and-docs/prompt-me/SKILL.md) — Prompt the user with pointed questions to extract what is in his head about a project — remaining work, what is being avoided, what really matters, what does not. Use when the user says "prompt me", "ask me questions", or wants the agent to figure out priorities by questioning him. +- [save-idea](skills/thinking-and-docs/save-idea/SKILL.md) — Quickly capture a content idea into ~/code/content from any repo or chat. Video ideas go to VIDEO-IDEAS.md; smaller podcast topics, guest ideas, questions, and AI observations go to TOPICS.md. Every entry gets a source line referencing the chat and repo it came from. Use when the user says "/save-idea", "save this idea", "video idea", "add a topic", "write this down for a video/podcast". Differentiator: appends to the user''s content backlog — not a reminder, task, or general note tool. diff --git a/skills/engineering/README.md b/skills/engineering/README.md index a9b346d..fdb3beb 100644 --- a/skills/engineering/README.md +++ b/skills/engineering/README.md @@ -4,33 +4,38 @@ Daily code work. ## User-invoked +- [thermo-nuclear-code-quality-review](code-quality-review/SKILL.md) — Run an extremely strict maintainability review for abstraction quality, giant files, and spaghetti-condition growth. Use for a thermo-nuclear code quality review, thermonuclear review, deep code quality audit, or especially harsh maintainability review. - [commit-staged](commit-staged/SKILL.md) — Commit staged files with a conventional commit message. -- [grill-with-docs](grill-with-docs/SKILL.md) — Interview the user to sharpen a plan or design while creating ADRs and glossary docs. -- [implement](implement/SKILL.md) — Implement a piece of work from a spec or set of tickets. -- [implement-isolation](implement-isolation/SKILL.md) — Implement a piece of work from a spec or set of tickets in isolation. -- [implement-isolation-tmux](implement-isolation-tmux/SKILL.md) — Dispatch an isolated worktree agent to implement work from a PRD or issues. -- [improve-codebase-architecture](improve-codebase-architecture/SKILL.md) — Find and work through opportunities to deepen a codebase's architecture. +- [grill-with-docs](grill-with-docs/SKILL.md) — A relentless interview to sharpen a plan or design, which also creates docs (ADR's and glossary) as we go. +- [implement](implement/SKILL.md) — Implement a piece of work based on a spec or set of tickets. +- [implement-isolation](implement-isolation/SKILL.md) — Implement a piece of work based on a spec or set of tickets in isolation. +- [implement-isolation-tmux](implement-isolation-tmux/SKILL.md) — Dispatch a child agent in an isolated git worktree to implement a piece of work based on a PRD or set of issues. +- [implement-spec](implement-spec/SKILL.md) — Implement the result of /to-spec and /to-tickets in code. +- [implementation-orchestrator](implementation-orchestrator/SKILL.md) — Implements ready-for-agent tracker tickets through isolated worktrees, pull requests, review, conflict resolution, and merge. Use after wayfinder and planning have produced tickets, with or without a ticket ID/URL; no ticket ID/URL means process available tickets. Does not create planning tickets. +- [improve-codebase-architecture](improve-codebase-architecture/SKILL.md) — Scan a codebase for deepening opportunities, present them as a visual HTML report, then grill through whichever one you pick. - [orchestrate-herdr](orchestrate-herdr/SKILL.md) — Drive a plan from context or @file through a published spec, linked tickets, and one-at-a-time isolated implementation to a merged PR using Herdr and Pi agents. -- [project-context-pack](project-context-pack/SKILL.md) — Build a bounded project context pack for later agent work. -- [recipe-diagrams](recipe-diagrams/SKILL.md) — Convert recipes into high-resolution process-flow diagrams. -- [setup-skills](../setup-skills/SKILL.md) — Configure engineering skills, issue tracking, triage labels, and domain docs. -- [to-spec](to-spec/SKILL.md) — Turn the current conversation into a spec and publish it to the issue tracker. -- [to-tickets](to-tickets/SKILL.md) — Break a plan or spec into tracer-bullet tickets with dependencies. -- [triage](triage/SKILL.md) — Triage issues and external PRs through the project workflow. -- [wayfinder](wayfinder/SKILL.md) — Plan large work as decision tickets and resolve them step by step. +- [project-context-pack](project-context-pack/SKILL.md) — Use when the user wants a bounded repo context pack, project map, codebase index, or cached memory file so later work uses fd/rg/tree-sitter/LSP instead of repeated browsing. +- [recipe-diagrams](recipe-diagrams/SKILL.md) — Recipe diagrams: convert any recipe into a high-resolution Cooking for Engineers-style PNG process-flow table with aligned ingredient streams, preparation branches, joins, temperatures, timings, and finish steps. Use when the user asks for a recipe diagram. +- [security-audit](security-audit/SKILL.md) — Comprehensive security and correctness audit of a branch's changes. Use for deep review requests, or branch/PR diff audits focused on bugs, breaking changes, security issues, devex regressions, and feature-gate leaks. +- [triage](triage/SKILL.md) — Move issues and external PRs through a state machine of triage roles, categorise, verify, grill if needed, and write agent-ready briefs. +- [wayfinder](wayfinder/SKILL.md) — Plan a huge chunk of work (more than one agent session can hold) as a shared map of decision tickets on your issue tracker, and resolve them one at a time until the way to the destination is clear. ## Model-invoked -- [code-review](code-review/SKILL.md) — Review changes against repository standards and the originating specification. -- [codebase-design](codebase-design/SKILL.md) — Design and improve deep module interfaces and seams. -- [dual-review](dual-review/SKILL.md) — Run parallel correctness/security and maintainability reviews of a branch diff, then synthesize findings. -- [diagnosing-bugs](diagnosing-bugs/SKILL.md) — Diagnose hard bugs and performance regressions. -- [domain-modeling](domain-modeling/SKILL.md) — Build and sharpen a project's domain model. -- [lsp-code-analysis](lsp-code-analysis/SKILL.md) — Navigate code and analyze it semantically with LSP. -- [prototype](prototype/SKILL.md) — Build a throwaway prototype to answer a design question. -- [research](research/SKILL.md) — Investigate a question using high-trust sources and capture the findings. -- [resolving-merge-conflicts](resolving-merge-conflicts/SKILL.md) — Resolve an in-progress Git merge or rebase conflict. -- [tdd](tdd/SKILL.md) — Use test-driven development for features, bugs, and integration tests. -- [wizard](wizard/SKILL.md) — Generate an interactive wizard for steps only a human can perform. -- [worktrees](worktrees/SKILL.md) — Manage Git worktrees in a canonical repository root. -- [write-discoverable-code](write-discoverable-code/SKILL.md) — Write code agents and humans can find through plain-text search. +- [code-review](code-review/SKILL.md) — Review the changes since a fixed point (commit, branch, tag, or merge-base) along two axes: Standards (does the code follow this repo's documented coding standards?) and Spec (does the code match what the originating issue/spec asked for?). Runs both reviews in parallel sub-agents and reports them side by side. Use when the user wants to review a branch, a PR, work-in-progress changes, or asks to "review since X". +- [codebase-design](codebase-design/SKILL.md) — Shared vocabulary for designing deep modules. Use when the user wants to design or improve a module's interface, find deepening opportunities, decide where a seam goes, make code more testable or AI-navigable, or when another skill needs the deep-module vocabulary. +- [diagnosing-bugs](diagnosing-bugs/SKILL.md) — Diagnosis loop for hard bugs and performance regressions. Use when the user says "diagnose"/"debug this", or reports something broken/throwing/failing/slow. +- [domain-modeling](domain-modeling/SKILL.md) — Build and sharpen a project's domain model. Use when discussing codebase terminology, writing or editing a CONTEXT.md, or recording or editing an ADR. +- [dual-review](dual-review/SKILL.md) — Run two independent, read-only reviews of a branch diff in parallel — correctness/security and maintainability — then synthesize prioritized findings. Use for a second review axis alongside code-review, a combined deep plus code-quality audit, or when the user asks for dual review. Runs both axes as parallel sub-agents so they do not pollute each other's context. +- [forge-cli](forge-cli/SKILL.md) — Provides copy-paste, non-interactive tea, gh, and glab commands for issue and pull or merge request work. Use whenever a task needs tracker inspection, assignment, labels, comments, reviews, CI, or merge operations. +- [lsp-code-analysis](lsp-code-analysis/SKILL.md) — Semantic code analysis via LSP. Navigate code (definitions, references, implementations), search symbols, preview refactorings, and get file outlines. Use for exploring unfamiliar codebases or performing safe refactoring. +- [pr](pr/SKILL.md) — Use when writing a PR body. +- [prototype](prototype/SKILL.md) — Build a throwaway prototype to answer a design question. Use when the user wants to sanity-check whether a state model or logic feels right, or explore what a UI should look like. +- [research](research/SKILL.md) — Investigate a question against high-trust primary sources and capture the findings as a Markdown file in the repo. Use when the user wants a topic researched, docs or API facts gathered, or reading legwork delegated to a background agent. +- [resolving-merge-conflicts](resolving-merge-conflicts/SKILL.md) — Use when you need to resolve an in-progress git merge/rebase conflict. +- [tdd](tdd/SKILL.md) — Test-driven development. Use when the user wants to build features or fix bugs test-first, mentions "red-green-refactor", or wants integration tests. +- [to-spec](to-spec/SKILL.md) — Turn the current conversation into a spec and publish it to the project issue tracker: no interview, just synthesis of what you've already discussed. Use when the user wants a spec from the current conversation or an orchestration workflow needs to publish one from context. +- [to-tickets](to-tickets/SKILL.md) — Break a plan, spec, or the current conversation into tracer-bullet tickets with blocking edges, published to the configured tracker. Use when the user wants tickets from a plan or spec, or an orchestration workflow needs agent-grabbable tickets. +- [wizard](wizard/SKILL.md) — Generate an interactive bash wizard that walks a human through steps only they can perform. Use when provisioning infrastructure, setting up credentials or CI secrets, walking an unfamiliar third-party dashboard, or running a one-off migration or cutover. Don't invoke this for steps the agent can perform itself. +- [worktrees](worktrees/SKILL.md) — Manage Git worktrees in a canonical `.bare` repository root. Use when creating, reusing, listing, removing, or repairing worktrees, or when setting up a repository to keep all branch checkouts under one root. +- [write-discoverable-code](write-discoverable-code/SKILL.md) — | diff --git a/skills/in-progress/README.md b/skills/in-progress/README.md index 6ecaa70..fe8ddee 100644 --- a/skills/in-progress/README.md +++ b/skills/in-progress/README.md @@ -1,12 +1,12 @@ -# In-Progress Skills +# In Progress Skills Drafts not yet ready to ship. ## User-invoked -- [agent-handoff](agent-handoff/SKILL.md) — Hand the current conversation to a fresh background agent. -- [knowledge-gardener](knowledge-gardener/SKILL.md) — Run vault-aware search, synthesis, note creation, and linking workflows. +- [agent-handoff](agent-handoff/SKILL.md) — Hand the current conversation off to a fresh background agent that picks up the work immediately. +- [knowledge-gardener](knowledge-gardener/SKILL.md) — Run vault-aware semantic search, synthesis, note creation, linking, and Zettelkasten workflows for this Obsidian vault. ## Model-invoked -No model-invoked skills. +No skills. diff --git a/skills/misc/README.md b/skills/misc/README.md index 05f1dbd..e394aa6 100644 --- a/skills/misc/README.md +++ b/skills/misc/README.md @@ -1,16 +1,16 @@ -# Miscellaneous Skills +# Misc Skills Kept around but rarely used. ## User-invoked -- [bro](bro/SKILL.md) — Restate the last message in plain human language. -- [show-me](show-me/SKILL.md) — Help explain topics visually with concise diagrams and artifacts. -- [tmux-launch-agent](tmux-launch-agent/SKILL.md) — Fork a new agent CLI session into a new tmux window. -- [visual-verification](visual-verification/SKILL.md) — Verify running desktop UI changes with screenshots and recordings. +- [bro](bro/SKILL.md) — Restate the last message in plain human language, with no jargon. +- [show-me](show-me/SKILL.md) — Help the user understand the current topic visually with concise diagrams, code-shape sketches, and focused HTML artifacts. +- [tmux-launch-agent](tmux-launch-agent/SKILL.md) — Fork a new agent CLI session into a new tmux window, detected from the current agent. +- [visual-verification](visual-verification/SKILL.md) — Verify running desktop UI changes with screenshots and recordings. Use when changing shell styling, layout, panels, menus, notifications, animations, transitions, or capture flows; inspect the artifacts before reporting completion. ## Model-invoked -- [migrate-to-shoehorn](migrate-to-shoehorn/SKILL.md) — Migrate test assertions from `as` to `@total-typescript/shoehorn`. -- [scaffold-exercises](scaffold-exercises/SKILL.md) — Create linted exercise directories with problems, solutions, and explainers. -- [setup-pre-commit](setup-pre-commit/SKILL.md) — Set up Husky, lint-staged, type checking, and tests. +- [migrate-to-shoehorn](migrate-to-shoehorn/SKILL.md) — Migrate test files from `as` type assertions to @total-typescript/shoehorn. Use when user mentions shoehorn, wants to replace `as` in tests, or needs partial test data. +- [scaffold-exercises](scaffold-exercises/SKILL.md) — Create exercise directory structures with sections, problems, solutions, and explainers that pass linting. Use when user wants to scaffold exercises, create exercise stubs, or set up a new course section. +- [setup-pre-commit](setup-pre-commit/SKILL.md) — Set up Husky pre-commit hooks with lint-staged (Prettier), type checking, and tests in the current repo. Use when user wants to add pre-commit hooks, set up Husky, configure lint-staged, or add commit-time formatting/typechecking/testing. diff --git a/skills/personal/README.md b/skills/personal/README.md index 1a3e8e8..4fb05e9 100644 --- a/skills/personal/README.md +++ b/skills/personal/README.md @@ -4,5 +4,9 @@ Skills tied to the user's own setup and not promoted as general-purpose workflow ## User-invoked -- [arch-maintenance](arch-maintenance/SKILL.md) — Keep an Arch/CachyOS system updated and healthy with status, check, and update workflows. -- [arch-troubleshooting](arch-troubleshooting/SKILL.md) — Diagnose and repair Arch/CachyOS system problems. +- [arch-maintenance](arch-maintenance/SKILL.md) — Keep an Arch or CachyOS system updated and healthy with status, check, and update workflows. +- [arch-troubleshooting](arch-troubleshooting/SKILL.md) — Diagnose and repair Arch or CachyOS system problems. + +## Model-invoked + +No skills. diff --git a/skills/pkm/README.md b/skills/pkm/README.md index a8d7277..58cb1c0 100644 --- a/skills/pkm/README.md +++ b/skills/pkm/README.md @@ -1,14 +1,14 @@ -# PKM Skills +# Pkm Skills Personal knowledge management. ## User-invoked -- [conversation-summary](conversation-summary/SKILL.md) — Save the current conversation as a report note in an Obsidian vault. -- [crit](crit/SKILL.md) — Run the CRIT framework through context, role, interview, and task. -- [research-vault](research-vault/SKILL.md) — Research a topic through a guided conversation and save a linked vault packet. -- [youtube-video-capture](youtube-video-capture/SKILL.md) — Capture a YouTube video's subtitles and summary in an Obsidian vault. +- [conversation-summary](conversation-summary/SKILL.md) — Save the current conversation as a comprehensive report note in your Obsidian vault, following OKF v0.1 conventions. +- [crit](crit/SKILL.md) — Run the CRIT framework — give the AI Context, assign it a Role, let it Interview you one question at a time, then issue the Task. +- [research-vault](research-vault/SKILL.md) — Research a topic through a one-question-at-a-time learning conversation, answer directly, share resources when useful, and save a linked OKF-conformant research packet in the Obsidian vault. +- [youtube-video-capture](youtube-video-capture/SKILL.md) — Fetch subtitles from a YouTube video, summarize the content, and save both the summary and raw subtitles to the Video bundle in the Obsidian vault. Use when the user wants to capture a YouTube video, mentions "summarize this video", "capture this talk", or pastes a YouTube URL wanting it saved to vault. ## Model-invoked -- [pkm-curation](pkm-curation/SKILL.md) — Curate an Obsidian vault with classification, links, and atomic notes. +- [pkm-curation](pkm-curation/SKILL.md) — Curate an Obsidian vault — classify notes, normalize frontmatter, add links, extract atomic notes. Use when curating, batch-processing, reviewing, or doing a serendipity pick. diff --git a/skills/productivity/README.md b/skills/productivity/README.md index 04c10da..5caa14d 100644 --- a/skills/productivity/README.md +++ b/skills/productivity/README.md @@ -4,13 +4,12 @@ General workflow tools, not code-specific. ## User-invoked -- [grill-me](grill-me/SKILL.md) — Interview the user to sharpen a plan or design. -- [handoff](handoff/SKILL.md) — Compact the current conversation into a handoff document. -- [teach](teach/SKILL.md) — Teach the user a new skill or concept within the workspace. -- [to-questionnaire](to-questionnaire/SKILL.md) — Turn an unresolved decision into a questionnaire. -- [wait-what](wait-what/SKILL.md) — Re-pitch the last message in clearer terms. +- [grill-me](grill-me/SKILL.md) — A relentless interview to sharpen a plan or design. +- [handoff](handoff/SKILL.md) — Compact the current conversation into a handoff document for another agent to pick up. +- [to-questionnaire](to-questionnaire/SKILL.md) — Turn a decision you can't fully answer into a questionnaire for someone else to fill in. +- [wait-what](wait-what/SKILL.md) — Stop. That last message did not land: re-pitch it. ## Model-invoked -- [grilling](grilling/SKILL.md) — Grill the user relentlessly about a plan or design. -- [writing-for-agents](writing-for-agents/SKILL.md) — Write effective documents for agents. +- [grilling](grilling/SKILL.md) — Grill the user relentlessly about a plan, decision, or idea. Use when the user wants to stress-test their thinking, or uses any 'grill' trigger phrases. +- [writing-for-agents](writing-for-agents/SKILL.md) — Writing documents for agents. Use when creating or editing skills, or modifying AGENTS.md or CLAUDE.md. diff --git a/skills/pstack/README.md b/skills/pstack/README.md new file mode 100644 index 0000000..d5ab996 --- /dev/null +++ b/skills/pstack/README.md @@ -0,0 +1,16 @@ +# Pstack Skills + +Personal agent workflow skills. + +## User-invoked + +- [bugfix-regression-test](bugfix-regression-test/SKILL.md) — Fix bugs test-first with a focused regression test when practical. +- [interrogate](interrogate/SKILL.md) — Use for "interrogate", "adversarial review", "multi-model review", "challenge this", "stress test this code", "find blind spots", or "tear this apart". Uses available subagents for independent, evidence-backed review. + +## Model-invoked + +- [fix-merge-conflicts](fix-merge-conflicts/SKILL.md) — Resolve merge conflicts non-interactively, validate build and tests, and finalize conflict resolution +- [how](how/SKILL.md) — Use for "how does X work", code walkthroughs before changing something, and placement / ownership / layering questions ("where should this live", "which package owns this", "is this the right layer"). Explains subsystem architecture, runtime flow, onboarding mental models. Can critique architecture. Use why for motivation. +- [reflect](reflect/SKILL.md) — Review a conversation for durable learnings and propose targeted edits to existing agent skills. Use when the user says "reflect", or when a complex workflow, correction, or recoverable dead end produced a reusable lesson. +- [unslop](unslop/SKILL.md) — Cut AI writing patterns while preserving meaning and voice. Use when drafting, editing, or polishing prose, messages, or documentation. +- [why](why/SKILL.md) — Investigate why code exists or behaves this way using cited historical evidence. Use for design rationale, tradeoffs, regressions, postmortems, and data-backed thresholds. Distinguishes motivation from how the code currently works. diff --git a/skills/setup-skills/README.md b/skills/setup-skills/README.md new file mode 100644 index 0000000..2842fbd --- /dev/null +++ b/skills/setup-skills/README.md @@ -0,0 +1,11 @@ +# Setup Skills + +One-time repository configuration workflows. + +## User-invoked + +- [setup-skills](SKILL.md) — Configure this repo for the engineering skills, issue tracker, triage label vocabulary, and domain doc layout. + +## Model-invoked + +No model-invoked skills. diff --git a/skills/skill-authoring/README.md b/skills/skill-authoring/README.md index e4e11a6..f4718f4 100644 --- a/skills/skill-authoring/README.md +++ b/skills/skill-authoring/README.md @@ -1,11 +1,11 @@ -# Skill Authoring +# Skill Authoring Skills Create and maintain effective agent skills. ## User-invoked -No user-invoked skills. +No skills. ## Model-invoked -- [effective-agent-skills](effective-agent-skills/SKILL.md) — Write, review, and debug effective agent skills. +- [effective-agent-skills](effective-agent-skills/SKILL.md) — How to write effective agent skills — what to do, what not to do, anatomy, progressive disclosure, design patterns, anti-patterns, testing, security. Read this whenever a skill (Claude Skill, Agent Skill, SKILL.md) is being created, edited, reviewed, or debugged. Use when the user says "create a skill", "new skill", "update this skill", "improve a skill", "why isn't my skill triggering", or anything else involving authoring or editing SKILL.md files. diff --git a/skills/thinking-and-docs/README.md b/skills/thinking-and-docs/README.md index 73b79b9..6e8142a 100644 --- a/skills/thinking-and-docs/README.md +++ b/skills/thinking-and-docs/README.md @@ -1,20 +1,20 @@ -# Thinking and Docs Skills +# Thinking And Docs Skills Clarify decisions, capture ideas, and improve project documentation. ## User-invoked -- [before-building](before-building/SKILL.md) — Surface consequential choices when the user proposes a build. -- [decisions](decisions/SKILL.md) — List choices made during the current work that remain uncertain. -- [level-up](level-up/SKILL.md) — Assess technical and product knowledge and grow a learning plan. -- [read-all-adrs](read-all-adrs/SKILL.md) — Read every ADR in the project's `docs/adr/` folder. -- [remind](remind/SKILL.md) — Rewrite the last response more simply and briefly. -- [short](short/SKILL.md) — Compress the current answer while keeping its substance. -- [teach](teach/SKILL.md) — Teach the user a new skill or concept within the workspace. +- [before-building](before-building/SKILL.md) — Fire the moment the user proposes a build. Instantly surface the 1-3 consequential choices hidden in his idea. Can also be invoked with /before-building. +- [decisions](decisions/SKILL.md) — Ask the agent to list all choices it made during the current work that it is not confident of. Manual-only; invoke with /decisions. +- [level-up](level-up/SKILL.md) — Gauge the user''s technical + product knowledge through 7 adaptive questions, log verbatim answers with honest ratings, and grow a learning plan from the gaps found. Use when the user says "level up", "level-up session", "quiz me", "gauge my knowledge", or wants a new assessment round. Differentiator: this finds and maps gaps; the `teach` skill delivers lessons on them. +- [read-all-adrs](read-all-adrs/SKILL.md) — Read every ADR markdown file in the project's docs/adr/ folder so you have full context on past decisions. Use only when the user explicitly calls it. +- [remind](remind/SKILL.md) — Rewrite the last response simpler and shorter in plain English, prefixed with a 3-5 sentence TLDR of the conversation so far. Manual-only, invoked as /remind. +- [short](short/SKILL.md) — Manually-invoked skill that forces the agent to compress its current answer — strip filler, simplify wording, and cut length while keeping the substance. Use when the user says "short", "shorter", "simpler", "too long", "tl;dr", or wants a more concise version of the previous response. +- [teach](teach/SKILL.md) — Teach the user a new skill or concept, within this workspace. ## Model-invoked -- [brain-to-docs](brain-to-docs/SKILL.md) — Extract project vision, decisions, and preferences into documentation. -- [next-decision](next-decision/SKILL.md) — Drill into the next unresolved decision with choices and a recommendation. -- [prompt-me](prompt-me/SKILL.md) — Ask pointed questions to extract project priorities and concerns. -- [save-idea](save-idea/SKILL.md) — Capture content ideas in the user's content backlog. +- [brain-to-docs](brain-to-docs/SKILL.md) — Use when the user wants to extract project vision, decisions, and preferences from his head into clear documentation (README + ADRs) through a back-and-forth Q&A loop. Triggers on "brain-to-docs", "build out the docs", "extract the vision", "let's document this project". +- [next-decision](next-decision/SKILL.md) — Drill open decisions one at a time — present the most important decision not yet clarified, give the top four choices, state a preference, ask the user. Use when the user says "next decision", "one decision at a time", or a plan has several unresolved choices. Differentiator: forward-looking; the decisions skill is retrospective (choices already made). Can be invoked with /next-decision. +- [prompt-me](prompt-me/SKILL.md) — Prompt the user with pointed questions to extract what is in his head about a project — remaining work, what is being avoided, what really matters, what does not. Use when the user says "prompt me", "ask me questions", or wants the agent to figure out priorities by questioning him. +- [save-idea](save-idea/SKILL.md) — Quickly capture a content idea into ~/code/content from any repo or chat. Video ideas go to VIDEO-IDEAS.md; smaller podcast topics, guest ideas, questions, and AI observations go to TOPICS.md. Every entry gets a source line referencing the chat and repo it came from. Use when the user says "/save-idea", "save this idea", "video idea", "add a topic", "write this down for a video/podcast". Differentiator: appends to the user''s content backlog — not a reminder, task, or general note tool.