sync skills: add skill-maintenance skill + shared DRY references

- New skill: skill-maintenance (SKILL.md + 4 references: best-practices,
  dry-across-skills, sub-division, audit-checklist) encoding the Agent Skills
  spec rules, cross-skill DRY, and the f3s/rocky-vm-setup sub-division pattern.
- agent-task-management/references/verification-honesty.md: canonical home
  for the general verification-honesty discipline (linked from go-best-practices).
- blog-writing-style/references/gemtext-conventions.md: shared foo.zone
  gemtext conventions (linked from compose-blog-post, update-blog-post,
  blog-writing-style).
- blog-writing-style/references/patterns-and-examples.md: foo.zone LLM-pattern
  catalog + rewrite examples extracted from blog-writing-style SKILL.md.
- f3s/references/{console-jetkvm-shutdown,shelly-plug}.md: referenced by
  f3s/SKILL.md (previously untracked).

1 files changed, 97 insertions, 0 deletions

diff --git a/prompts/skills/skill-maintenance/references/best-practices.md b/prompts/skills/skill-maintenance/references/best-practices.md
new file mode 100644
index 0000000..86fe99b
--- /dev/null
+++ b/prompts/skills/skill-maintenance/references/best-practices.md
@@ -0,0 +1,97 @@
+# Skill Best Practices (Agent Skills spec + pi)
+
+Source: the [Agent Skills specification](https://agentskills.io/specification)
+and pi's `docs/skills.md`. The rules below are what to enforce when auditing a
+skill.
+
+## Progressive disclosure (the core model)
+
+Skills load progressively — take advantage of it:
+
+| Layer | Loaded | Target size |
+|-------|--------|-------------|
+| Metadata | Always in context at startup | ~100 tokens (name + description) |
+| Instructions | When the skill is activated (the full `SKILL.md` body) | **< 5000 tokens, < 500 lines** |
+| Resources | On demand only (`scripts/`, `references/`, `assets/`) | As small as focused |
+
+Keep `SKILL.md` under 500 lines. Move detailed reference material to separate
+files so the activated body stays small.
+
+## Frontmatter (required)
+
+| Field | Required | Constraints |
+|-------|----------|-------------|
+| `name` | yes | 1-64 chars; lowercase a-z, 0-9, hyphens; no leading/trailing hyphen; no consecutive hyphens. Pi relaxes "must match parent dir" for shared skill dirs. |
+| `description` | yes | 1-1024 chars; non-empty; what it does **and** when to use it. **Missing description ⇒ skill is not loaded.** |
+| `license` | no | Short license name or bundled file reference. |
+| `compatibility` | no | 1-500 chars; environment requirements (product, system packages, network). Most skills omit it. |
+| `metadata` | no | Arbitrary string→string map; use reasonably unique keys. |
+| `allowed-tools` | no | Space-separated pre-approved tools (experimental). |
+| `disable-model-invocation` | no | `true` hides skill from system prompt; requires `/skill:name`. |
+
+## Description best practices
+
+The description determines when the agent loads the skill. Be specific and
+include trigger keywords.
+
+Good:
+```yaml
+description: Extracts text and tables from PDF files, fills PDF forms, and merges multiple PDFs. Use when working with PDF documents or when the user mentions PDFs, forms, or document extraction.
+```
+
+Poor:
+```yaml
+description: Helps with PDFs.
+```
+
+This collection's convention: end descriptions with `Triggers on: <comma-separated phrases>.`
+
+## Structure
+
+```
+skill-name/
+├── SKILL.md          # required: frontmatter + instructions
+├── scripts/          # optional: executable code
+├── references/       # optional: detailed docs loaded on demand
+└── assets/           # optional: templates, images, data
+```
+
+Everything besides `SKILL.md` is freeform.
+
+### scripts/
+
+- Self-contained or document dependencies clearly
+- Helpful error messages
+- Handle edge cases gracefully
+- Common languages: Python, Bash, JavaScript
+
+### references/
+
+- Detailed technical reference, form templates, domain-specific docs
+- **Keep individual reference files focused** — agents load them on demand, so
+  smaller files mean less context consumed
+- One topic per file
+
+## File references
+
+Use relative paths from the skill root:
+
+```markdown
+See [the reference guide](references/REFERENCE.md) for details.
+Run the extraction script: scripts/extract.py
+```
+
+Keep file references **one level deep** from `SKILL.md`. Avoid deeply nested
+reference chains. (An index file like `references/storage.md` that links into
+`references/storage/*.md` is acceptable but at the limit — prefer flat.)
+
+## Validation
+
+Pi validates skills against the Agent Skills standard. Most issues warn but
+still load. **Exception: skills with missing `description` are not loaded.**
+Name collisions (same name from different locations) warn and keep the first.
+
+## Skill commands
+
+Skills register as `/skill:name`. Arguments after the command are appended as
+`User: <args>`. Toggle via `/settings` or `settings.json: { "enableSkillCommands": true }`.
\ No newline at end of file