From 557c4a848b6497106e50e49e0d53973454004f98 Mon Sep 17 00:00:00 2001 From: Paul Buetow Date: Sun, 28 Jun 2026 23:13:34 +0300 Subject: Update --- prompts/commands/create-skill.md | 15 +- prompts/commands/update-skill.md | 17 +- prompts/sharable.md | 26 -- prompts/skills/agent-task-management/SKILL.md | 4 +- prompts/skills/blog-writing-style/SKILL.md | 135 ++--------- .../references/imap-scan-script.md | 24 +- prompts/skills/compose-blog-post/SKILL.md | 60 +---- prompts/skills/go-best-practices/SKILL.md | 34 +-- prompts/skills/rocky-vm-setup/SKILL.md | 267 ++------------------- prompts/skills/update-blog-post/SKILL.md | 2 +- 10 files changed, 112 insertions(+), 472 deletions(-) diff --git a/prompts/commands/create-skill.md b/prompts/commands/create-skill.md index ccd8233..b2f5972 100644 --- a/prompts/commands/create-skill.md +++ b/prompts/commands/create-skill.md @@ -20,18 +20,23 @@ I'll create a new skill called `{{skill_name}}`. Here's my process: - Determine the likely intent and use case - The name must be lowercase alphanumeric with hyphens only -2. **Generate the skill structure**: +2. **Follow the collection's conventions** — load the `skill-maintenance` skill and apply its references so the new skill is spec-compliant and consistent with the rest of the collection: + - *best-practices*: valid frontmatter (`name` lowercase a-z/0-9/hyphens, ≤64 chars; `description` ≤1024 chars stating **what** and **when to use** with trigger keywords), progressive disclosure (`SKILL.md` < 500 lines / < 5000 tokens; move detail to `references/`; one topic per reference file; refs one level deep), self-contained scripts. + - *dry-across-skills*: before duplicating knowledge that another skill already owns (a snippet, a convention, a discipline), give it a **single canonical home** and cross-link with `../sibling/SKILL.md` instead of copy-pasting. Surface ownership conflicts to the user. + - *sub-division*: keep `SKILL.md` a slim index (overview + When to Use + Reference Files list + optional quick-reference); put detail in `references/`. Never let `SKILL.md` re-inline content that lives in its own `references/`. + +3. **Generate the skill structure**: - Create YAML frontmatter with `name` and `description` - Write a "When to Use" section - - Write detailed instructions for the skill + - Write detailed instructions (or an index pointing to `references/` if the skill is large) -3. **Show you a preview** of the generated SKILL.md and ask if you want to: +4. **Show you a preview** of the generated SKILL.md and ask if you want to: - Use it as-is - Modify the description - Refine the instructions -4. **Save the skill** to `~/Notes/Prompts/skills/{{skill_name}}/SKILL.md` +5. **Save the skill** to `~/Notes/Prompts/skills/{{skill_name}}/SKILL.md` -5. **Confirm** the skill is ready to use as `/{{skill_name}}` +6. **Confirm** the skill is ready to use as `/{{skill_name}}` Let me start by analyzing the skill name and generating the initial version... diff --git a/prompts/commands/update-skill.md b/prompts/commands/update-skill.md index b55dd61..aceb17b 100644 --- a/prompts/commands/update-skill.md +++ b/prompts/commands/update-skill.md @@ -20,21 +20,28 @@ I need to update an existing skill. Please follow these steps: 2. **Show me the current content** of the skill in a clear, organized format -3. **Ask me what I want to update** using the AskUserQuestion tool: +3. **Audit it against the collection's conventions** — load the `skill-maintenance` skill and run its `references/audit-checklist.md` against this skill. Surface findings before editing: + - *best-practices*: frontmatter valid (`name`/`description` rules, `description` ≤1024 with trigger keywords), `SKILL.md` < 500 lines, file refs one level deep, no missing `description`. + - *dry-across-skills*: does this skill duplicate knowledge another skill owns? Should shared knowledge get a single canonical home with cross-links instead? + - *sub-division*: does `SKILL.md` re-inline content that already lives in its own `references/`? Should detail move to focused `references/` so `SKILL.md` becomes a slim index? + - Broken internal / cross-skill links. + Present the audit findings alongside the content; let the user decide what to fix (do not silently refactor). + +4. **Ask me what I want to update** using the AskUserQuestion tool: - Description (YAML frontmatter) - When to Use section - Instructions - All of the above -4. **Guide me through the updates** interactively: +5. **Guide me through the updates** interactively: - For description: Ask for the new description - For When to Use: Ask what triggers should be added or changed - For instructions: Ask for the new content or specific sections to change -5. **Show me a preview** of the updated skill before saving +6. **Show me a preview** of the updated skill before saving -6. **Save the updated skill** back to `~/Notes/Prompts/skills/{{skill_name}}/SKILL.md` +7. **Save the updated skill** back to `~/Notes/Prompts/skills/{{skill_name}}/SKILL.md` -7. **Confirm** the update was successful and summarize what changed +8. **Confirm** the update was successful and summarize what changed Be helpful and thorough - make sure I understand each change and why it improves the skill. diff --git a/prompts/sharable.md b/prompts/sharable.md index 9e95d57..46d7d29 100644 --- a/prompts/sharable.md +++ b/prompts/sharable.md @@ -1,28 +1,2 @@ # Sharable prompts -commands/are-you-sure.md -commands/commit-and-push-to-git.md -commands/create-command.md -commands/create-context.md -commands/create-skill.md -commands/create-tasks.md -commands/delete-command.md -commands/delete-context.md -commands/delete-skill.md -commands/load-context.md -commands/review-changes.md -commands/update-command.md -commands/update-context.md -commands/update-skill.md -commands/work-on-tasks.md -skills/100-go-mistakes -skills/auditing-code-quality -skills/beyond-solid-principles -skills/c-best-practices -skills/go-best-practices -skills/increment-version-and-push -skills/purge-file-from-git -skills/solid-principles -skills/agent-task-management -skills/run-command -skills/bash-best-practices diff --git a/prompts/skills/agent-task-management/SKILL.md b/prompts/skills/agent-task-management/SKILL.md index dc851b7..9571192 100644 --- a/prompts/skills/agent-task-management/SKILL.md +++ b/prompts/skills/agent-task-management/SKILL.md @@ -57,8 +57,8 @@ When beginning a new task, **always use a fresh context** — spawn a sub-agent |--------|------| | **Create task** | `references/00-context.md` + `references/1-create-task.md` (include refs to all context required) | | **Start task** | `references/00-context.md` + `references/2-start-task.md` (start with fresh context; use task refs; **stay within task scope** — never patch vendored/upstream deps, flag as a blocker) | -| **Recover a stalled/interrupted task** | `references/00-context.md` + `references/6-recover-stalled-task.md` (detect partial edits, revert cleanly, resume) | -| **Complete task** | `references/00-context.md` + `references/3-complete-task.md` | +| **Recover a stalled/interrupted task** | `references/00-context.md` + `references/6-recover-stalled-task.md` (detect partial edits, revert cleanly, resume) + `references/verification-honesty.md` | +| **Complete task** | `references/00-context.md` + `references/3-complete-task.md` + `references/verification-honesty.md` (preflight, smallest verifying subset, annotate blockers, never over-claim) | | **Annotate / update task** | `references/00-context.md` + `references/4-annotate-update-task.md` | | **Review / overview tasks** | `references/00-context.md` + `references/5-review-overview-tasks.md` | diff --git a/prompts/skills/blog-writing-style/SKILL.md b/prompts/skills/blog-writing-style/SKILL.md index d30a0e6..86283c2 100644 --- a/prompts/skills/blog-writing-style/SKILL.md +++ b/prompts/skills/blog-writing-style/SKILL.md @@ -19,7 +19,9 @@ Rewrite blog content to sound authentically human by removing LLM-generated patt Detailed reference documentation is in the `references/` subfolder: -- [Signs of AI Writing](references/signs-of-ai-writing.md) — the deep, general-purpose reference based on Wikipedia's "Signs of AI writing" page (WikiProject AI Cleanup). Voice calibration, personality/soul injection, the 29 numbered AI patterns (content, language, style, communication, filler/hedging) with before/after examples, the full worked example, and the standard process/output format. Use this when you need the exhaustive pattern catalog beyond the foo.zone-specific guidance below. +- [Signs of AI Writing](references/signs-of-ai-writing.md) — the deep, general-purpose reference based on Wikipedia's "Signs of AI writing" page (WikiProject AI Cleanup). Voice calibration, personality/soul injection, the 29 numbered AI patterns (content, language, style, communication, filler/hedging) with before/after examples, the full worked example, and the standard process/output format. Use this when you need the exhaustive pattern catalog. +- [Patterns & Rewrite Examples](references/patterns-and-examples.md) — the foo.zone-focused working set: the LLM tells to hunt for (opening structures, corporate/marketing language, hedging, over-explanation, formal transitions, passive constructions, third-person distance) and concrete before/after rewrite pairs. +- [Gemtext Authoring Conventions](references/gemtext-conventions.md) — shared foo.zone gemtext rules (file rules, format constraints, post structure, TOC, links, images/diagrams, multi-part series). Used by this skill, `compose-blog-post`, and `update-blog-post`. ## Target Files @@ -49,43 +51,12 @@ Read 2-3 posts from 9+ months ago to absorb the authentic voice. Look at files d ### 3. Identify LLM Patterns to Remove -Rewrite text that contains these patterns: - -**Opening structures:** -- "This [noun] [verb]..." → Start with action or personal observation -- "As a [role], you..." → Use direct "You" or "I" statements -- "In today's world..." → Cut entirely or rephrase - -**Corporate/marketing language:** -- "robust", "vital", "ensuring", "leveraging", "enabling", "facilitating" -- "comprehensive", "seamless", "powerful", "efficient" -- Replace with simpler words or remove - -**Hedging language:** -- "often", "typically", "can help", "may", "might" -- "tends to", "generally", "usually" -- Replace with definitive statements or personal experience - -**Over-explanation:** -- Sentences explaining *why* something is useful after stating it -- Redundant clarifications -- Paragraphs that summarize what was just said -- Remove these entirely - -**Formal transitions:** -- "Furthermore", "Additionally", "Moreover", "In conclusion" -- "It's worth noting that", "It's important to understand" -- Replace with conversational transitions or just cut - -**Passive constructions:** -- "This can be achieved by..." → "You can do this by..." -- "It is recommended to..." → "I'd recommend..." or just state it directly - -**Third-person distance:** -- "The author suggests..." → "Larson suggests..." or "The book says..." -- "One should consider..." → "You might consider..." or "I'd..." - -For the exhaustive catalog of AI tells with before/after examples (29 numbered patterns), see [references/signs-of-ai-writing.md](references/signs-of-ai-writing.md). +Rewrite text that contains the LLM tells cataloged in +[references/patterns-and-examples.md](references/patterns-and-examples.md) +(opening structures, corporate/marketing language, hedging, over-explanation, +formal transitions, passive constructions, third-person distance). For the +exhaustive 29-pattern catalog with before/after examples, see +[references/signs-of-ai-writing.md](references/signs-of-ai-writing.md). ### 4. Apply Human Writing Patterns @@ -113,83 +84,17 @@ For the exhaustive catalog of AI tells with before/after examples (29 numbered p - Use specific details over generalizations - Show, don't tell -### 5. Concrete Rewrite Examples - -**Before (LLM):** -> "This blog post describes my hackathon efforts adding observability to X-RAG..." - -**After (Human):** -> "This post describes my hackathon efforts adding observability to X-RAG..." - ---- - -**Before (LLM):** -> "This thesis aims to make it easier for users to view distributed systems from a different perspective. Here, the viewpoint of an end user is not adopted; instead, the functional methods of protocols and their processes in distributed systems should be made comprehensible, while simultaneously making all relevant events of a distributed system transparent." - -**After (Human):** -> "This thesis aims to make distributed systems easier to understand from a different angle. Instead of the end-user perspective, it focuses on the functional methods of protocols and their processes, making all relevant events of a distributed system transparent." - ---- - -**Before (LLM):** -> "In the previous posts, I deployed applications to the k3s cluster using Helm charts and Justfiles—running `just install` or `just upgrade` to imperatively push changes to the cluster. While this approach works, it has several drawbacks:" - -**After (Human):** -> "In previous posts, I deployed applications to the k3s cluster using Helm charts and Justfiles—running `just install` or `just upgrade` to imperatively push changes to the cluster. Works fine, but has some drawbacks:" - ---- - -**Before (LLM):** -> "I especially made time available over the weekend to join his 3-day hackathon..." - -**After (Human):** -> "I made time over the weekend to join his 3-day hackathon..." - ---- - -**Before (LLM):** -> "It is insane how times have changed." - -**After (Human):** -> "Times have changed." - ---- - -**Before (LLM):** -> "Larson breaks down the role of a Staff Engineer into four main archetypes, which can help frame how you approach the role:" - -**After (Human):** -> "Larson defines four archetypes. You'll probably recognize yourself in one (or a mix):" - ---- - -**Before (LLM):** -> "As a Staff Engineer, influence is often more important than formal authority. You'll rarely have direct control over teams or projects but will need to drive outcomes by influencing peers, other teams, and leadership. It's about understanding how to persuade, align, and mentor others to achieve technical outcomes." - -**After (Human):** -> "You won't have direct authority over most people or teams you work with. Influence is the actual tool here. You have to persuade, align, sometimes just nudge people in the right direction. No one reports to you, but you still need to drive outcomes." - ---- - -**Before (LLM):** -> "Robust monitoring is vital to any infrastructure, especially one as distributed as mine. I've thought about a setup that ensures I'll always be aware of what's happening in my environment." - -**After (Human):** -> "I want to know when stuff breaks (ideally before it breaks), so monitoring is a big part of the plan." - ---- - -**Before (LLM):** -> "The Beelink S12 Pro with Intel N100 CPUs checks all the boxes for a k3s project: Compact, efficient, expandable, and affordable. Its compatibility with both Linux and FreeBSD makes it versatile for other use cases, whether as part of your cluster or as a standalone system." - -**After (Human):** -> "Honestly, the Beelink S12 Pro with the N100 is kind of perfect for this — tiny, cheap, sips power, and runs both Linux and FreeBSD without drama. I'm pretty happy with it." +Concrete before/after rewrite pairs are in +[references/patterns-and-examples.md](references/patterns-and-examples.md). -### 6. Gemtext Format Constraints +### 5. Gemtext Format Constraints -Gemtext (`.gmi` / `.gmi.tpl`) does NOT support Markdown bold (`**text**`) or italic (`*text*`). Gemtexter will not render these. Never use `**...**` or `*...*` for emphasis in blog posts. Instead, rely on sentence structure, word choice, or `backticks` for inline emphasis. +Gemtext has no Markdown bold/italic and a fixed post structure. Follow the +shared foo.zone conventions in +[references/gemtext-conventions.md](references/gemtext-conventions.md) (file +rules, format constraints, TOC, links, images/diagrams). -### 7. Preserve What Works +### 6. Preserve What Works Do NOT change: - Technical accuracy @@ -200,7 +105,7 @@ Do NOT change: - Personal anecdotes that already sound human - Direct quotes from sources (only rewrite your own commentary) -### 8. Process Each File +### 7. Process Each File 1. Read the target `.gmi.tpl` or standalone `.gmi` file 2. Identify sections that sound LLM-generated @@ -209,8 +114,8 @@ Do NOT change: 5. Show a diff before writing 6. Write the updated file -### 9. Related Skills +### 8. Related Skills When using `compose-blog-post` or `update-blog-post`, apply this writing style proactively to ensure new content sounds human from the start. Reference this skill when writing or editing any blog content. -For the full Wikipedia-based pattern catalog (voice calibration, personality/soul, the 29 numbered AI patterns, and the complete worked example), see [references/signs-of-ai-writing.md](references/signs-of-ai-writing.md). +For the full Wikipedia-based pattern catalog (voice calibration, personality/soul, the 29 numbered AI patterns, and the complete worked example), see [references/signs-of-ai-writing.md](references/signs-of-ai-writing.md). \ No newline at end of file diff --git a/prompts/skills/check-shopping-status/references/imap-scan-script.md b/prompts/skills/check-shopping-status/references/imap-scan-script.md index 3cae647..f6f8784 100644 --- a/prompts/skills/check-shopping-status/references/imap-scan-script.md +++ b/prompts/skills/check-shopping-status/references/imap-scan-script.md @@ -4,16 +4,30 @@ This script implements steps 1-3 of the workflow (scan all Shopping folders, classify, extract tracking codes/carriers) in a single pass. It is read-only (`BODY.PEEK`, `readonly=True`) and idempotent. +## Prerequisites (from the `protonbridge-imap` skill) + +The IMAP connection is **not** re-derived here. Load credentials and connect as +shown in the [`protonbridge-imap` skill](../protonbridge-imap/SKILL.md): load +`~/.protonbridge` into the environment, then `imaplib.IMAP4` → `starttls` +(self-signed cert, so `ssl.CERT_NONE`) → `login`, yielding a logged-in +connection `M`. The `decode_header`-based subject decode pattern shown there is +reused below via a small local `dh()` wrapper. + +This one-shot assumes `M` is already a logged-in IMAP4 connection. Only the +shopping-specific scanning/classification/extraction logic below is unique to +this skill. + +## Shopping scan + +`dh()` is a small local def that wraps `decode_header` (shown in +`protonbridge-imap`); kept inline because it runs on every subject/sender. + ```bash set -a; . ~/.protonbridge; . ~/.amazon; set +a python3 - <<'PY' import imaplib, os, ssl, email, re, html from email.header import decode_header -ctx = ssl.create_default_context(); ctx.check_hostname=False; ctx.verify_mode=ssl.CERT_NONE -M = imaplib.IMAP4(os.environ['IMAP_HOST'], int(os.environ['IMAP_PORT'])) -M.starttls(ssl_context=ctx); M.login(os.environ['IMAP_USER'], os.environ['IMAP_PASS']) - def dh(s): if not s: return '' return ''.join(p.decode(c or 'utf-8','replace') if isinstance(p, bytes) else p @@ -80,4 +94,4 @@ After IMAP extraction, for every Amazon progress-tracker URL: After this prints the candidates, run the headless-Chrome lookup loop for each tracking code/URL and assemble the final markdown report following the -format in step 5 of the parent `SKILL.md`. +format in step 5 of the parent `SKILL.md`. \ No newline at end of file diff --git a/prompts/skills/compose-blog-post/SKILL.md b/prompts/skills/compose-blog-post/SKILL.md index abe14d1..0dd8367 100644 --- a/prompts/skills/compose-blog-post/SKILL.md +++ b/prompts/skills/compose-blog-post/SKILL.md @@ -14,65 +14,19 @@ Compose a blog post in gemtext for the foo.zone gemfeed. **Only write or modify ## Instructions -1. **Match existing style.** Read 2–3 recent posts from `~/git/foo.zone-content/gemtext/gemfeed/*.gmi` or `*.gmi.tpl` (for style only; do not modify those .gmi files) to mirror: - - Title and published date format - - Optional ASCII art - - Table of Contents format - - Section levels and link style - - Closing (related posts, E-Mail, Back to main site) +1. **Match existing style.** Read 2–3 recent posts from `~/git/foo.zone-content/gemtext/gemfeed/*.gmi` or `*.gmi.tpl` (for style only; do not modify those .gmi files) to mirror title/date format, ASCII art usage, section levels, link style, and closing. 2. **Decide filename and date.** Use `YYYY-MM-DD-slug.gmi.tpl` for the template file. Ask for the publish date and slug if the user doesn't specify them. -3. **Structure the post** in this order: - - `# Title` (first line) - - `> Published at YYYY-MM-DDTHH:MM:SS+02:00` (ISO 8601 with timezone) - - Optional: ASCII art in a fenced code block (triple backticks). Suggest only if it fits the topic (e.g. diagram, device, logo). - - Short intro paragraph(s) - - First image (if any) and/or main product/external links - - **Table of Contents** (see below) - - Body with `##` and `###` sections - - Optional: "Other related posts:" with `=> ./YYYY-MM-DD-slug.gmi YYYY-MM-DD Title` lines - - `E-Mail your comments to \`paul@nospam.buetow.org\` :-)` - - `=> ../ Back to the main site` (last line) +3. **Author the content following the foo.zone gemtext conventions.** All format/structure rules live in the shared [`blog-writing-style` gemtext conventions](../blog-writing-style/references/gemtext-conventions.md) — follow them for: post structure & order (`# Title`, `> Published at …`, intro, TOC, body, related posts, E-Mail line, back-to-main-site), Table of Contents (`⇢` arrows by section level), links (inline project links after the mentioning paragraph), images & ASCII diagrams (web resize, Unicode box-drawing, fixed-column `│` divider with an `awk` alignment check), multi-part series (cross-links, shared hero, `DRAFT-…` handling, dated-filename ordering), and format constraints (no Markdown bold/italic; `##`/`###` only; no HTML). -4. **Table of Contents.** Add a hand-written TOC after the intro/first image, before the first `##`: - - Heading: `## Table of Contents` then a blank line - - List with `* ⇢` and indentation by section level: - - `* ⇢ Post title` (one arrow = document title) - - `* ⇢ ⇢ Section name` (two arrows = each `##` section) - - `* ⇢ ⇢ ⇢ Subsection name` (three arrows = each `###` subsection) - - List every `##` and `###` in the same order as in the body. +4. **Ask when unclear.** If the topic, date, slug, or need for ASCII art / images / related posts is missing, ask the user before writing. -5. **Images and diagrams.** - - Store images in a subfolder under the gemfeed (e.g. `gemfeed/slug-name/` or a name the user gives). Reference them as `=> ./slug-name/filename.jpg Description`. - - If the user provides or points to large image files (e.g. multi‑MB or very high resolution), suggest or perform resizing for web (e.g. longest side 1200px, JPEG quality 85) so the post stays fast to load. - - **Image density.** Prose-heavy posts with long `##` sections benefit from at least one image or diagram per major section. Walls of text without visual anchors feel dense; when a section runs to several screens of prose, propose a diagram or screenshot to break it up. - - **ASCII diagrams.** Use a fenced code block (triple backticks). Use Unicode box-drawing characters — `─`, `│`, `▼`, `▶`, `┼`, `┌`, `└`, `┐`, `┘` — for cleaner output than `|` / `-` / `+`. - - For two-section comparison diagrams (e.g. kernel vs userspace, before vs after, mode A vs B), place a vertical `│` divider at a single fixed column on every row, rather than relying on whitespace alone to separate the sides. Without a divider, the header label drifts away from the content underneath it. - - After drafting a multi-column diagram, verify the divider column is identical on every line (e.g. with a small `awk` check) before accepting it. Misaligned dividers are the most common rendering bug. - - Anchor labels above content: each section header should sit visually over the column it describes, not floating off to one side. - -6. **Links.** Use gemtext link lines: `=> URL Description` for external links, `=> ./path Description` for internal/images. Include product or reference links when the post mentions specific items. - - **Inline project links.** When the body first mentions an external tool, project, or library by name (e.g. eBPF, libbpf, ClickHouse), add a `=> URL Description` line immediately after that paragraph rather than waiting for a bottom-of-post link block. Bottom blocks are reserved for source repos and related posts. - -7. **Gemtext conventions.** - - Sections: `##` and `###` (no `#` except the title). - - Code blocks: triple backticks; list blocks with `*` or `-`. - - No HTML; plain gemtext only. - -8. **Ask when unclear.** If the topic, date, slug, or need for ASCII art / images / related posts is missing, ask the user before writing. - -9. **Add to index.** After saving the post template, add one line at the top of `~/git/foo.zone-content/gemtext/gemfeed/index.gmi.tpl` only (do not edit `index.gmi`): +5. **Add to index.** After saving the post template, add one line at the top of `~/git/foo.zone-content/gemtext/gemfeed/index.gmi.tpl` only (do not edit `index.gmi`): `=> ./YYYY-MM-DD-slug.gmi YYYY-MM-DD - Post title` -10. **Preview and confirm.** Show a short preview (e.g. title, TOC, and first section) before writing the file. After saving, confirm that only `.gmi.tpl` files were created or modified (post template and index template) and that no `.gmi` files were changed. - -11. **Optional publish.** If the user wants the new post published after it is written, use the `gemtexter` skill to run the publish workflow and verify the live page on `https://foo.zone`. +6. **Preview and confirm.** Show a short preview (e.g. title, TOC, and first section) before writing the file. After saving, confirm that only `.gmi.tpl` files were created or modified (post template and index template) and that no `.gmi` files were changed. -12. **Apply human writing style.** Use the `blog-writing-style` skill to ensure the content sounds authentically human — casual, personal, without corporate/marketing language or LLM-generated patterns. +7. **Optional publish.** If the user wants the new post published after it is written, use the `gemtexter` skill to run the publish workflow and verify the live page on `https://foo.zone`. -13. **Multi-part series.** When a post is part of a series (Part 1 / Part 2 / Part 3 …): - - Cross-link to siblings near the top (right after the intro paragraph) and again at the bottom, using the dated filename: `=> ./YYYY-MM-DD-slug-part-N.gmi Part N: short subtitle`. - - **Shared hero image.** Use the same hero image at the same position (typically immediately after the intro) in every part. Store hero and other shared assets in one subfolder, e.g. `gemfeed/series-slug/`. - - **Drafts.** Unpublished parts can live as `DRAFT-slug-part-N.gmi.tpl`; their cross-references use `=> ./DRAFT-slug-part-N.gmi`. Promoting a draft to a dated post requires (a) renaming the `.gmi.tpl` and removing the stale generated `.gmi`, then (b) updating every `=> ./DRAFT-…` or `=> ./old-date-…` reference in every OTHER `.gmi.tpl` in the series to point at the new filename. Search with `grep -rn "old-filename" gemtext/` to catch them all. - - The dated filename controls gemfeed ordering. Fix the filename first, then propagate to references — never the other way around. +8. **Apply human writing style.** Use the `blog-writing-style` skill to ensure the content sounds authentically human — casual, personal, without corporate/marketing language or LLM-generated patterns. \ No newline at end of file diff --git a/prompts/skills/go-best-practices/SKILL.md b/prompts/skills/go-best-practices/SKILL.md index c03e91d..a81c231 100644 --- a/prompts/skills/go-best-practices/SKILL.md +++ b/prompts/skills/go-best-practices/SKILL.md @@ -73,22 +73,24 @@ When writing or modifying Go code (especially with an AI agent), run static-anal * **errcheck:** Run `errcheck ./...` to catch silently ignored errors—one of the most common Go bugs. Treat findings as defects: check the error (wrap with `%w`) or discard it explicitly with `_ =`. Do not silence it by deleting the check. See `references/errcheck.md` for install instructions, flags, exclude files, and how to wire it into the Magefile / CI / pre-commit hooks. * Be honest about what actually ran: if errcheck (or any tool) is not installed or could not run, say so rather than implying the code was checked. -### Environment preflight and verification honesty - -Before claiming any verification, confirm the local toolchain can actually build and run the relevant tests. A *missing or incomplete* toolchain (not slow tests) is common: e.g. CGO headers absent (`bpf/bpf.h` for eBPF code), or external tools not installed (`flutter`/`dart` for a companion app). - -* **Preflight first:** Verify the build/test path works before trusting it—run `go build ./...`, confirm required CGO headers are present, and confirm required external tools are on `PATH`. If preflight fails, do not claim the project builds. -* **Run the smallest verifying subset that DOES work:** When part of the toolchain is missing, still verify what you can—`go vet ./...`, `gofmt -l .`, `go build` on the packages that do not need the missing headers, and the unit tests that do not require the missing tool. Use build tags or explicit package paths to skip the unbuildable parts. -* **Annotate the blocker explicitly:** Record what is missing and the impact with `ask annotate ""`—name the missing header/tool, what you verified, and what you could not. -* **Never claim full verification when it did not run:** State precisely what was and was not verified (e.g. "vet + gofmt clean; `./internal/bpf` not built—`bpf/bpf.h` missing; eBPF tests not run"). Do not imply a green build or passing tests that never executed. - -### Long-running / timeout-exceeding test suites - -Distinct from a *missing* toolchain (see "Environment preflight and verification honesty"): here the toolchain works, but the full suite is too SLOW to finish within the go-test / mage / command timeout (e.g. `mage integrationTest` runs > 30m). Run a focused subset rather than nothing, and be explicit that you did so. - -* **Run a representative subset within the timeout:** Scope to the package(s) the change touches and skip the slow target—e.g. `go test ./internal/foo/... -run -short`. Prefer `-short` (have slow tests honor `testing.Short()`), build tags, or `-run` to exclude expensive integration/E2E tests; run the unit subset when the full integration suite can't complete. -* **Annotate the intentional skip:** Record with `ask annotate ""` that the full suite was *intentionally* skipped, why (exceeds timeout, not a failure), which subset ran, and the result—e.g. "integrationTest skipped (>30m, timeout); ran `go test ./internal/foo/... -short` → pass". -* **Acceptance implications:** A focused subset is NOT full verification. Be explicit about residual risk—untested integration paths, packages not touched—so the reviewer/orchestrator can decide whether to accept or run the full suite out-of-band. As in 8q0, never imply the full suite passed when it never ran. +### Verification honesty (Go specifics) + +The general discipline — preflight the toolchain, run the smallest verifying +subset that works, annotate blockers with `ask annotate`, never claim full +verification that did not run, and the long-running-suite subset rule — lives in +the [`agent-task-management` skill](../agent-task-management/references/verification-honesty.md). +Follow it for any Go verification. The Go-specific concrete actions: + +* **Preflight:** `go build ./...`; confirm CGO headers are present (e.g. + `bpf/bpf.h` for eBPF code) and external tools are on `PATH` (e.g. + `flutter`/`dart` for a companion app). +* **Smallest verifying subset when part of the toolchain is missing:** + `go vet ./...`, `gofmt -l .`, `go build` on the packages that do not need the + missing headers, and the unit tests that do not require the missing tool. + Use build tags or explicit package paths to skip the unbuildable parts. +* **Slow suite within timeout:** `go test ./internal/foo/... -run + -short`. Prefer `-short` (have slow tests honor `testing.Short()`), build + tags, or `-run` to exclude expensive integration/E2E tests. ### Build system diff --git a/prompts/skills/rocky-vm-setup/SKILL.md b/prompts/skills/rocky-vm-setup/SKILL.md index f21061a..dfa5c57 100644 --- a/prompts/skills/rocky-vm-setup/SKILL.md +++ b/prompts/skills/rocky-vm-setup/SKILL.md @@ -7,254 +7,33 @@ description: Reference for the plain Rocky Linux 9 bhyve VM (host `rocky`, 192.1 The `rocky` VM is a plain Rocky Linux 9 bhyve guest on **f3** (LAN IP `192.168.1.123`, WireGuard `192.168.2.123`). It is **not** part of the k3s cluster and serves as a general-purpose build / dev / git client VM. -Parent infrastructure: see the [`f3s`](skills/f3s) skill (f3 host, zrepl, bhyve, git server). +Parent infrastructure: see the [`f3s`](../f3s/SKILL.md) skill (f3 host, zrepl, bhyve, git server). ---- - -## SSH Keys - -| Key | Path | Purpose | -|-----|------|---------| -| Root VM key | `/root/.ssh/id_ed25519` | Git server SSH auth | -| Paul VM key | `/home/paul/.ssh/id_ed25519` | Git server SSH auth, local remotes | - -The public keys are added to the k3s `git-server-authorized-keys` secret (namespace `cicd`) so both `root` and `paul` can push/pull via `git@r{N}:30022`. - -```sh -# Regenerate if needed -ssh-keygen -t ed25519 -N '' -f /root/.ssh/id_ed25519 -C 'root@rocky.f3s.lan.buetow.org' -``` - ---- - -## /etc/hosts - -Short LAN aliases for all f3s hosts (short, `.lan`, and `.lan.buetow.org` variants): - -``` -# f3s k3s node LAN aliases -192.168.1.120 r0 r0.lan r0.lan.buetow.org -192.168.1.121 r1 r1.lan r1.lan.buetow.org -192.168.1.122 r2 r2.lan r2.lan.buetow.org - -# f3s FreeBSD host LAN aliases -192.168.1.130 f0 f0.lan f0.lan.buetow.org -192.168.1.131 f1 f1.lan f1.lan.buetow.org -192.168.1.132 f2 f2.lan f2.lan.buetow.org -192.168.1.133 f3 f3.lan f3.lan.buetow.org - -# f3s Raspberry Pi LAN aliases -192.168.1.125 pi0 pi0.lan pi0.lan.buetow.org -192.168.1.126 pi1 pi1.lan pi1.lan.buetow.org -192.168.1.127 pi2 pi2.lan pi2.lan.buetow.org -192.168.1.128 pi3 pi3.lan pi3.lan.buetow.org -``` - ---- - -## Installed Tools - -| Tool | Version | How Installed | -|------|---------|---------------| -| tmux | 3.2a | `dnf install -y tmux` | -| tmux prefix | C-g | **Rocky override** — nested tmux (see below) | -| fish | 3.7.1 | `dnf install -y fish` (EPEL) | -| helix | 25.07.1 | `dnf install -y helix helix-themes` (EPEL) | -| amp | 0.7.1 | Downloaded binary from GitHub releases | -| claude-code | 2.1.169 | `npm install -g @anthropic-ai/claude-code` | -| pi coding agent | 0.79.0 | `npm install -g @earendil-works/pi-coding-agent` | -| taskwarrior | 2.6.2 | **Built from source** (see below) | -| Rex | 1.16.1 | `cpanm Rex` (requires expat-devel, perl-LWP-Protocol-https) | -| zoxide | 0.9.8 | `dnf install -y zoxide` (EPEL) | -| fzf | 0.58.0 | `dnf install -y fzf` (EPEL) | -| fzf fish plugin | — | **fisher install PatrickF1/fzf.fish** | -| ask, hexai*, gt, gitsyncer, etc. | — | `go install codeberg.org/snonux/...` (see update::tools) | - -### Nested tmux (C-g on rocky) - -Earth (outer tmux) uses the default **C-b** prefix. Rocky (inner tmux) uses **C-g** so you can control both layers. - -**Visual distinction — you'll never confuse the two:** - -| Layer | Prefix | Active Border | Status Bar | Pane Indicators | TERM | -|-------|--------|---------------|------------|-----------------|------| -| **Earth (outer)** | `C-b` | **Magenta** | White-on-purple | Default blue | `tmux-256color` | -| **Rocky (inner)** | `C-g` | **Bright Red** | **Black-on-orange** with `[ROCKY]` label | **Red/orange** pane numbers, border labels | `tmux-256color` | - -**Workflow:** -| Key | Action | -|-----|--------| -| `C-b c` | Create window in outer tmux (earth) | -| `C-g c` | Create window in inner tmux (rocky) | -| `C-b b` | Send `C-b` through to inner tmux | -| `C-g g` | Send `C-g` through to inner-inner tmux | - -Rocky config is in `~/.config/tmux/tmux.rocky.conf` and sourced from `tmux.local.conf`: - -```sh -# ~/.config/tmux/tmux.rocky.conf -unbind C-b -set -g prefix C-g -bind C-g send-prefix - -# Drastic RED/ORANGE color scheme -set -g pane-active-border-style 'fg=brightred,bold' -set -g status-style 'bg=colour208,fg=black,bold' -set -g status-left ' [ROCKY] #[bg=brightred,fg=white] #S ' -set -g window-status-current-style 'bg=brightred,fg=white,bold' -set -g window-status-style 'bg=colour208,fg=black' - -# Active pane indicators -set -g display-panes-colour colour208 # prefix+q pane numbers -set -g display-panes-active-colour brightred # active pane number -set -g pane-border-status top # show pane info on borders -set -g pane-border-format '#[fg=colour208] #{pane_index} #[fg=brightred]#{pane_title} ' -set -g window-status-current-format ' #I*#[bg=brightred,fg=white] #W ' - -# TERM inside tmux — must advertise 256 colors so helix/fzf/etc work -set -g default-terminal 'tmux-256color' -set -ga terminal-overrides ',xterm-256color:Tc,*-256color:Tc' - -# Pass COLORTERM through from outer SSH session so helix knows truecolor is available -set -g update-environment 'DISPLAY SSH_ASKPASS SSH_AGENT_LAUNCHER SSH_AUTH_SOCK SSH_CONNECTION SSH_TTY WINDOWID XAUTHORITY TERM COLORTERM' -``` - -This is deployed by the `home_tmux_rocky` Rex task (runs only when `hostname =~ /rocky/`). - -### Building taskwarrior from source - -Rocky 9 does not ship `task`/`taskwarrior`. v3.x requires Rust; v2.6.2 compiles cleanly. - -```sh -# deps -dnf install -y cmake gcc-c++ make libuuid-devel gnutls-devel libssh2-devel - -# build -git clone --depth 1 --branch v2.6.2 \ - https://github.com/GothenburgBitFactory/taskwarrior.git /tmp/tw-build -cd /tmp/tw-build -cmake -S . -B build -DCMAKE_BUILD_TYPE=Release -cmake --build build -j$(nproc) -cmake --install build - -# verify -/usr/local/bin/task --version # 2.6.2 -``` - -### First-run fish setup +## When to Use -After the dotfiles `home` task deploys fish config, some plugins and binaries are expected but not yet present: +- Working on or replicating the `rocky` VM configuration +- SSH keys, git remotes, installed tooling, tmux/fish first-run setup +- User privileges and sudoers, Rex deployment, zrepl replication -```sh -# 1. Install fisher (fish plugin manager) -curl -sL https://raw.githubusercontent.com/jorgebucaran/fisher/main/functions/fisher.fish | source -fisher install jorgebucaran/fisher +## Reference Files -# 2. Install the fzf.fish plugin (provides fzf_configure_bindings) -fisher install PatrickF1/fzf.fish +Detailed reference documentation is in the `references/` subfolder — load the one that matches the task: -# 3. First-run taskwarrior creates ~/.taskrc -yes | task >/dev/null 2>&1 - -# 4. Install Go tooling binaries (run as paul) -for prog in ask hexai hexai-lsp-server hexai-tmux-action hexai-tmux-edit hexai-mcp-server; do - go install codeberg.org/snonux/hexai/cmd/$prog@latest -done -for prog in tasksamurai timesamurai gt; do - go install codeberg.org/snonux/$prog/cmd/$prog@latest -done -for prog in gitsyncer gos snonux; do - go install codeberg.org/snonux/$prog/cmd/$prog@latest -done -# (foostore, loadbars, totalrecall, goprecords may need X11/GL deps for GUI — skip on headless) -``` - -**tmux 3.2a compatibility note:** The dotfiles `tmux.conf` includes `set -g extended-keys-format csi-u` (tmux 3.3+). On rocky this line is automatically stripped by the `home_tmux_rocky` Rex task. If you deploy manually, remove or comment out that line. - ---- - -## User and Privileges - -**`root`** — full root, used for package installs and Rex tasks. - -**`paul`** -- **Removed from `wheel`** group. No general `sudo` access. -- **Only** allowed to run without password: - ``` - /home/paul/scripts/update-coding-agents - ``` -- Home: `/home/paul` -- Git repos: `~/git/` (cloned via local `r0`/`r1`/`r2` remotes) - ---- - -## Git Remotes - -All repos available on the local git server have `r0`, `r1`, `r2` remotes replacing any codeberg ones: - -``` -url = ssh://git@r0:30022/repos/REPO.git -url = ssh://git@r1:30022/repos/REPO.git -url = ssh://git@r2:30022/repos/REPO.git -``` - -Repos pushed: conf, dotfiles, gemtexter, gitsyncer, goprecords, gt, hexai, hypr, ior, photoalbum, rcm, snonux, tasksamurai, wireguardmeshgenerator - ---- - -## Scripts - -`/home/paul/scripts/update-coding-agents` -```sh -#!/bin/sh -set -e -if [ "$(id -u)" -ne 0 ]; then - exec sudo "$0" "$@" -fi -echo "Updating Claude Code..." -npm update -g @anthropic-ai/claude-code @anthropic-ai/claude-code-linux-x64 -echo "Updating pi coding agent..." -npm update -g @earendil-works/pi-coding-agent -echo "All coding agents updated." -``` - -Run as paul: `$ /home/paul/scripts/update-coding-agents` - ---- - -## Rex Usage - -The dotfiles repo (`~/git/dotfiles`) contains the main `Rexfile`. - -```sh -# Install packages (as root) -rex pkg_rocky - -# Deploy dotfiles (as paul) -rex home -``` - -`pkg_rocky` uses Rex's `pkg` directive which requires root — no `sudo` wrappers. - ---- - -## ZFS Snapshot / Replication - -The rocky VM dataset `zroot/bhyve/rocky` is managed by **zrepl** on the FreeBSD host f3. It is **not** included in local `zfs-periodic` snapshots. - -| Property | Value | -|------------|-------| -| Snapshots | Every 10 minutes via zrepl (`zrepl_` prefix) | -| Replication | f3 → f2 (`zroot/sink/f3/zroot/bhyve/rocky`) | -| Retention | 10 immediate + 24 hourly + 14 daily | -| Local snap job | `zroot/bhyve/rocky` excluded from `local_zfs_snapshots` | - -See [`f3s` skill zrepl.md](skills/f3s/references/storage/zrepl.md) for full config. - ---- +- [Overview](references/overview.md) — VM role, SSH keys, `/etc/hosts` LAN aliases for all f3s hosts +- [Installed Tools](references/tools.md) — tool/version/install table, building taskwarrior 2.6.2 from source, first-run fish + fisher + Go tooling setup, tmux 3.2a compatibility note +- [Nested tmux](references/tmux.md) — `C-g` prefix on rocky vs `C-b` on earth, red/orange color scheme, source ordering, 256-color and truecolor (`COLORTERM`) passthrough +- [Git Remotes](references/git-remotes.md) — `r0`/`r1`/`r2` remotes replacing codeberg, `git@r{N}:30022`, repos pushed, authorized-keys secret +- [User and Privileges](references/privileges.md) — `root` full access; `paul` removed from `wheel`, NOPASSWD only for `update-coding-agents`, sudoers config +- [Scripts](references/scripts.md) — `/home/paul/scripts/update-coding-agents` (updates claude-code + pi) +- [Rex Usage](references/rex.md) — `rex pkg_rocky` (root) / `rex home` (paul), Rocky-specific `home_tmux_rocky` task +- [ZFS Snapshot / Replication](references/zrepl.md) — `zroot/bhyve/rocky` via zrepl on f3 → f2, retention; full config in `f3s` skill +- [Notes](references/notes.md) — `claude` wrapper must be a symlink not a shell script (fork bomb), Node.js 22 module, `amp` non-TTY panic -## Notes +## Quick Reference -- The `claude` wrapper must **not** be a shell script calling the JS wrapper — that caused a fork bomb because `cli-wrapper.cjs` tried to exec the `claude` binary but found the script instead. Use a direct symlink or the npm-installed binary. -- Node.js v20 is installed via `dnf module install nodejs:20/common`. -- `amp` panics in non-TTY environments — that's expected for a TUI editor. +- Host: `rocky` / `192.168.1.123` (LAN), `192.168.2.123` (WireGuard) +- Parent: f3 (see `f3s` skill) +- Git remotes: `ssh://git@r0:30022/repos/REPO.git` (and r1, r2) +- tmux prefix: `C-g` (rocky inner) over `C-b` (earth outer) +- paul sudo: only `/home/paul/scripts/update-coding-agents` +- Replication: zrepl f3 → f2, every 10 min \ No newline at end of file diff --git a/prompts/skills/update-blog-post/SKILL.md b/prompts/skills/update-blog-post/SKILL.md index f9198ca..a573acc 100644 --- a/prompts/skills/update-blog-post/SKILL.md +++ b/prompts/skills/update-blog-post/SKILL.md @@ -16,7 +16,7 @@ Update an existing blog post in ~/git/foo.zone-content/gemtext/gemfeed/ in the g 1. Identify the blog post file in `~/git/foo.zone-content/gemtext/gemfeed/` matching the name or slug given by the user. If multiple matches exist, ask which one. 2. Read the matched `.gmi.tpl` file to understand its current content. 3. If the user hasn't specified what to update, ask what changes should be made. -4. Apply the requested changes while preserving the existing gemtext style and structure. Also add an updated note before the new or modified text like this "> Updated Tue 27 Jan: Added SECTION about SHORT DESCRIPTION here" +4. Apply the requested changes while preserving the existing gemtext style and structure. Follow the shared foo.zone conventions in [`blog-writing-style/references/gemtext-conventions.md`](../blog-writing-style/references/gemtext-conventions.md) (post structure, TOC `⇢` format, links, images/diagrams, format constraints like no Markdown bold/italic). Also add an updated note before the new or modified text like this "> Updated Tue 27 Jan: Added SECTION about SHORT DESCRIPTION here" 5. Also add an "last updated" note to the blog post's publishing date, format like this "> Published at 2025-07-13T16:44:29+03:00, last updated Tue 27 Jan 10:09:08 EET 2026" 6. Show a diff or summary of the changes before writing. 7. After writing, commit and push the changes to git. -- cgit v1.2.3