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:
1 parent
58525056a1
commit
5d96e69d2b
10 files changed
+30
-76
No files matched your search
@@ -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.
|
||||
Reference in new issue
Block a user