@e4779/skills 0.0.0-stage → 0.1.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/chrome-devtools/README.md +76 -0
- package/chrome-devtools/SKILL.md +277 -0
- package/chrome-devtools/references/recipes.md +379 -0
- package/chrome-devtools/references/setup.md +138 -0
- package/drawio/SKILL.md +395 -0
- package/gh-cli/SKILL.md +83 -0
- package/grill/SKILL.md +72 -0
- package/layout-check/README.md +32 -0
- package/layout-check/SKILL.md +416 -0
- package/layout-check/scripts/layoutProbe.mjs +539 -0
- package/mcpls/SKILL.md +261 -0
- package/mcpls/references/configuration.md +131 -0
- package/mcpls/references/install.md +13 -0
- package/mcporter/SKILL.md +90 -0
- package/mindmap/SKILL.md +46 -0
- package/mindmap/references/drawio-recipe.md +60 -0
- package/mindmap/references/mindmap-design.md +63 -0
- package/opensource-contribution/SKILL.md +119 -0
- package/package.json +29 -5
- package/shell-taste/.shellcheckrc +16 -0
- package/shell-taste/SKILL.md +95 -0
- package/shell-taste/references/handbook/dialects.md +168 -0
- package/shell-taste/references/handbook/dom/01-output-logging.md +245 -0
- package/shell-taste/references/handbook/dom/02-errors-exit.md +48 -0
- package/shell-taste/references/handbook/dom/03-installation-setup.md +179 -0
- package/shell-taste/references/handbook/dom/04-network.md +384 -0
- package/shell-taste/references/handbook/dom/05-files-paths.md +74 -0
- package/shell-taste/references/handbook/dom/06-checks-validation.md +127 -0
- package/shell-taste/references/handbook/dom/07-system-administration.md +103 -0
- package/shell-taste/references/handbook/dom/08-privilege-users.md +58 -0
- package/shell-taste/references/handbook/dom/09-text-data.md +62 -0
- package/shell-taste/references/handbook/dom/10-terminal-ux.md +60 -0
- package/shell-taste/references/handbook/dom/11-process-control.md +28 -0
- package/shell-taste/references/handbook/dom/12-uncategorized.md +161 -0
- package/shell-taste/references/handbook/dom/13-containers.md +13 -0
- package/shell-taste/references/handbook/dom/14-agents-ai-tooling.md +13 -0
- package/shell-taste/references/handbook/family-index.md +230 -0
- package/shell-taste/references/handbook/index.md +41 -0
- package/skill-author/SKILL.md +86 -0
- package/sobesednik/SKILL.md +98 -0
- package/sobesednik/card-template.md +23 -0
- package/sobesednik/personas/advocate.md +27 -0
- package/sobesednik/personas/analyst.md +29 -0
- package/sobesednik/personas/chat.md +42 -0
- package/sobesednik/personas/ifs.md +32 -0
- package/sobesednik/personas/journal/README.md +6 -0
- package/sobesednik/personas/nasreddin.md +29 -0
- package/sobesednik/personas/premortem.md +29 -0
- package/sobesednik/personas/rogers.md +27 -0
- package/sobesednik/personas/socratic.md +29 -0
- package/sobesednik/personas/stoic.md +27 -0
- package/sobesednik/references/persona-design.md +41 -0
- package/zai-mcp/README.md +63 -0
- package/zai-mcp/SKILL.md +160 -0
- package/zai-mcp/references/recipes.md +273 -0
- package/zai-mcp/references/tools.md +266 -0
- package/README.md +0 -3
|
@@ -0,0 +1,63 @@
|
|
|
1
|
+
# Mindmap design — theory into drawio practice
|
|
2
|
+
|
|
3
|
+
## Buzan's laws (1974, "Mind Map Mastery") — digital adaptation
|
|
4
|
+
|
|
5
|
+
1. **Central image** — the idea in the middle, bigger than everything. In
|
|
6
|
+
drawio: the ellipse center node, 1.5–2x the size of branch nodes.
|
|
7
|
+
2. **Images/symbols** — hand-drawn pictures become shapes/icons; use
|
|
8
|
+
sparingly (one per major branch at most, else noise).
|
|
9
|
+
3. **Color** — one color per first-level branch. Clusters become scannable;
|
|
10
|
+
recall improves. Apply fillColor per branch subtree.
|
|
11
|
+
4. **Curved organic branches, thick to thin** — in drawio:
|
|
12
|
+
entityRelationEdgeStyle + curved=1, no arrows; emulate taper by
|
|
13
|
+
strokeWidth 2 on level-1 edges, 1 deeper.
|
|
14
|
+
5. **One keyword per line** — a node holds 1-3 words, never a sentence.
|
|
15
|
+
Compression forces precise naming; sentences hide their atoms.
|
|
16
|
+
6. **Each idea gets its own branch** — if you write "X and Y" in one node,
|
|
17
|
+
that is two nodes. Splitting is the thinking.
|
|
18
|
+
7. **Hierarchy — Basic Ordering Ideas (BOI)** — first level = 5±2 "chapter"
|
|
19
|
+
branches. This is the working-memory budget (Miller 7±2).
|
|
20
|
+
8. **Radiant structure** — association radiates outward from the center.
|
|
21
|
+
9. **Personal style** — idiosyncratic phrasing aids memory; do not sanitize
|
|
22
|
+
the user's words.
|
|
23
|
+
10. **Redraw/revise** — redrawing consolidates understanding. Cheap here:
|
|
24
|
+
re-render after rounds; it is the built-in review.
|
|
25
|
+
|
|
26
|
+
## Layout patterns — when to use which
|
|
27
|
+
|
|
28
|
+
| Layout | Shape | Best for |
|
|
29
|
+
|---|---|---|
|
|
30
|
+
| Radial "sun" | center + fan in all directions | exploration, brainstorm, balanced association; structure still being discovered |
|
|
31
|
+
| Right-flowing logic tree ("grape bunch") | root at left, chains to the right | reading order, execution plans, argument chains, documentation |
|
|
32
|
+
| Bottom-up tree | conclusion at top, reasons below | argument/justification maps |
|
|
33
|
+
|
|
34
|
+
Both sun and grape bunch are legitimate — they answer different questions
|
|
35
|
+
(sun: "what is related?"; tree: "what follows from what?"). Do not mix
|
|
36
|
+
directions within one level. A hybrid is fine when quadrants stay coherent.
|
|
37
|
+
|
|
38
|
+
## Sub-topic vs branching (terminology)
|
|
39
|
+
|
|
40
|
+
- **Main branches** = the BOI level: 5±2 top areas, the "chapters" of the map.
|
|
41
|
+
- **Branching** = the act of splitting: one idea per branch. If a node reads
|
|
42
|
+
"X and Y", it is two nodes — the split forces you to name each precisely.
|
|
43
|
+
- **Sub-topic** = any node below level 1. Depth budget: max 4 levels; deeper
|
|
44
|
+
→ regroup or spin a sub-map (a drawio page or separate file).
|
|
45
|
+
|
|
46
|
+
## Cognitive constraints (why the rules exist)
|
|
47
|
+
|
|
48
|
+
- Working memory = 7±2 chunks → first-level fan max 9.
|
|
49
|
+
- Keyword compression = forced encoding: naming an atom beats paraphrasing.
|
|
50
|
+
- Color clustering aids recall and rapid scanning.
|
|
51
|
+
- Semantic adjacency: related branches sit adjacent; crossing edges are a
|
|
52
|
+
layout smell, not a style choice.
|
|
53
|
+
|
|
54
|
+
## drawio-specific tips
|
|
55
|
+
|
|
56
|
+
- Template styles: ellipse center; rounded=1;arcSize=50 topics;
|
|
57
|
+
partialRectangle leaves (bottom-line only); entityRelationEdgeStyle
|
|
58
|
+
curved edges without arrows.
|
|
59
|
+
- Generate via drawio MCP (get_page → modify → set_page); geometry attribute
|
|
60
|
+
must be as="geometry".
|
|
61
|
+
- Export PNG at -s 2 and review with a vision model: overlaps, truncation,
|
|
62
|
+
edges-through-nodes. Fix coordinates, re-export. One or two iterations
|
|
63
|
+
usually suffice.
|
|
@@ -0,0 +1,119 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: opensource-contribution
|
|
3
|
+
description: "Writing upstream messages that maintainers actually read: bug reports, PR/MR descriptions, issue comments, mailing-list posts. Anti-AI-slop rules, evidence discipline, structure templates, scale-to-change and style-audit checklists, follow-up etiquette. Not for internal QA defect documentation or tracker automation; MusicBrainz contributions live in musicbrainz-contribute. Использовать, когда готовим сообщение в опенсорс: багрепорт, написать в апстрим, PR description, письмо мейнтейнеру или в рассылку, контрибьюция."
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
# opensource-contribution — upstream messages without the slop
|
|
7
|
+
|
|
8
|
+
You are writing to a busy maintainer who owes you nothing and reads at
|
|
9
|
+
skimming speed. Every sentence must earn its place. The contribution IS the
|
|
10
|
+
evidence, curated — what you filtered out is half the gift.
|
|
11
|
+
|
|
12
|
+
## Before writing (non-negotiable)
|
|
13
|
+
|
|
14
|
+
1. **Dedup**: search THEIR tracker + the web for the symptom. Cite near-misses
|
|
15
|
+
in the report ("related but distinct: #NNN — why"). A duplicate report with
|
|
16
|
+
good analysis is still welcome; a duplicate with none is slop.
|
|
17
|
+
2. **Read their rules**: CONTRIBUTING.md, issue templates, submission article
|
|
18
|
+
(e.g. FreeBSD's "Writing Problem Reports"). Use THEIR fields and title
|
|
19
|
+
style, not your own scheme.
|
|
20
|
+
3. **Calibrate to the room**: open 3 recent merged PRs / resolved issues.
|
|
21
|
+
Copy their format, length, and register. A kernel-list mail differs from a
|
|
22
|
+
GitHub issue; both differ from a GitLab MR to a small Wayland project.
|
|
23
|
+
|
|
24
|
+
## Scale to the change
|
|
25
|
+
|
|
26
|
+
- **One-line fix** → minimal report: repro, diff, why. Resist padding.
|
|
27
|
+
- **Significant change** → scope consult FIRST: comment on the existing issue
|
|
28
|
+
/ IRC / list with the design sketch BEFORE the big PR. The issue thread is
|
|
29
|
+
your anchor; reference it everywhere.
|
|
30
|
+
- **Multi-part work** → offer a reviewable series ("core → feature → tests"),
|
|
31
|
+
not a 13-commit blob. Ask maintainers which split they prefer.
|
|
32
|
+
- **Style-audit before PR**: check their code style rules and apply them to
|
|
33
|
+
YOUR code — naming prefixes, allocator APIs, brace style, column limit,
|
|
34
|
+
C standard, no-GNU-extensions. Rename your darlings to their conventions
|
|
35
|
+
(an enum that misses their prefix is a review-speed bump).
|
|
36
|
+
- **A reproducible demo/test harness is the strongest evidence** a report can
|
|
37
|
+
carry. If you built one, lead with it.
|
|
38
|
+
|
|
39
|
+
## Structure templates
|
|
40
|
+
|
|
41
|
+
**Bug report** — Title: `component: observed behavior` (one line, no drama).
|
|
42
|
+
Then: Environment (exact versions, hw) → Reproduction (deterministic commands,
|
|
43
|
+
not prose) → Observed (evidence excerpts) → Expected (spec/doc citation) →
|
|
44
|
+
Analysis (what you ruled out, with file:line refs) → Suggested direction.
|
|
45
|
+
|
|
46
|
+
**PR/MR** — Problem (why, link the issue) → Fix (what, minimal, why this
|
|
47
|
+
approach) → Testing (exact commands + observed results) → Notes for review
|
|
48
|
+
(risks, rejected alternatives).
|
|
49
|
+
|
|
50
|
+
**Mailing list** — one context paragraph, facts, then the ask. Short.
|
|
51
|
+
Subject line states the conclusion, not the journey.
|
|
52
|
+
|
|
53
|
+
## Anti-slop rules (the heart of this skill)
|
|
54
|
+
|
|
55
|
+
| Never | Instead |
|
|
56
|
+
|---|---|
|
|
57
|
+
| "Hi team!", "Hope you're doing well", "Thanks in advance!" | Start at the first fact |
|
|
58
|
+
| "delve", "leverage", "comprehensive", "seamless", "robust" | plain verbs: read, use, full, exact |
|
|
59
|
+
| "It's worth noting that", "Interestingly", "Notably" | delete the throat-clearing, keep the fact |
|
|
60
|
+
| "Moreover/Additionally" chains | cut, or renumber real lists |
|
|
61
|
+
| hedging everything ("might", "perhaps", "I believe") | commit to verified claims; mark the rest "unverified" |
|
|
62
|
+
| bullet-point-everything | prose for reasoning, lists for artifacts |
|
|
63
|
+
| restating the report in a closing summary | end at the last fact |
|
|
64
|
+
| apologetic opener about being new/possibly wrong | one honest scope note, if needed |
|
|
65
|
+
| "!" energy, emojis, bold-spam | flat declarative tone; bold for 2-3 real anchors max |
|
|
66
|
+
| pleasing tone: "happy to", "I'd love to", "буду рад", "feel free to", "let me know if you need" | end at the last fact — the work itself is the offer |
|
|
67
|
+
| pasted raw logs (500+ lines) | the 10 lines that matter + "full log attached" |
|
|
68
|
+
|
|
69
|
+
Absolute bans: invented line numbers, versions, quotes, benchmark numbers.
|
|
70
|
+
Every number reproducible by the reader from your repro steps. If an LLM
|
|
71
|
+
generated any part you could not verify, verify it or cut it — this is the
|
|
72
|
+
exact failure mode that got AI reports mass-banned (curl, 2025-2026).
|
|
73
|
+
|
|
74
|
+
## Evidence discipline
|
|
75
|
+
|
|
76
|
+
- file:line with repo paths, commit hashes, counter deltas
|
|
77
|
+
("+22 EXCHANGE_ID per 30s"), before/after behavior.
|
|
78
|
+
- Reproduction first, theory second, speculation labeled as such.
|
|
79
|
+
- Say what you EXCLUDED and how — negative results save maintainers hours.
|
|
80
|
+
- Attachments for anything over ~20 lines; name files descriptively.
|
|
81
|
+
|
|
82
|
+
## Tone
|
|
83
|
+
|
|
84
|
+
- First person singular for what you did; no "we" unless there is a we.
|
|
85
|
+
- Match their language (English for most trackers) and their register.
|
|
86
|
+
- Respect ≠ deference: plain, direct, no honorifics, no self-flagellation.
|
|
87
|
+
- No pleasing tone: zero eagerness signals, no offers of further service.
|
|
88
|
+
The patch/report IS the gesture; servility reads as noise (or as a bot).
|
|
89
|
+
- Disagree with a maintainer by citing evidence, never by volume.
|
|
90
|
+
|
|
91
|
+
## Follow-up etiquette
|
|
92
|
+
|
|
93
|
+
- Maintainer replied: answer exactly what was asked, nothing else. No
|
|
94
|
+
unasked-for status updates, no enthusiasm about the review.
|
|
95
|
+
- Silence is normal. Do not ping before ~2 weeks (or the project's own norm,
|
|
96
|
+
if stated). One polite ping, never two in a row.
|
|
97
|
+
- Asked for changes/rebase: do them, reply tersely ("Rebased onto main;
|
|
98
|
+
commit X dropped because Y").
|
|
99
|
+
- Abandoning the work: say so in the thread and close/label it yourself.
|
|
100
|
+
|
|
101
|
+
## Pre-submit checklist
|
|
102
|
+
|
|
103
|
+
- [ ] dedup done, near-misses cited
|
|
104
|
+
- [ ] their template/fields used, their title style
|
|
105
|
+
- [ ] scale right: minimal for small, consult-first for big, series offered
|
|
106
|
+
- [ ] style-audit applied if code is included
|
|
107
|
+
- [ ] repro is deterministic (someone else can run it)
|
|
108
|
+
- [ ] every number/quote reproducible, nothing invented
|
|
109
|
+
- [ ] no greetings, no filler, no AI-tell vocabulary
|
|
110
|
+
- [ ] prose where reasoning, lists where artifacts
|
|
111
|
+
- [ ] attachments named, oversized logs trimmed
|
|
112
|
+
- [ ] read it aloud once: would YOU triage this in 60 seconds?
|
|
113
|
+
|
|
114
|
+
## Sources
|
|
115
|
+
|
|
116
|
+
- Simon Tatham, "How to Report Bugs Effectively" (structure, "show me" ethos)
|
|
117
|
+
- Daniel Stenberg, "Death by a thousand slops" (2025), "The end of the curl
|
|
118
|
+
bug-bounty" (2026) — what mass low-trust reports do to maintainers
|
|
119
|
+
- FreeBSD, "Writing FreeBSD Problem Reports" (docs.freebsd.org article)
|
package/package.json
CHANGED
|
@@ -1,6 +1,30 @@
|
|
|
1
1
|
{
|
|
2
|
-
|
|
3
|
-
|
|
4
|
-
|
|
5
|
-
|
|
6
|
-
|
|
2
|
+
"name": "@e4779/skills",
|
|
3
|
+
"version": "0.1.0",
|
|
4
|
+
"description": "Agent-agnostic skill pack (pi manifest inside; plain markdown, other agents can read it too)",
|
|
5
|
+
"keywords": [
|
|
6
|
+
"pi-package"
|
|
7
|
+
],
|
|
8
|
+
"license": "ISC",
|
|
9
|
+
"author": "e4779",
|
|
10
|
+
"pi": {
|
|
11
|
+
"skills": [
|
|
12
|
+
"./drawio",
|
|
13
|
+
"./mindmap",
|
|
14
|
+
"./skill-author",
|
|
15
|
+
"./gh-cli",
|
|
16
|
+
"./mcpls",
|
|
17
|
+
"./mcporter",
|
|
18
|
+
"./chrome-devtools",
|
|
19
|
+
"./grill",
|
|
20
|
+
"./layout-check",
|
|
21
|
+
"./opensource-contribution",
|
|
22
|
+
"./shell-taste",
|
|
23
|
+
"./sobesednik",
|
|
24
|
+
"./zai-mcp"
|
|
25
|
+
]
|
|
26
|
+
},
|
|
27
|
+
"publishConfig": {
|
|
28
|
+
"access": "public"
|
|
29
|
+
}
|
|
30
|
+
}
|
|
@@ -0,0 +1,16 @@
|
|
|
1
|
+
# shell-taste: the objective floor for shellcheck (≈ eslint for shell)
|
|
2
|
+
# Usage: shellcheck --rcfile <skill-dir>/.shellcheckrc script.sh
|
|
3
|
+
# Repo-wide: drop a copy at repo root as .shellcheckrc — shellcheck walks
|
|
4
|
+
# parent dirs from each script, so nested scripts inherit it.
|
|
5
|
+
# Inline pragmas work like eslint-disable: # shellcheck disable=SC2086
|
|
6
|
+
|
|
7
|
+
# report everything down to style level
|
|
8
|
+
severity=style
|
|
9
|
+
|
|
10
|
+
# warn on unquoted variables even where the value is "safe"
|
|
11
|
+
enable=quote-safe-variables
|
|
12
|
+
|
|
13
|
+
# uppercase variables must be assigned before use (catches typo'd consts)
|
|
14
|
+
enable=check-unassigned-uppercase
|
|
15
|
+
|
|
16
|
+
# aggressive option (verified in man): enable=all — every optional check
|
|
@@ -0,0 +1,95 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: shell-taste
|
|
3
|
+
description: "Taste layer for shell code: portable POSIX idioms vs host-shell extras, composability discipline, pre-delivery ritual — plus a generated handbook of measured idioms from ~900 real-world open-source scripts (error handling and die, check_root, usage output, cleanup traps, install logic, menus, logging) with ecosystem-consensus counts and canon exemplars. Use when writing, reviewing, or refactoring any #!/bin/sh or bash script, rc.d-style service script, or CLI glue; when asked how real-world scripts or the ecosystem handle a task, or which idiom is common vs one-off. RU: написать шелл-скрипт, идиоматичный sh, красивый шелл, переписать скрипт на sh, как принято в опенсорсных скриптах, как это делают реальные скрипты, обработка ошибок, check_root, usage, cleanup, install."
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
# shell-taste
|
|
7
|
+
|
|
8
|
+
How to write shell *well*: dialect discipline, idioms, a ritual.
|
|
9
|
+
The objective floor is shellcheck — the eslint of shell (rule codes SC####,
|
|
10
|
+
severity levels, enable/disable config, inline pragmas) — driven by this
|
|
11
|
+
skill's `.shellcheckrc`.
|
|
12
|
+
|
|
13
|
+
## 1. Dialect — portable core by default
|
|
14
|
+
|
|
15
|
+
Two tiers; pick deliberately. Host-local scripts mark `# dialect: host` on line 2.
|
|
16
|
+
|
|
17
|
+
- **posix** (default, unmarked): POSIX Issue 7 + `local`. Runs on dash,
|
|
18
|
+
FreeBSD sh, bash, busybox ash, mksh. No pipefail, no $'..'.
|
|
19
|
+
- **host**: extras of the host shell. On FreeBSD /bin/sh (probed 2026-11):
|
|
20
|
+
pipefail, $'..', `local` with dynamic scoping, `local -` (options scoped
|
|
21
|
+
to the function, restored on return). bash: same set.
|
|
22
|
+
|
|
23
|
+
Portability matrix (probed live 2026-11; dash column from upstream docs):
|
|
24
|
+
|
|
25
|
+
| feature | POSIX Iss.7 | FreeBSD sh | bash | dash | zsh |
|
|
26
|
+
|---|---|---|---|---|---|
|
|
27
|
+
| `local` | no (rationale left it for "a future version") | yes | yes | yes | yes |
|
|
28
|
+
| `pipefail`| no | yes | yes | NO | yes |
|
|
29
|
+
| `$'..'` | no | yes | yes | NO | yes |
|
|
30
|
+
| `local -` | no | yes | yes | — | (use `setopt local_options`) |
|
|
31
|
+
|
|
32
|
+
ksh93 has no `local` (use `typeset`).
|
|
33
|
+
|
|
34
|
+
If correctness *needs* pipefail: restructure — check exit codes explicitly
|
|
35
|
+
(`cmd || exit`, while-read loops) instead of leaning on a non-portable option.
|
|
36
|
+
|
|
37
|
+
## 2. Idioms (the canon)
|
|
38
|
+
|
|
39
|
+
Verbs as functions returning via stdout; case = pattern dispatch;
|
|
40
|
+
`${var#pat}` / `${var%%pat}` before sed; heredocs for generated files;
|
|
41
|
+
pipelines as dataflow; `set --` as a worklist; metadata-vars + naming
|
|
42
|
+
convention (rc.subr style) for multi-script projects.
|
|
43
|
+
|
|
44
|
+
```sh
|
|
45
|
+
log() { printf '%s: %s\n' "${0##*/}" "$*" >&2; }
|
|
46
|
+
die() { log "error: $*"; exit 1; }
|
|
47
|
+
cleanup() { [ -n "$tmp" ] && rm -rf "$tmp"; }
|
|
48
|
+
trap cleanup EXIT INT TERM
|
|
49
|
+
tmp=$(mktemp -d) || die mktemp
|
|
50
|
+
```
|
|
51
|
+
|
|
52
|
+
## 3. Ritual before delivering
|
|
53
|
+
|
|
54
|
+
1. `shfmt -ln posix -s` — apply its rewrite; it enforces idiom mechanically
|
|
55
|
+
2. shellcheck with this skill's rc (explicit path, nothing to copy):
|
|
56
|
+
`shellcheck --rcfile <this-skill-dir>/.shellcheckrc script.sh`
|
|
57
|
+
- portable tier: add `-s dash` — the strictest dialect, catches bashisms
|
|
58
|
+
(SC2039 class "In POSIX sh, ... is undefined")
|
|
59
|
+
- host tier: `-s bash`, or let the shebang deduce
|
|
60
|
+
- many scripts in one repo: drop the rc at repo root as `.shellcheckrc` —
|
|
61
|
+
discovered from each script's directory upward, editors inherit it too
|
|
62
|
+
3. Read every unquoted $var aloud; cannot justify it → quote it
|
|
63
|
+
4. If the user is taste-learning: offer an A/B variant (toolbox vs loop) and let them pick
|
|
64
|
+
|
|
65
|
+
Inline pragmas work like eslint-disable (`# shellcheck disable=SC2086`) —
|
|
66
|
+
use sparingly, with the reason on the same line.
|
|
67
|
+
|
|
68
|
+
## 4. Canon (consult on demand)
|
|
69
|
+
|
|
70
|
+
pure-sh-bible (dylanaraps) · Wooledge wiki (BashPitfalls, BashFAQ/105) · kiss,
|
|
71
|
+
`/etc/rc.d/*` on this host.
|
|
72
|
+
|
|
73
|
+
## 5. Handbook (generated)
|
|
74
|
+
|
|
75
|
+
Measured companion: idioms harvested from ~900 real-world open-source
|
|
76
|
+
scripts (die/error handling, check_root, usage output, cleanup traps,
|
|
77
|
+
install logic, menus, logging), with ecosystem-consensus counts and canon
|
|
78
|
+
exemplars. Rebuild after atlas data changes: `mk -C ~/projects/shell-atlas handbook`.
|
|
79
|
+
|
|
80
|
+
| You ask | Open | You get |
|
|
81
|
+
|---|---|---|
|
|
82
|
+
| error handling, die, exit codes | references/handbook/dom/02-errors-exit.md | family entries + copy-paste queries |
|
|
83
|
+
| how do real-world scripts do X / what does the ecosystem use | domain page via the slug line below | consensus counts + canon kin |
|
|
84
|
+
| the proper way / show the reference | domain page, canon line | top-ranked exemplar body |
|
|
85
|
+
| how common is this practice | domain page, consensus lines; thresholds in references/handbook/index.md | wild family names + similarity scores |
|
|
86
|
+
| two live variants of one task | references/handbook/dialects.md | JOB/SAME/DIFF card, bodies a/b |
|
|
87
|
+
| what is family X / where does check_root appear | references/handbook/family-index.md | anchor → domain page → query |
|
|
88
|
+
|
|
89
|
+
Domains: `output-logging` `errors-exit` `installation-setup` `network` `files-paths` `checks-validation` `system-administration` `privilege-users` `text-data` `terminal-ux` `process-control` `containers` `agents-ai-tooling` `uncategorized` — one page per domain at `references/handbook/dom/<NN>-<slug>.md`.
|
|
90
|
+
|
|
91
|
+
Reading rules: counts printed on the pages are navigation aids, stamped
|
|
92
|
+
as-of — never quote them as universal facts. Canon and wild family names
|
|
93
|
+
differ ("Check Root Privileges" vs "Privilege Check"): grep family-index
|
|
94
|
+
by word root and desc words, not by exact name.
|
|
95
|
+
|
|
@@ -0,0 +1,168 @@
|
|
|
1
|
+
<!-- GENERATED by shell-atlas bin/handbook (mk handbook). Hand edits WILL be overwritten. as-of: 5539bbbe9ebc 2026-11-08 -->
|
|
2
|
+
|
|
3
|
+
# Dialect cards — same job, different spelling
|
|
4
|
+
|
|
5
|
+
18 measured pairs (top archetypes of the dialect band). Verdict lines are verbatim from work/wild/dialect-cards.toon (audit diffs them against the jsonl mirror); bodies resolve by coordinate under work/wild/units/.
|
|
6
|
+
|
|
7
|
+
### change_color
|
|
8
|
+
|
|
9
|
+
sim 0.8996 (observed pair similarity).
|
|
10
|
+
|
|
11
|
+
JOB: Update configuration files for colors | SAME: Both functions modify polybar and rofi configurations | DIFF: Function A replaces specific color values using sed and overwrites the entire rofi configuration file | Function B replaces specific color values using sed for polybar and overwrites the entire rofi configuration file | Function C is not present. | Function D is not present. | Function
|
|
12
|
+
|
|
13
|
+
- a: `work/wild/units/adi1090x-polybar-themes/0158-change_color.sh`
|
|
14
|
+
- b: `work/wild/units/thegoodhackertv-hackerpwm/0003-change_color.sh`
|
|
15
|
+
|
|
16
|
+
### rofi_cmd
|
|
17
|
+
|
|
18
|
+
sim 0.8901 (observed pair similarity).
|
|
19
|
+
|
|
20
|
+
JOB: Launching a rofi menu | SAME: rofi -dmenu with user prompt and uptime message | DIFF: The functions are identical in logic and parameters. They differ only in the way they are formatted and indented.
|
|
21
|
+
|
|
22
|
+
- a: `work/wild/units/adi1090x-rofi/0054-rofi_cmd.sh`
|
|
23
|
+
- b: `work/wild/units/stringhost-kalighost/0001-rofi_cmd.sh`
|
|
24
|
+
|
|
25
|
+
### error
|
|
26
|
+
|
|
27
|
+
sim 0.8781 (observed pair similarity).
|
|
28
|
+
|
|
29
|
+
JOB: Error handling | SAME: Exit with status 1 | DIFF: A uses a ANSI color code variable, while B uses raw escape sequences.
|
|
30
|
+
|
|
31
|
+
- a: `work/wild/units/alirezarezvani-claude-code-tresor/0003-error.sh`
|
|
32
|
+
- b: `work/wild/units/adam-sizzler-marz-reverse-proxy/0004-error.sh`
|
|
33
|
+
|
|
34
|
+
### die
|
|
35
|
+
|
|
36
|
+
sim 0.8996 (observed pair similarity).
|
|
37
|
+
|
|
38
|
+
JOB: Terminate script | SAME: Prints to stderr and exits with 1 | DIFF: A uses ANSI color codes for formatting.
|
|
39
|
+
|
|
40
|
+
- a: `work/wild/units/andrewnakas-skate3-ios-setup/0008-die.sh`
|
|
41
|
+
- b: `work/wild/units/solaceproducts-solace-agent-mesh/0003-die.sh`
|
|
42
|
+
|
|
43
|
+
### fail
|
|
44
|
+
|
|
45
|
+
sim 0.8782 (observed pair similarity).
|
|
46
|
+
|
|
47
|
+
JOB: Terminate script execution | SAME: Exit with status 1 | DIFF: B redirects output to stderr and A does not.
|
|
48
|
+
|
|
49
|
+
- a: `work/wild/units/automazeio-ccpm/0011-fail.sh`
|
|
50
|
+
- b: `work/wild/units/ublue-os-ucore/0001-fail.sh`
|
|
51
|
+
|
|
52
|
+
### cleanup
|
|
53
|
+
|
|
54
|
+
sim 0.8971 (observed pair similarity).
|
|
55
|
+
|
|
56
|
+
JOB: Deleting worktrees and branches | SAME: Removing directories and branches | DIFF: A is a simple directory deletion, while B uses git-specific commands to remove worktrees and branches.
|
|
57
|
+
|
|
58
|
+
- a: `work/wild/units/binpash-try/0010-cleanup.sh`
|
|
59
|
+
- b: `work/wild/units/fletchgqc-agentbox/0001-cleanup.sh`
|
|
60
|
+
|
|
61
|
+
### _request
|
|
62
|
+
|
|
63
|
+
sim 0.895 (observed pair similarity).
|
|
64
|
+
|
|
65
|
+
JOB: Executing a curl request | SAME: Docker container status check and curl command structure | DIFF: Container linking and target hostnames for the request.
|
|
66
|
+
|
|
67
|
+
- a: `work/wild/units/docker-library-official-images/0079-_request.sh`
|
|
68
|
+
- b: `work/wild/units/nginx-docker-nginx/0010-_request.sh`
|
|
69
|
+
|
|
70
|
+
### info
|
|
71
|
+
|
|
72
|
+
sim 0.878 (observed pair similarity).
|
|
73
|
+
|
|
74
|
+
JOB: Logging status messages | SAME: Both use printf to output a formatted string | DIFF: A uses a variable for color codes and A uses a shell variable for color codes. (Wait, I need to make sure I'm correct. A uses `_CLR_GREEN` and `_CLR_RESET`, while B uses `GREEN` and `GREEN`? No, B uses `GREEN` and `RESET`. Let me re-read.) 1. A uses `_CLR_GREEN` and `_CLR_RESET`. 2. B uses `GREEN` and `RESET`
|
|
75
|
+
|
|
76
|
+
- a: `work/wild/units/prismml-eng-bonsai-demo/0014-info.sh`
|
|
77
|
+
- b: `work/wild/units/jnmetacode-agency-agents-zh/0001-info.sh`
|
|
78
|
+
|
|
79
|
+
### fetch
|
|
80
|
+
|
|
81
|
+
sim 0.8978 (observed pair similarity).
|
|
82
|
+
|
|
83
|
+
JOB: Downloading files | SAME: curl and die commands | DIFF: A pipes to tar for extraction, while B downloads a single file to a disk.
|
|
84
|
+
|
|
85
|
+
- a: `work/wild/units/ravindu644-android-kernel-tutorials/0003-fetch.sh`
|
|
86
|
+
- b: `work/wild/units/xiaolegun-kernelsu_action/0026-fetch.sh`
|
|
87
|
+
|
|
88
|
+
### usage
|
|
89
|
+
|
|
90
|
+
sim 0.8907 (observed pair similarity).
|
|
91
|
+
|
|
92
|
+
JOB: Display usage instructions | SAME: sed commands for parsing and replacing | DIFF: There is no substantive difference between the two functions. They are identical.
|
|
93
|
+
|
|
94
|
+
- a: `work/wild/units/sobolevn-git-secret/0008-usage.sh`
|
|
95
|
+
- b: `work/wild/units/bats-core-bats-core/0008-usage.sh`
|
|
96
|
+
|
|
97
|
+
### warn
|
|
98
|
+
|
|
99
|
+
sim 0.8997 (observed pair similarity).
|
|
100
|
+
|
|
101
|
+
JOB: Issue a warning | SAME: Both use printf to output a colorized warning message | DIFF: A uses a character-style prefix and character-style prefix, while B uses a bracketed "!!" prefix. (Wait, I need to make sure the shell script is thesaurus-ly correct and concise.) Let me re-read the "DIFF" part. A uses `!`, B uses `[!!]`. 100% correct. Let me re- the "DIFF" part. A uses `!`, B uses `[!!]`. 1
|
|
102
|
+
|
|
103
|
+
- a: `work/wild/units/peonping-peon-ping/0029-warn.sh`
|
|
104
|
+
- b: `work/wild/units/jnmetacode-agency-agents-zh/0002-warn.sh`
|
|
105
|
+
|
|
106
|
+
### err
|
|
107
|
+
|
|
108
|
+
sim 0.8859 (observed pair similarity).
|
|
109
|
+
|
|
110
|
+
JOB: Error reporting | SAME: Output to stderr | DIFF: Variable names for color codes differ.
|
|
111
|
+
|
|
112
|
+
- a: `work/wild/units/jnmetacode-agency-agents-zh/0043-err.sh`
|
|
113
|
+
- b: `work/wild/units/prismml-eng-bonsai-demo/0016-err.sh`
|
|
114
|
+
|
|
115
|
+
### command_exists
|
|
116
|
+
|
|
117
|
+
sim 0.8975 (observed pair similarity).
|
|
118
|
+
|
|
119
|
+
JOB: Check if a command exists | SAME: command -v "$1" >/dev/null 2>&1 | DIFF: There is no substantive difference between the two functions. They are functionally identical.
|
|
120
|
+
|
|
121
|
+
- a: `work/wild/units/lmc999-regionrestrictioncheck/0002-command_exists.sh`
|
|
122
|
+
- b: `work/wild/units/yeahwu-v2ray-wss/0022-command_exists.sh`
|
|
123
|
+
|
|
124
|
+
### main
|
|
125
|
+
|
|
126
|
+
sim 0.8429 (observed pair similarity).
|
|
127
|
+
|
|
128
|
+
JOB: Software installation | SAME: Automated script execution | DIFF: Script A handles complex configuration and service management, while Script B focuses on a linear, file-based binary installation.
|
|
129
|
+
|
|
130
|
+
- a: `work/wild/units/xtls-xray-install/0056-main.sh`
|
|
131
|
+
- b: `work/wild/units/lewislulu-terminal-setup/0001-main.sh`
|
|
132
|
+
|
|
133
|
+
### pass
|
|
134
|
+
|
|
135
|
+
sim 0.8277 (observed pair similarity).
|
|
136
|
+
|
|
137
|
+
JOB: Print success messages | SAME: Output format and content | DIFF: Function A includes a counter and increments it.
|
|
138
|
+
|
|
139
|
+
- a: `work/wild/units/games-on-whales-gow/0003-pass.sh`
|
|
140
|
+
- b: `work/wild/units/0xax-asm/0002-pass.sh`
|
|
141
|
+
|
|
142
|
+
### ok
|
|
143
|
+
|
|
144
|
+
sim 0.885 (observed pair similarity).
|
|
145
|
+
|
|
146
|
+
JOB: Print status message | SAME: Output format with prefix and arguments | DIFF: A uses a plain text output with a added counter, but B uses ANSI escape codes for green color.
|
|
147
|
+
|
|
148
|
+
- a: `work/wild/units/games-on-whales-gow/0008-ok.sh`
|
|
149
|
+
- b: `work/wild/units/andrewnakas-skate3-ios-setup/0006-ok.sh`
|
|
150
|
+
|
|
151
|
+
### log
|
|
152
|
+
|
|
153
|
+
sim 0.8747 (observed pair similarity).
|
|
154
|
+
|
|
155
|
+
JOB: Logging messages | SAME: Output format with timestamp | DIFF: B uses printf for formatting and a different date format, while A uses echo and a1zmc format. (Wait, I need to meed the strict format) -> JOB: Logging messages | SAME: Output format with timestamp | DIFF: B uses printf for formatting and a different date format, while A uses echo and a1zmc format. (Wait, I meed to meed the strict f
|
|
156
|
+
|
|
157
|
+
- a: `work/wild/units/hamelsmu-claude-review-loop/0007-log.sh`
|
|
158
|
+
- b: `work/wild/units/aaddrick-claude-desktop-debian/0001-log.sh`
|
|
159
|
+
|
|
160
|
+
### check_root
|
|
161
|
+
|
|
162
|
+
sim 0.8675 (observed pair similarity).
|
|
163
|
+
|
|
164
|
+
JOB: Root privilege check | SAME: Checking the current user's UID | DIFF: A uses exiterr function and a custom message, while B uses printf with a ANSI-colored string and a hardcoded exit code.
|
|
165
|
+
|
|
166
|
+
- a: `work/wild/units/hwdsl2-setup-ipsec-vpn/0151-check_root.sh`
|
|
167
|
+
- b: `work/wild/units/jinqians-snell/0102-check_root.sh`
|
|
168
|
+
|