# 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. |
| **[`software-vision.md`](skills-public/software-vision.md)** | Starting from a software idea: turn it into a requirements checklist, search the web first (projects, forks, skeletons, libraries, user reviews), then merge in training-data recall checked against current sources, shallow-clone promising candidates to a temp dir to check them, then present use / extend / fork / start-fresh options before building anything. |
| **[`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. |
| **[`android-backup-restore.md`](skills-public/android-backup-restore.md)** | Extracting/backing up/restoring Android data by access tier before a wipe or migration: EDL/firehose & bootloader, custom recovery (TWRP/OrangeFox/CWM), root, device-owner, Shizuku, plain ADB, and on-device apps; FBE decryption limits, per-partition dumps (userdata, EFS/modem/IMEI, persist), SELinux/UID-correct restores, the death of `adb backup`, and app-specific data (WhatsApp, Signal, TOTP/Keystore) that does not survive. |

### 🔤 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 |
| **Lua** | [`lua.md`](skills-public/code-languages/lua.md) | pin the dialect first, `luac -p` + luacheck as the only gate, locals over globals, `pcall` at the boundary, `#t`/pattern traps, embedded & HavokScript hosts |
| **GSC** | [`gsc.md`](skills-public/code-languages/gsc.md) | compile off-engine with `gsc-tool --mode comp`, `isdefined` on everything external, `endon` before the first wait, per-frame budget, precache at load, level-state side effects |

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.