steve/skills
Public Access
1
0
Fork 0
Code Issues 11 Pull Requests 1 Actions Packages Projects Releases Wiki Activity

Compare commits

base: steve/skills:d956e513a496dfc2873fabb404f7ec7016115e96
Branches Tags
steve/skills:master steve/skills:issue-16-provider-neutral-tracker-automation-cli-and-library
..
compare: steve/skills:71525bc349f8bdf435f82d3137e4d8be99b30321
Branches Tags
steve/skills:master steve/skills:issue-16-provider-neutral-tracker-automation-cli-and-library
2 Commits
d956e513a4 .. 71525bc349
Author SHA1 Message Date
gitadmin 71525bc349 feat(feedback-bundle): commit-linked Gitea tickets with file attachments 
New model-invoked skill + feedback_bundle.py: creates a Gitea issue whose
body links the current HEAD commit and uploads logs/screenshots as issue
assets. Handles label-name-to-ID resolution, tea-config token lookup, and
the disabled-attachments (403/404) case. Index updated in root and
engineering READMEs.
 2026-10-06 14:06:01 -04:00
gitadmin 01c488157d docs: rewrite repo indexes and context pack for skills/ layout 
Replace the stale common/ structure docs with the current skills/ bucket
layout. Root and bucket READMEs now index every SKILL.md by invocation
type, AGENTS.md lists the ten actual buckets, and the project context
pack is condensed to purpose, structure, conventions, and validation.
 2026-10-06 14:00:45 -04:00
15 changed files with 448 additions and 261 deletions
Expand all files Collapse all files
.agent/project-context.md
+19 -102
View File
@@ -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/<category>/`
- 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.
AGENTS.md
+11 -20
View File
@@ -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
README.md
+92 -72
View File
@@ -4,116 +4,136 @@ 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.
- [feedback-bundle](skills/engineering/feedback-bundle/SKILL.md) — Post a Gitea feedback issue linked to the current commit and attach logs or screenshots. Use when the user reports a problem and asks to file it with evidence, open a bug ticket, or says “feedback-bundle” or “attach the log.”
- [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.
skills/engineering/README.md
+31 -25
View File
@@ -4,33 +4,39 @@ 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.
- [feedback-bundle](feedback-bundle/SKILL.md) — Post a Gitea feedback issue linked to the current commit and attach logs or screenshots. Use when the user reports a problem and asks to file it with evidence, open a bug ticket, or says “feedback-bundle” or “attach the log.”
- [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) — |
skills/engineering/feedback-bundle/SKILL.md
+40
View File
@@ -0,0 +1,40 @@
---
name: feedback-bundle
description: Post a Gitea feedback issue linked to the current commit and attach logs or screenshots. Use when the user reports a problem and asks to file it with evidence, open a bug ticket, or says "feedback-bundle" or "attach the log".
---
# Feedback Bundle
Create a Gitea issue in the current repository, linked to its current `HEAD`, with optional files attached.
## Run
Run from the repository the issue should belong to, using `feedback_bundle.py` beside this file:
```sh
python3 <skill-dir>/feedback_bundle.py "Describe the problem" @app.log @screenshot.png
```
The script requires Python `requests`. Without `--token`, it reads the matching host token from `~/.config/tea/config.yml` and requires PyYAML. The default repository is read from `git remote get-url origin`.
Common options:
```sh
python3 <skill-dir>/feedback_bundle.py "Description" @log.txt \
--title "Short issue title" --label bug --dry-run
```
- `@file` — attach an existing file; paths are resolved from the current working directory. The `@` is optional.
- `--title` — override the default title (the description's first line).
- `--label` — add a label; repeat to add more. Labels are resolved against the repository's Gitea labels; unknown labels are skipped with a warning.
- `--repo` — override the remote URL. Use a full Git remote URL (SSH, SCP-style, or HTTPS), not an `owner/repo` slug.
- `--token` — provide a Gitea token instead of reading tea config.
- `--dry-run` — print the issue preview without creating an issue or uploading files. Authentication is still loaded; labels require an API request.
## What happens
1. The script reads `HEAD`, repository host/owner/name, and authentication.
2. It creates an issue whose body includes a link to that exact commit.
3. It uploads each attachment to the issue and adds download links to the body.
Gitea only accepts issue attachments after an issue exists. If uploads fail because attachments are disabled (403/404), the issue already exists without the files; enable attachments on the Gitea instance, then attach the files to that issue manually. The instance setting is `[attachment] ENABLED = true` in `app.ini` (or `ATTACHMENTS_ENABLED`), not a web UI toggle.
skills/engineering/feedback-bundle/feedback_bundle.py
+183
View File
@@ -0,0 +1,183 @@
#!/usr/bin/env python3
"""Post a feedback ticket to a Gitea repo, linked to the current commit, with
files attached to the issue.
feedback_bundle.py [--title T] [--label L ...] [--repo REMOTE_URL] [--token T]
[--dry-run] <description> [@file ...]
Flow (Gitea attaches files to an existing issue, there is no standalone upload
endpoint): create the issue, then POST each file to
/repos/{owner}/{repo}/issues/{number}/assets (multipart field "attachment").
The ticket body links to `git HEAD` and lists the attached files.
If the assets endpoint returns 403/404 the instance has attachments disabled
(admin `[attachment] ENABLED = true` in app.ini — not a web-UI setting); the
script reports this instead of posting a ticket with no attachments.
"""
from __future__ import annotations
import argparse
import os
import re
import subprocess
import sys
try:
import requests
except ImportError: # pragma: no cover
sys.exit("requests is required: pip install requests")
def run(*args: str) -> str:
return subprocess.run(args, capture_output=True, text=True, check=True).stdout.strip()
def parse_remote(remote: str | None) -> tuple[str, str, str]:
"""(host, owner, repo) from a git remote URL (scp, ssh, or https forms)."""
url = remote or run("git", "remote", "get-url", "origin")
u = re.sub(r"^[a-z]+://", "", url.strip(), flags=re.I) # strip scheme
u = u.split("@", 1)[-1] # strip user@
u = u.replace(".git", "").rstrip("/")
host, rest = (u.split(":", 1) if ":" in u else u.split("/", 1))
owner, repo = rest.split("/", 1)
return host, owner, repo
def load_token(host: str, token: str | None) -> str:
if token:
return token
cfg = os.path.expanduser("~/.config/tea/config.yml")
if not os.path.exists(cfg):
sys.exit("no --token and no tea config found; cannot authenticate")
import yaml
data = yaml.safe_load(open(cfg).read())
for login in data.get("logins", []):
if login.get("url").rstrip("/").endswith(host) and login.get("token"):
return login["token"]
sys.exit(f"no stored token for host {host}; pass --token")
def resolve_labels(host, token, owner, repo, names):
"""Gitea's issue API wants label IDs, not names. Map names to IDs; warn on
unknown labels and drop them."""
if not names:
return []
url = f"https://{host}/api/v1/repos/{owner}/{repo}/labels"
r = requests.get(url, headers={"Authorization": f"token {token}"})
if r.status_code >= 400:
sys.exit(f"could not list labels ({r.status_code}): {r.text}")
by_name = {l["name"]: l["id"] for l in r.json()}
ids = []
for n in names:
if n in by_name:
ids.append(by_name[n])
else:
print(f"warning: unknown label '{n}', skipping", file=sys.stderr)
return ids
def create_issue(host, token, owner, repo, title, body, label_ids):
url = f"https://{host}/api/v1/repos/{owner}/{repo}/issues"
r = requests.post(url, json={"title": title, "body": body, "labels": label_ids},
headers={"Authorization": f"token {token}"})
if r.status_code >= 400:
sys.exit(f"issue create failed ({r.status_code}): {r.text}")
return r.json()
def attach(host, token, owner, repo, issue_number, path):
"""Attach one file to an issue. Returns the browser_download_url, or None
on 403/404 (attachments disabled on this instance)."""
url = f"https://{host}/api/v1/repos/{owner}/{repo}/issues/{issue_number}/assets"
with open(path, "rb") as f:
r = requests.post(url, files={"attachment": f},
params={"name": os.path.basename(path)},
headers={"Authorization": f"token {token}"})
if r.status_code in (403, 404):
return None
r.raise_for_status()
return r.json().get("browser_download_url")
def main() -> int:
ap = argparse.ArgumentParser(description="Post a commit-linked feedback ticket with attachments.")
ap.add_argument("description", help="ticket description (text before any @file)")
ap.add_argument("files", nargs="*", help="files to attach (@name or name)")
ap.add_argument("--title", help="ticket title (default: first line of description)")
ap.add_argument("--label", action="append", default=[], help="label to add (repeatable)")
ap.add_argument("--repo", help="Git remote URL (default: git remote origin)")
ap.add_argument("--token", help="Gitea token (default: tea config for the host)")
ap.add_argument("--dry-run", action="store_true", help="print the ticket without posting it")
args = ap.parse_args()
files = [f.lstrip("@") for f in args.files]
for p in files:
if not os.path.isfile(p):
sys.exit(f"not a file: {p}")
host, owner, repo = parse_remote(args.repo) if args.repo else (None, None, None)
if not host:
host, owner, repo = parse_remote(None)
token = load_token(host, args.token)
sha = run("git", "rev-parse", "HEAD")
short = sha[:7]
commit_url = f"https://{host}/{owner}/{repo}/commit/{sha}"
desc = args.description.strip()
title = (args.title or desc).strip().splitlines()[0] if desc else "(no description)"
labels = resolve_labels(host, token, owner, repo, [l for l in args.label if l])
seed = f"{desc}\n\n**Linked commit:** [{short}]({commit_url}) (`{sha}`)"
# Preview only: no issue is created and nothing is uploaded.
if args.dry_run:
att_line = "\n".join(f"- {os.path.basename(p)}" for p in files) or "(none)"
body = seed + "\n\n**Attachments:**\n" + att_line
print("=== DRY RUN (nothing created) ===")
print(f"repo: {owner}/{repo}")
print(f"commit: {commit_url}")
print(f"title: {title}")
print(f"labels: {[l for l in args.label if l] or '(none)'}")
print(f"attach: {att_line}")
print("=== body ===")
print(body)
return 0
# Create the issue first (Gitea attaches files to an existing issue).
issue = create_issue(host, token, owner, repo, title, seed, labels)
number = issue["number"]
attached = []
missing = False
for p in files:
url = attach(host, token, owner, repo, number, p)
if url is None:
missing = True
else:
attached.append((os.path.basename(p), url))
if missing and not attached:
print(
"ERROR: attachment endpoint returned 403/404 — attachments are disabled on this "
"instance (admin setting `[attachment] ENABLED = true` in app.ini; there is no "
"web-UI toggle). Enable it and re-run. The issue was created but has no attachments.",
file=sys.stderr,
)
return 2
if attached:
body = seed + "\n\n**Attachments:**\n" + "\n".join(f"- [{n}]({u})" for n, u in attached)
patch_url = f"https://{host}/api/v1/repos/{owner}/{repo}/issues/{number}"
requests.patch(patch_url, json={"body": body},
headers={"Authorization": f"token {token}"})
if missing:
print(f"warning: {sum(1 for _ in range(0)) + (len(files) - len(attached))} file(s) could not be attached (instance may have attachments disabled)",
file=sys.stderr)
print(f"Created: {issue.get('html_url', '')}")
return 0
if __name__ == "__main__":
raise SystemExit(main())
skills/in-progress/README.md
+4 -4
View File
@@ -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.
skills/misc/README.md
+8 -8
View File
@@ -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.
skills/personal/README.md
+6 -2
View File
@@ -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.
skills/pkm/README.md
+6 -6
View File
@@ -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.
skills/productivity/README.md
+6 -7
View File
@@ -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.
skills/pstack/README.md
+16
View File
@@ -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.
skills/setup-skills/README.md
+11
View File
@@ -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.
skills/skill-authoring/README.md
+3 -3
View File
@@ -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.
skills/thinking-and-docs/README.md
+12 -12
View File
@@ -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.