From 5d96e69d2bdae71d205150ebc1dc0f0abba2687f Mon Sep 17 00:00:00 2001 From: Bluscream Date: Fri, 18 Sep 2026 12:49:30 +0200 Subject: [PATCH] refactor(skills): inline cross-links, drop Related sections, fix conventions MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - all nine files: trailing "Related" sections removed, their unique links inlined where the topic actually arises (FFI boundary -> c-cpp, embedded frontend -> js-typescript, build scripts -> bash, etc.) - README conventions: rule 2 mandated a Related Skills section, which now contradicts practice — replaced with inline-linking and one-home-per-fact rules. The / rule was appended after the wrong section last commit; moved into the list where it belongs. Co-Authored-By: Claude Opus 5 --- README.md | 29 ++++++++++++++++++----------- cli-tooling.md | 7 ------- code-languages/bash.md | 12 ++---------- code-languages/c-cpp.md | 11 ++--------- code-languages/csharp-dotnet.md | 9 ++------- code-languages/go.md | 9 ++------- code-languages/js-typescript.md | 9 ++------- code-languages/python.md | 7 +------ code-languages/rust.md | 8 +------- coding-dev.md | 5 ----- 10 files changed, 30 insertions(+), 76 deletions(-) diff --git a/README.md b/README.md index 83aaa28..a20914b 100644 --- a/README.md +++ b/README.md @@ -33,10 +33,24 @@ Each language file extends `coding-dev.md` rather than repeating it. A project's Skills in this repo follow the same structure as the private counterpart repo, so agents can load either interchangeably: 1. **YAML frontmatter** with `name` (kebab-case, matching the filename) and a `description` starting with *"Use this skill when …"* — the description is what an agent matches against to decide relevance, so it must enumerate concrete triggers. -2. **Numbered `##` sections**, sequential and unique, ending with a **Related Skills** section that cross-links sibling documents. -3. **CLI discovery over enumeration** — document the *non-obvious* workflows, gotchas, and constraints. For the routine surface, point at ` --help` rather than transcribing flag lists that will go stale. -4. **No secrets inline** — reference the environment file that holds them (e.g. `~/.config/environment.d/…`), never the values themselves. -5. **Verify before documenting** — confirm hostnames, container names, and versions against the live system rather than carrying forward stale claims. +2. **Numbered `##` sections**, sequential and unique. +3. **Cross-link inline, at the point the other skill becomes relevant** — never in a trailing + "Related Skills" list. A link inside the sentence that raises the topic gets followed; a + list at the bottom of a long document does not, and it drifts out of sync with the body. +4. **One home per fact.** Content that belongs to another skill is *replaced* by a link to it, + not duplicated. Where a skill needs its own specific values for something another skill + owns the rules for (a container's own template fields, say), keep only the values and link + out for the rules. +5. **Link between skills as `/`** — e.g. + `` [`cli-tooling.md`](skills-public/cli-tooling.md) `` or + `` [`network.md`](skills-private/network.md) ``. Links resolve from the shared parent + directory holding both repos, so the same spelling works from either repo and from any + subdirectory. Never `./`, `../`, or absolute `file://` paths. The sole exception is the + per-agent profile files, which state each repository root once in full, since they are + loaded as global instructions with no implied working directory. +6. **CLI discovery over enumeration** — document the *non-obvious* workflows, gotchas, and constraints. For the routine surface, point at ` --help` rather than transcribing flag lists that will go stale. +7. **No secrets inline** — reference the environment file that holds them (e.g. `~/.config/environment.d/…`), never the values themselves. +8. **Verify before documenting** — confirm hostnames, container names, and versions against the live system rather than carrying forward stale claims. --- @@ -47,10 +61,3 @@ These skill documents are compatible across agentic developer assistants and env - **Codex**: Include in workspace instructions or agent configuration. - **Antigravity**: Mount or reference from workspace `.agents/skills/` or global `~/.gemini/config/skills/`. - **Other AI Tools (Cursor, OpenCode, Aider, Devin)**: Include as persistent project rules or context files. -6. **Link between skills as `/`** — e.g. - `` [`cli-tooling.md`](skills-public/cli-tooling.md) `` or - `` [`network.md`](skills-private/network.md) ``. Links resolve from the shared parent - directory holding both repos, so the same spelling works from either repo and from any - subdirectory. Never `./`, `../`, or absolute `file://` paths. The sole exception is the - per-agent profile files, which state each repository root once in full, since they are - loaded as global instructions with no implied working directory. diff --git a/cli-tooling.md b/cli-tooling.md index 404befa..80e160f 100644 --- a/cli-tooling.md +++ b/cli-tooling.md @@ -180,10 +180,3 @@ system, not scattered at the repository root. - **Don't saturate the machine.** A full build consuming every core makes the workstation unusable. When something latency-sensitive is running, reduce the job count and `nice` the work — and say that you did. - ---- - -## 8. Related Skills -- [`coding-dev.md`](skills-public/coding-dev.md) — writing the code these tools build and test. -- [`code-languages/bash.md`](skills-public/code-languages/bash.md) — writing the scripts themselves: - strict mode, quoting, build-gate structure, destructive-command guards. diff --git a/code-languages/bash.md b/code-languages/bash.md index d7da7ea..d843a53 100644 --- a/code-languages/bash.md +++ b/code-languages/bash.md @@ -11,8 +11,8 @@ description: >- Extends [`coding-dev.md`](skills-public/coding-dev.md). Everything there applies; this adds shell specifics. Bash is for **orchestration** — sequencing tools, wiring a build pipeline, gluing CLIs. -Once a script grows real data structures, arithmetic, or parsing, it wants to be Python or -a compiled tool instead. +Once a script grows real data structures, arithmetic, or parsing, it wants to be +[Python](skills-public/code-languages/python.md) or a compiled tool instead. --- @@ -165,11 +165,3 @@ Standalone utility scripts belong in a **dedicated, version-controlled scripts d symlinked into `PATH` rather than copied there. Never write a loose script directly into `~/.local/bin` or another `PATH` directory — the source of truth should be one versioned location. See [`cli-tooling.md` §5](skills-public/cli-tooling.md) for the reasoning and the pattern. - ---- - -## 10. Related -- [`coding-dev.md`](skills-public/coding-dev.md) — the general rules this extends. -- [`cli-tooling.md`](skills-public/cli-tooling.md) — invoking other tools *from* these scripts: - discovery, non-interactive flags, structured output. -- [`python.md`](skills-public/code-languages/python.md) — where a shell script should have become a Python script. diff --git a/code-languages/c-cpp.md b/code-languages/c-cpp.md index d84616c..01d151e 100644 --- a/code-languages/c-cpp.md +++ b/code-languages/c-cpp.md @@ -11,8 +11,8 @@ description: >- Extends [`coding-dev.md`](skills-public/coding-dev.md). Everything there applies; this adds C/C++ specifics. C and C++ are for the cases with no better option: existing codebases, hard real-time paths, -and FFI boundaries. **For new standalone work, prefer Rust** — the memory-safety guarantees -are worth more than the familiarity. +and FFI boundaries. **For new standalone work, prefer [Rust](skills-public/code-languages/rust.md)** — the memory-safety +guarantees are worth more than the familiarity. --- @@ -144,10 +144,3 @@ When exposing C/C++ to another language: - When a binary search through a packed/embedded blob finds nothing, that is not evidence the content is absent — packed asset formats defeat naive string searches. Re-check without anchoring before concluding. - ---- - -## 9. Related -- [`coding-dev.md`](skills-public/coding-dev.md) — the general rules this extends. -- [`rust.md`](skills-public/code-languages/rust.md) — the preferred language for new native work, and the usual consumer - of these FFI boundaries. diff --git a/code-languages/csharp-dotnet.md b/code-languages/csharp-dotnet.md index 8a2a3d6..3bb1ca9 100644 --- a/code-languages/csharp-dotnet.md +++ b/code-languages/csharp-dotnet.md @@ -143,12 +143,7 @@ interface, a type being renamed): project's designated container. Entering one resets the working directory — chain `cd` in the same command string. - Prefer the project's build script over hand-typed `dotnet` calls; it carries `-warnaserror`, - the correct action ordering, and the asset completeness checks. + the correct action ordering, and the asset completeness checks — see + [`bash.md`](skills-public/code-languages/bash.md) for how that script should be structured. - **Never stop, deploy to, or restart an application while the user has it running**, unless they have said to. - ---- - -## 9. Related -- [`coding-dev.md`](skills-public/coding-dev.md) — the general rules this extends. -- [`bash.md`](skills-public/code-languages/bash.md) — for the release pipeline scripts around a .NET build. diff --git a/code-languages/go.md b/code-languages/go.md index 4f46e1b..bb24de6 100644 --- a/code-languages/go.md +++ b/code-languages/go.md @@ -135,7 +135,8 @@ CGO_ENABLED=0 go build -trimpath -ldflags="-s -w" -o bin/app ./cmd/app - One package per concern; **package names are lowercase, single-word, no underscores**, and never `util` or `common`. - Keep the exported surface small. Unexported by default. -- Embed frontend/static assets with `//go:embed` for single-binary distribution. +- Embed frontend/static assets with `//go:embed` for single-binary distribution — the frontend + itself follows [`js-typescript.md`](skills-public/code-languages/js-typescript.md). - File and function size limits from the general rules apply. --- @@ -149,9 +150,3 @@ CGO_ENABLED=0 go build -trimpath -ldflags="-s -w" -o bin/app ./cmd/app - **Regression test every fixed bug.** - **Never run destructive operations against real accounts or user data during validation** — temporary fixtures only. - ---- - -## 10. Related -- [`coding-dev.md`](skills-public/coding-dev.md) — the general rules this extends. -- [`js-typescript.md`](skills-public/code-languages/js-typescript.md) — for the embedded frontend in a Go service. diff --git a/code-languages/js-typescript.md b/code-languages/js-typescript.md index 84699fa..bbee280 100644 --- a/code-languages/js-typescript.md +++ b/code-languages/js-typescript.md @@ -175,7 +175,8 @@ Attach an `AbortController` to every long-lived `fetch` and abort it in cleanup. ## 10. Tooling & Tests - Respect the project's runtime and package manager (`npm` / `pnpm` / `yarn` / `bun`) and its - lockfile. Do not switch package managers or add a second lockfile. + lockfile. Do not switch package managers or add a second lockfile. Build and release scripts + around it follow [`bash.md`](skills-public/code-languages/bash.md). - Test runner: whatever the project uses (`vitest`, `bun test`, `jest`). Tests live beside the code as `*.test.ts(x)` unless the project says otherwise. - **Add unit tests for new logic and route tests for new handlers.** Prioritize coverage on @@ -195,9 +196,3 @@ Attach an `AbortController` to every long-lived `fetch` and abort it in cleanup. > current APIs frequently differ from what is in a model's training data. **Read the version's > own docs in `node_modules//dist/docs/` or the project's pinned documentation before > writing code against them.** Heed deprecation notices rather than pattern-matching from memory. - ---- - -## 12. Related -- [`coding-dev.md`](skills-public/coding-dev.md) — the general rules this extends. -- [`bash.md`](skills-public/code-languages/bash.md) — for the build/release scripts around these projects. diff --git a/code-languages/python.md b/code-languages/python.md index 3cb7adf..649f3cc 100644 --- a/code-languages/python.md +++ b/code-languages/python.md @@ -9,6 +9,7 @@ description: >- # Python — Rules & Preferences Extends [`coding-dev.md`](skills-public/coding-dev.md). Everything there applies; this adds Python specifics. +For the surrounding build and deploy scripts, see [`bash.md`](skills-public/code-languages/bash.md). --- @@ -145,9 +146,3 @@ When talking to a rate-limited API (a chat platform, a store, a tracker): - **Never exercise destructive operations against real accounts or real data.** Temporary fixtures only. - `pytest -p no:randomly` only when order genuinely matters, and note why. - ---- - -## 10. Related -- [`coding-dev.md`](skills-public/coding-dev.md) — the general rules this extends. -- [`bash.md`](skills-public/code-languages/bash.md) — for the surrounding build and deploy scripts. diff --git a/code-languages/rust.md b/code-languages/rust.md index 376a89a..92a04cd 100644 --- a/code-languages/rust.md +++ b/code-languages/rust.md @@ -96,7 +96,7 @@ workspace = true **Forbidden by default**, enforced in `Cargo.toml` with `unsafe_code = "forbid"`. If an FFI binding genuinely requires it, it goes behind a **safe wrapper in exactly one -module**, with a `// SAFETY:` comment on every block stating the invariant being upheld. +module** (see [`c-cpp.md`](skills-public/code-languages/c-cpp.md) for the other side of that boundary), with a `// SAFETY:` comment on every block stating the invariant being upheld. `unsafe` scattered through call sites is not acceptable. --- @@ -189,9 +189,3 @@ throttling so a release build does not saturate the machine. **Split so that as little as possible needs the container**: a `-core` crate with no GUI dependencies builds and tests directly on the host, which is seconds instead of minutes. - ---- - -## 11. Related -- [`coding-dev.md`](skills-public/coding-dev.md) — the general rules this extends. -- [`c-cpp.md`](skills-public/code-languages/c-cpp.md) — when bindgen/FFI crosses into a C library. diff --git a/coding-dev.md b/coding-dev.md index 898f375..5d18605 100644 --- a/coding-dev.md +++ b/coding-dev.md @@ -308,8 +308,3 @@ Full version in [`cli-tooling.md`](skills-public/cli-tooling.md); the essentials `nice` the build. - **Prefer long-running work in the background** over blocking wait loops. Never write `until ; do sleep 2; done` — it hangs the terminal and has to be interrupted by hand. - ---- - -## 14. Related Skills -- [`code-languages/`](skills-public/code-languages/) — per-language rules that extend and specialize this document.