From 58525056a158adb67cea0465f4e4530c08e2207b Mon Sep 17 00:00:00 2001 From: Bluscream Date: Fri, 18 Sep 2026 12:44:23 +0200 Subject: [PATCH] docs: use / links throughout, document the convention MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit All cross-skill links now spell out the repository: skills-public/foo.md, skills-private/bar.md. These resolve from the shared parent directory, so one spelling works from either repo and from code-languages/ subdirectories โ€” replacing the previous mix of ./, ../ and absolute file:// URLs. Link labels normalised to match. Convention added to the README conventions list. Co-Authored-By: Claude Opus 5 --- README.md | 27 +++++++++++++++++---------- cli-tooling.md | 10 +++++----- code-languages/bash.md | 10 +++++----- code-languages/c-cpp.md | 6 +++--- code-languages/csharp-dotnet.md | 6 +++--- code-languages/go.md | 6 +++--- code-languages/js-typescript.md | 6 +++--- code-languages/python.md | 6 +++--- code-languages/rust.md | 6 +++--- coding-dev.md | 20 ++++++++++---------- 10 files changed, 55 insertions(+), 48 deletions(-) diff --git a/README.md b/README.md index 497598e..83aaa28 100644 --- a/README.md +++ b/README.md @@ -8,20 +8,20 @@ A collection of public, reusable agent skills, cheatsheets, and operational work | Skill File | Scope / Topics Covered | | :--- | :--- | -| **[`coding-dev.md`](./coding-dev.md)** | Standing rules for all code work: maximum linter/compiler strictness, never filtering build output, reuse-before-reinvent dependency ordering, file/function size limits, test & regression discipline, verification gates, scope control, commit hygiene, and honest reporting. | -| **[`cli-tooling.md`](./cli-tooling.md)** | Using command-line tools correctly: reading the help tree instead of guessing flags, preferring an existing CLI over an ad-hoc script, non-interactive invocation, machine-readable output formats, orienting on prior work before starting, script placement & symlinking, and care around destructive commands. | +| **[`coding-dev.md`](skills-public/coding-dev.md)** | Standing rules for all code work: maximum linter/compiler strictness, never filtering build output, reuse-before-reinvent dependency ordering, file/function size limits, test & regression discipline, verification gates, scope control, commit hygiene, and honest reporting. | +| **[`cli-tooling.md`](skills-public/cli-tooling.md)** | Using command-line tools correctly: reading the help tree instead of guessing flags, preferring an existing CLI over an ad-hoc script, non-interactive invocation, machine-readable output formats, orienting on prior work before starting, script placement & symlinking, and care around destructive commands. | -### ๐Ÿ”ค Per-Language Rules ([`code-languages/`](./code-languages/)) +### ๐Ÿ”ค Per-Language Rules ([`code-languages/`](skills-public/code-languages/)) | Language | Skill File | Highlights | | :--- | :--- | :--- | -| **Rust** | [`rust.md`](./code-languages/rust.md) | `--workspace` clippy gate, `[workspace.lints]` single source of truth, no `unwrap`/`unsafe`, core-crate split | -| **TypeScript / JavaScript** | [`js-typescript.md`](./code-languages/js-typescript.md) | TS > JSDoc > plain JS, banned constructs table, React & hooks rules, resource lifecycle, sandbox boundaries | -| **Bash / Shell** | [`bash.md`](./code-languages/bash.md) | `set -euo pipefail`, shellcheck, no wait loops, destructive-command guards, build-gate structure | -| **Python** | [`python.md`](./code-languages/python.md) | `mypy --strict`, broad ruff rule set, asyncio task discipline, rate-limit queueing | -| **Go** | [`go.md`](./code-languages/go.md) | strict `golangci-lint` set, concrete types over `interface{}`, context everywhere, CGO-free static builds | -| **C# / .NET** | [`csharp-dotnet.md`](./code-languages/csharp-dotnet.md) | `TreatWarningsAsErrors`, nullable enabled, no `.Result`, trimming/single-file publish caveats, SDK shims | -| **C / C++** | [`c-cpp.md`](./code-languages/c-cpp.md) | full warning set + `-Werror`, sanitizers, RAII/Rule of Zero, target-based CMake, FFI ownership | +| **Rust** | [`rust.md`](skills-public/code-languages/rust.md) | `--workspace` clippy gate, `[workspace.lints]` single source of truth, no `unwrap`/`unsafe`, core-crate split | +| **TypeScript / JavaScript** | [`js-typescript.md`](skills-public/code-languages/js-typescript.md) | TS > JSDoc > plain JS, banned constructs table, React & hooks rules, resource lifecycle, sandbox boundaries | +| **Bash / Shell** | [`bash.md`](skills-public/code-languages/bash.md) | `set -euo pipefail`, shellcheck, no wait loops, destructive-command guards, build-gate structure | +| **Python** | [`python.md`](skills-public/code-languages/python.md) | `mypy --strict`, broad ruff rule set, asyncio task discipline, rate-limit queueing | +| **Go** | [`go.md`](skills-public/code-languages/go.md) | strict `golangci-lint` set, concrete types over `interface{}`, context everywhere, CGO-free static builds | +| **C# / .NET** | [`csharp-dotnet.md`](skills-public/code-languages/csharp-dotnet.md) | `TreatWarningsAsErrors`, nullable enabled, no `.Result`, trimming/single-file publish caveats, SDK shims | +| **C / C++** | [`c-cpp.md`](skills-public/code-languages/c-cpp.md) | full warning set + `-Werror`, sanitizers, RAII/Rule of Zero, target-based CMake, FFI ownership | Each language file extends `coding-dev.md` rather than repeating it. A project's own `AGENTS.md` / `CLAUDE.md` / `.rules` always overrides both. @@ -47,3 +47,10 @@ 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 cd84506..404befa 100644 --- a/cli-tooling.md +++ b/cli-tooling.md @@ -11,7 +11,7 @@ description: >- # CLI & Tooling โ€” Discovery, Invocation, and Script Placement How to use command-line tools correctly, and where utility scripts belong. -Companion to [`coding-dev.md`](./coding-dev.md), which covers writing the code itself. +Companion to [`coding-dev.md`](skills-public/coding-dev.md), which covers writing the code itself. --- @@ -62,7 +62,7 @@ Anything run from a script, a CI job, or an agent must not depend on a human bei - **Use the tool's own blocking flag** (`--wait`, `--follow`, `--no-detach`) when you need an operation to finish before the next step. Do not build a polling loop around a command that already knows how to wait โ€” and never write a shell `until`/`while` wait loop - (see [`code-languages/bash.md`](./code-languages/bash.md)). + (see [`code-languages/bash.md`](skills-public/code-languages/bash.md)). - **Prefer a `--dry-run` rehearsal** for anything that deploys, releases, or deletes, when the tool offers one. - Set `--yes` / `--non-interactive` deliberately and only where the action is genuinely safe โ€” @@ -91,7 +91,7 @@ tool list -o csv # structured columns for a spreadsheet or script > [!WARNING] > **Never pipe build, lint, or test output through a filter to make it shorter.** That is a > different situation and the rule there is the opposite โ€” see -> [`coding-dev.md` ยง2](./coding-dev.md). Structured output flags are for data; `grep` on +> [`coding-dev.md` ยง2](skills-public/coding-dev.md). Structured output flags are for data; `grep` on > diagnostics hides warnings. --- @@ -184,6 +184,6 @@ system, not scattered at the repository root. --- ## 8. Related Skills -- [`coding-dev.md`](./coding-dev.md) โ€” writing the code these tools build and test. -- [`code-languages/bash.md`](./code-languages/bash.md) โ€” writing the scripts themselves: +- [`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 2330165..d7da7ea 100644 --- a/code-languages/bash.md +++ b/code-languages/bash.md @@ -8,7 +8,7 @@ description: >- # Bash / Shell โ€” Rules & Preferences -Extends [`../coding-dev.md`](../coding-dev.md). Everything there applies; this adds shell specifics. +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 @@ -164,12 +164,12 @@ mistakes before a human does. Standalone utility scripts belong in a **dedicated, version-controlled scripts directory**, 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](../cli-tooling.md) for the reasoning and the pattern. +location. See [`cli-tooling.md` ยง5](skills-public/cli-tooling.md) for the reasoning and the pattern. --- ## 10. Related -- [`../coding-dev.md`](../coding-dev.md) โ€” the general rules this extends. -- [`../cli-tooling.md`](../cli-tooling.md) โ€” invoking other tools *from* these scripts: +- [`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`](./python.md) โ€” where a shell script should have become a Python script. +- [`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 87f1540..d84616c 100644 --- a/code-languages/c-cpp.md +++ b/code-languages/c-cpp.md @@ -8,7 +8,7 @@ description: >- # C / C++ โ€” Rules & Preferences -Extends [`../coding-dev.md`](../coding-dev.md). Everything there applies; this adds C/C++ specifics. +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 @@ -148,6 +148,6 @@ When exposing C/C++ to another language: --- ## 9. Related -- [`../coding-dev.md`](../coding-dev.md) โ€” the general rules this extends. -- [`rust.md`](./rust.md) โ€” the preferred language for new native work, and the usual consumer +- [`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 a935f83..8a2a3d6 100644 --- a/code-languages/csharp-dotnet.md +++ b/code-languages/csharp-dotnet.md @@ -8,7 +8,7 @@ description: >- # C# / .NET โ€” Rules & Preferences -Extends [`../coding-dev.md`](../coding-dev.md). Everything there applies; this adds .NET specifics. +Extends [`coding-dev.md`](skills-public/coding-dev.md). Everything there applies; this adds .NET specifics. --- @@ -150,5 +150,5 @@ interface, a type being renamed): --- ## 9. Related -- [`../coding-dev.md`](../coding-dev.md) โ€” the general rules this extends. -- [`bash.md`](./bash.md) โ€” for the release pipeline scripts around a .NET build. +- [`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 ccc6fb2..4f46e1b 100644 --- a/code-languages/go.md +++ b/code-languages/go.md @@ -8,7 +8,7 @@ description: >- # Go โ€” Rules & Preferences -Extends [`../coding-dev.md`](../coding-dev.md). Everything there applies; this adds Go specifics. +Extends [`coding-dev.md`](skills-public/coding-dev.md). Everything there applies; this adds Go specifics. --- @@ -153,5 +153,5 @@ CGO_ENABLED=0 go build -trimpath -ldflags="-s -w" -o bin/app ./cmd/app --- ## 10. Related -- [`../coding-dev.md`](../coding-dev.md) โ€” the general rules this extends. -- [`js-typescript.md`](./js-typescript.md) โ€” for the embedded frontend in a Go service. +- [`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 922c889..84699fa 100644 --- a/code-languages/js-typescript.md +++ b/code-languages/js-typescript.md @@ -9,7 +9,7 @@ description: >- # TypeScript / JavaScript โ€” Rules & Preferences -Extends [`../coding-dev.md`](../coding-dev.md). Everything there applies; this adds JS/TS specifics. +Extends [`coding-dev.md`](skills-public/coding-dev.md). Everything there applies; this adds JS/TS specifics. --- @@ -199,5 +199,5 @@ Attach an `AbortController` to every long-lived `fetch` and abort it in cleanup. --- ## 12. Related -- [`../coding-dev.md`](../coding-dev.md) โ€” the general rules this extends. -- [`bash.md`](./bash.md) โ€” for the build/release scripts around these projects. +- [`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 8c6ab48..3cb7adf 100644 --- a/code-languages/python.md +++ b/code-languages/python.md @@ -8,7 +8,7 @@ description: >- # Python โ€” Rules & Preferences -Extends [`../coding-dev.md`](../coding-dev.md). Everything there applies; this adds Python specifics. +Extends [`coding-dev.md`](skills-public/coding-dev.md). Everything there applies; this adds Python specifics. --- @@ -149,5 +149,5 @@ When talking to a rate-limited API (a chat platform, a store, a tracker): --- ## 10. Related -- [`../coding-dev.md`](../coding-dev.md) โ€” the general rules this extends. -- [`bash.md`](./bash.md) โ€” for the surrounding build and deploy scripts. +- [`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 a941b5f..376a89a 100644 --- a/code-languages/rust.md +++ b/code-languages/rust.md @@ -8,7 +8,7 @@ description: >- # Rust โ€” Rules & Preferences -Extends [`../coding-dev.md`](../coding-dev.md). Everything there applies; this adds Rust specifics. +Extends [`coding-dev.md`](skills-public/coding-dev.md). Everything there applies; this adds Rust specifics. --- @@ -193,5 +193,5 @@ dependencies builds and tests directly on the host, which is seconds instead of --- ## 11. Related -- [`../coding-dev.md`](../coding-dev.md) โ€” the general rules this extends. -- [`c-cpp.md`](./c-cpp.md) โ€” when bindgen/FFI crosses into a C library. +- [`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 68fb8d0..898f375 100644 --- a/coding-dev.md +++ b/coding-dev.md @@ -26,17 +26,17 @@ reasons attached, not style trivia โ€” most exist because ignoring them caused a > When in doubt about which mode you are in, **ask** โ€” it changes the answer on strictness, > file size, typing, and test policy all at once. -Per-language specifics live in [`code-languages/`](./code-languages/): +Per-language specifics live in [`code-languages/`](skills-public/code-languages/): | Language | Rules | | :--- | :--- | -| Rust | [`code-languages/rust.md`](./code-languages/rust.md) | -| TypeScript / JavaScript | [`code-languages/js-typescript.md`](./code-languages/js-typescript.md) | -| Bash / Shell | [`code-languages/bash.md`](./code-languages/bash.md) | -| Python | [`code-languages/python.md`](./code-languages/python.md) | -| Go | [`code-languages/go.md`](./code-languages/go.md) | -| C# / .NET | [`code-languages/csharp-dotnet.md`](./code-languages/csharp-dotnet.md) | -| C / C++ | [`code-languages/c-cpp.md`](./code-languages/c-cpp.md) | +| Rust | [`code-languages/rust.md`](skills-public/code-languages/rust.md) | +| TypeScript / JavaScript | [`code-languages/js-typescript.md`](skills-public/code-languages/js-typescript.md) | +| Bash / Shell | [`code-languages/bash.md`](skills-public/code-languages/bash.md) | +| Python | [`code-languages/python.md`](skills-public/code-languages/python.md) | +| Go | [`code-languages/go.md`](skills-public/code-languages/go.md) | +| C# / .NET | [`code-languages/csharp-dotnet.md`](skills-public/code-languages/csharp-dotnet.md) | +| C / C++ | [`code-languages/c-cpp.md`](skills-public/code-languages/c-cpp.md) | --- @@ -294,7 +294,7 @@ Run the **whole** gate, not the convenient part of it. A typical full gate: ## 13. Environment & Tooling -Full version in [`cli-tooling.md`](./cli-tooling.md); the essentials: +Full version in [`cli-tooling.md`](skills-public/cli-tooling.md); the essentials: - **Read ` --help` before using a CLI.** Do not guess flags, and do not write an ad-hoc script when an existing tool already does the job. @@ -312,4 +312,4 @@ Full version in [`cli-tooling.md`](./cli-tooling.md); the essentials: --- ## 14. Related Skills -- [`code-languages/`](./code-languages/) โ€” per-language rules that extend and specialize this document. +- [`code-languages/`](skills-public/code-languages/) โ€” per-language rules that extend and specialize this document.