refactor(skills): inline cross-links, drop Related sections, fix conventions

- 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 <repo>/<rel path> rule was appended after the wrong section
  last commit; moved into the list where it belongs.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
This commit is contained in:
BluscreamandClaude Opus 5 committed 2026-09-18 12:49:30 +02:00
1 parent 58525056a1
commit 5d96e69d2b
10 files changed
+30 -76

No files matched your search

+18 -11
View File
@@ -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 `<tool> --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 `<repo>/<relative path>`** — 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 `<tool> --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 `<repo>/<relative path>`** — 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.