find-skills

Robert's standing rule (2026-04-25): before writing non-trivial code in any domain - Apple frameworks, third-party API integration, build/CI tooling, design systems, debugging methodology - search the open Skills ecosystem first via npx skills find <kw>. If a battle-tested skill exists with a healthy install count, install it globally so the knowledge is loaded for this AND future sessions AND every subagent we dispatch.

The whole point: we are NOT alone in figuring out e.g. SwiftUI animation patterns or AVFoundation playback or macOS code-signing. People have already solved these problems and packaged the patterns. Reinventing is bandwidth that should have gone to Robert's actual feature work.

This skill exists because in one session we burned hours on:

• SwiftUI animation gotchas (fixable with dpearson2699/swift-ios-skills@swiftui-animation)
• AVAudioPlayer init paths (fixable with charleswiltgen/axiom@axiom-avfoundation-ref)
• macOS codesign + entitlement quirks (partial coverage in dimillian/skills@macos-spm-app-packaging)
• Stale binary debugging (would have been faster with obra/superpowers@systematic-debugging)

Every one of those was findable in <30 seconds with npx skills find.

Steps

1. Scope - no side effects

Identify the domain of the work you're about to do. Pick 2-3 specific keywords. Skip if the work is purely Snappy-internal (no external library, no platform API).

2. Search

npx skills find <keyword>

Multiple targeted searches beat one broad search. Examples:

• npx skills find swiftui animation
• npx skills find elevenlabs tts
• npx skills find macos codesign
• npx skills find systematic debugging

Results show install count - use it as a proxy for quality. >1K installs is a strong signal; >10K is gold.

3. Gate

Apply judgment:

• Does any result actually match the work? (Don't install Flutter skills

for Swift work.)

• Has the skill been recently updated? (Visit the skills.sh URL to verify.)
• Is the install count meaningful? (Be skeptical of single-digit installs

unless the publisher is authoritative - vendor-official skills like elevenlabs/skills/text-to-speech get a pass even with lower counts.)

4. Act - install globally

npx skills add <owner/repo@skill> -g -y

The -g is critical: it installs at user-level (~/.claude/skills/...) so the skill is available across every Claude session AND every subagent dispatched from this machine. Without -g, the install is project-local and the leverage is lost.

5. Log + eval

Append to memory the skill that was useful so future agents know it exists without re-searching:

echo "[$(date -u +%FT%TZ)] find-skills: installed <slug> for <reason> [FIXED]" >> state/log/agents-md-feedback.log

Update ~/.claude/projects/<project>/memory/feedback_use_findskills_first.md with the new install in the "Already installed" list.

Eval

The default failure mode is silent: we don't notice we should have searched. The eval is therefore manual review - Robert (or a future audit pass) checks recent feedback log entries against installed skills to spot reinvention.

Already installed (snappy-os, 2026-04-25)

These are loaded globally and available to every subagent without re-installation:

Known Pitfalls

• Don't install everything that matches. Each installed skill costs

context budget when loaded. Pick the one with the highest install count AND tightest match to the actual problem.

• Don't search for snappy-os-internal concepts. "snappy skill" or "PID

loader" won't find anything because those are our terms. Search for the GENERIC version of the problem ("self-correcting prompt", "feedback loop cli").

• Don't forget -g. Without the global flag, the skill is local to

the current cwd's Skills config. Subagents dispatched from a different cwd won't see it.

When to create your own skill

If a non-trivial pattern emerges from snappy-os work that COULD help others (e.g. our minimal-harnessing rule, our PID loader pattern, our snappy-os deploy script), consider scaffolding a publishable skill via npx skills init <name> so the knowledge flows back out. The marketplace gets stronger, future Claude sessions in any project benefit.

find-skills - loader

Per-turn rules for the find-skills skill. Full reference: state/skills/find-skills/SKILL.md. Do not skip these.

Critical Rules

_(no failures recorded yet - this skill has not produced hard-won rules. Read state/skills/find-skills/SKILL.md before invoking.)_

Commands

| ui dashboard | state/skills/find-skills/resources/ui.openui | |invoke: see state/skills/find-skills/SKILL.md Steps section |eval log: state/log/evals.ndjson (skill: "find-skills")

Self-Test

An agent reading this should correctly:

1. [ ] Know which lib/bin artifact backs this skill (or that it is prose-only)
2. [ ] Know what to write to state/log/evals.ndjson after invoking
3. [ ] Know the eval mode (auto / shape / manual) from the .md frontmatter

Self-report

If this loader fell short, append a line:

echo "[$(date -u +%FT%TZ)] find-skills: <what was missing>" >> state/log/loader-feedback.log

<!-- kernel-ok: historical attribution for the PID-loader pattern. -->

Self-correcting loader (PID feedback)

This is the rule that makes loaders learn. Ported from snappy-kernel, where it demonstrably worked: the snappy-dom-cartographer skill mapped Skool admin UI once, every later ship-agent inherited the full map for free.

Before you finish, do two things:

1. Fix gaps (P - proportional). MANDATORY. If this loader didn't cover your case - if you had to read another file, run an undocumented command, work around a wrong selector, or discover a quirk - you MUST attempt an Edit to this AGENTS.md before you log.

• Default action: edit this file. Surgical. Add the missing line, table

row, or code example where it belongs. No restructuring.

• Only LOGGED is allowed when: the fix needs >10 lines, spans multiple

files, or requires a structural rewrite. In that case the state/regen/drain.sh queue picks it up asynchronously.

• "I didn't have time" / "it's minor" / "the next agent will figure it out"

are NOT valid reasons. Minor gaps compound - that's the whole point of this loop.

• Concrete example of a valid P-fix: discover agent-browser screenshot

takes path positionally not as --output <path>. One line in a table. Edit it in. Do not just log it.

• The goal: the next agent never has to leave the loader.

2. Log the result.

echo "[$(date -u +%FT%TZ)] find-skills: <what was missing or fixed> [FIXED|LOGGED]" >> state/log/loader-feedback.log

• FIXED = you patched this loader inline (P-fix).
• LOGGED = too large for inline; the PostToolUse enqueue + Stop-hook drain

will rewrite the loader from scratch on next session-end.

Do not skip this. Every agent run must leave the system better than it found it. The loader is the setpoint; you are the sensor; the gap is the error signal; closing the gap is the correction.

OpenUI Resource

• Skill-owned OpenUI Lang resource: state/skills/find-skills/resources/ui.openui. Read it before rendering or editing this skill's generated component surface.
• Treat this resource as a first-class artifact of the skill, not a generic chat response. Improve it when the skill's user-facing output needs to become richer.
• System resources compose OpenUI primitives and inherit SnappyChat tokens. Use ui_contract: branded in SKILL.md only for deliberate platform or client visuals.