BluscreamandClaude Opus 5
5aef9707d2
PHP was the one language with real code in two shapes here and no skill: a Composer library held at PHPStan level max, and a plain PHP-FPM application behind nginx with no framework. The rules come from reading both rather than from general PHP advice, so each one names the failure it prevents. The two halves differ enough to be separate sections. A library requires PSR interfaces and ships no implementation; an application's rules are about escaping, keeping the document root unwritable, atomic writes and sessions. Everything in §1-§8 applies to both. Three findings are worth the space they take because they were each paid for once already: `json_encode` with JSON_UNESCAPED_SLASHES into an inline <script> is an XSS hole, a web user that cannot write its own cache fails silently on every request, and inside the dev container the host's own `php` bridge shadows the real interpreter so every vendor/bin tool dies naming distrobox. docs(python): cover MCP servers, Red cogs and HA components, and correct three rules the owner's own code contradicts The skill described a toolchain and was silent on the four things most of this Python actually is. Three of its rules are also wrong in context, and the code is right: getLogger(__name__) puts a cog outside the red.* tree where Red's log controls apply; TaskGroup's cancel-on-first-error is the wrong default for fan-out over N providers, where the real pattern is a semaphore plus gather(return_exceptions=True); and the gate runs locally and through pre-commit, not through CI, which never runs under this account. Also: ruff ALL-minus-documented-ignores is the preferred shape rather than the explicit select list, lockfiles split by artifact type, and bare `python` and bare `pip` are different interpreters on this host. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
66 lines
5.6 KiB
Markdown
66 lines
5.6 KiB
Markdown
# Public Agent Skills
|
|
|
|
A collection of public, reusable agent skills, cheatsheets, and operational workflows for AI coding assistants and automation agents.
|
|
|
|
---
|
|
|
|
## 📂 Skills Index
|
|
|
|
| Skill File | Scope / Topics Covered |
|
|
| :--- | :--- |
|
|
| **[`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. |
|
|
| **[`afk-sleep-work.md`](skills-public/afk-sleep-work.md)** | Operating unattended and autonomously: continuous forward momentum, avoiding polling traps and deadlocks, host preservation and resource budgeting (disk, packages, processes), isolated tool provisioning, avoiding "last breath" traps on token/quota exhaustion, bypassing or driving GUI launchers, and wake-up checkpoints. |
|
|
|
|
### 🔤 Per-Language Rules ([`code-languages/`](skills-public/code-languages/))
|
|
|
|
| Language | Skill File | Highlights |
|
|
| :--- | :--- | :--- |
|
|
| **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, MCP/cog/HA framework rules |
|
|
| **PHP** | [`php.md`](skills-public/code-languages/php.md) | `strict_types` everywhere, PHPStan `level: max`, PER-CS 2.0 risky rules, `final readonly` value objects, PSR interfaces over implementations, escaping & unwritable document root |
|
|
| **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.
|
|
|
|
---
|
|
|
|
## ✍️ Skill Document Conventions
|
|
|
|
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.
|
|
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.
|
|
|
|
---
|
|
|
|
## 🛠️ Usage Across AI Agents & Tools
|
|
|
|
These skill documents are compatible across agentic developer assistants and environments:
|
|
- **Claude Code / Claude Desktop**: Symlink or reference in project instructions or memory.
|
|
- **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.
|