Nweii Skills

nweii-skills

Reference context for Nathan's skills ecosystem. Read this before creating, editing, or migrating any skill in his environment.

The repos

Skills live in two paired repos:

• nweii/agent-stuff — public + internal-but-public skills. Cloned at ~/Developer/LLMs/agent-stuff/.
• nweii/agent-stuff-private — truly private skills (sensitive materials, personal workflows, confidential content). Pushed to a private GitHub remote.

Both repos share a core layout, with some folders specific to one:

/
├── skills/          # Skill folders
├── agents/          # Subagent definitions (public: inspiration set; private: backups)
├── zips/            # Auto-built per-skill zips for drag-into-Claude.ai (generated)
├── scripts/         # update-catalog.py + build-zips.py (run by the pre-commit hook)
└── templates/       # SKILL_TEMPLATE.md, RULE_TEMPLATE.md (agent-stuff only)

Both repos have a .githooks/pre-commit that, when a skill changes, regenerates the README.md catalog (update-catalog.py) and rebuilds the zips/ mirror (build-zips.py) into the same commit.

The zips/ mirror

Each skill is also packaged as a .zip (one top-level folder named after the skill, containing its files) for non-CLI user convenience. Key properties:

• Built locally by the pre-commit hook, not a GitHub Action — the zip lands in the same commit as the skill edit, and reverts with it.
• Deterministic — build-zips.py uses fixed timestamps, sorted entries, and git-tracked files only (so .DS_Store and other junk never get in). An unchanged skill produces a byte-identical zip, so editing one skill diffs exactly one zip; no churn.
• Self-healing — the hook wipes and fully rebuilds zips/ each run, so a deleted, renamed, or newly-internal skill drops its stale zip automatically.
• Per-repo scope — build-zips.py carries a ZIP_INCLUDE_INTERNAL constant: False in agent-stuff (general-purpose skills only — don't encourage dropping internal ones in unmodified), True in agent-stuff-private (every skill is personal, so zip all).

The agent-stuff README catalog also splits skills into a general list and an ### Internal section (the script's existing is_internal flag). The private README stays a flat list.

The agents/ folders

Subagent definitions (*.md), not installed by bunx skills — copy them into ~/.agents/agents/ by hand. In agent-stuff this is a small curated inspiration set (vault-reader, vault-writer) with a framing README; in agent-stuff-private it's version-controlled backups of Nathan's personal subagents.

Use the repos as a source of truth over local installs

All edits to a skill happen in the repo working copy (~/Developer/LLMs/agent-stuff/skills// or ~/Developer/LLMs/agent-stuff-private/skills//). The installed skill under ~/.agents/skills// is a downstream copy placed there by bunx skills add and overwritten on the next install — it isn't version-controlled and never reaches GitHub. If you find yourself reaching for ~/.agents/skills//SKILL.md, stop: edit the matching repo folder instead, then reinstall to sync the change down.

Installing and updating skills

Always install via bunx skills add, from the GitHub slug for every repo, public or private:

• Public (agent-stuff) → nweii/agent-stuff. Updates via bunx skills update.
• Private (agent-stuff-private) → nweii/agent-stuff-private. Cloning a private repo relies on an authenticated gh (it falls back to gh repo clone, then SSH); make sure gh auth status is logged in.
• Third-party → their GitHub slug.

Don't install private skills from the local clone path or an SSH URL — the slug works for private repos through gh and keeps the recorded source portable across machines.

To try a skill without installing it, bunx skills use -s generates a usage prompt.

Architecture: how the install is laid out

bunx skills add keeps one real copy of each skill in the canonical dir ~/.agents/skills//, then symlinks each agent's skills dir to it. So Claude Code sees ~/.claude/skills/ as a symlink pointing to ../../.agents/skills/.

• The real files live once, in ~/.agents/skills/. The agent dirs hold symlinks, not duplicate copies.
• Trashing the symlink at ~/.claude/skills/ leaves the canonical copy intact; trashing ~/.agents/skills/ removes the real skill.
• A ~/.claude/skills/ that is a real directory instead of a symlink is copy-mode drift — see the install command below for why it happens and how to avoid it.

On Nathan's MacBook, ~/.claude/skills is itself a directory-level symlink to ~/.agents/skills (readlink ~/.claude/skills to confirm on any machine). Under this layout per-skill symlinks never appear: every ~/.claude/skills/ is the canonical copy seen through the parent link, so it lists as a real directory. That is NOT copy-mode drift — do not "repair" it. Trashing ~/.claude/skills/ here deletes the real skill, and creating a per-skill symlink inside it produces a self-referencing loop. Check the parent with readlink before diagnosing anything about per-skill symlinks.

Install commands

The default install mode is symlink, but bunx only uses it when two or more agent directories are targeted. Installing to a single agent (-a claude-code alone) silently falls back to copy mode — it writes a real folder into ~/.claude/skills/ and skips the canonical ~/.agents/skills/ entirely. To get the symlink layout, add a second agent whose skills dir is the canonical ~/.agents/skills, so the real copy lands there and Claude Code gets a symlink. zed works for this and creates no stray agent dir (its global skills dir is ~/.agents/skills); cline, dexto, loaf, warp, and kimi-code-cli work the same way.

# Public agent-stuff
bunx skills add nweii/agent-stuff --skill  -a claude-code zed -g -y

# Private agent-stuff-private (clones via authenticated gh)
bunx skills add nweii/agent-stuff-private --skill  -a claude-code zed -g -y

# Third-party
bunx skills add vercel-labs/agent-skills --skill  -a claude-code zed -g -y

Scoping with -a matters either way: without it, bunx skills add spreads the skill into every agent directory it knows about, for tools that aren't used.

Updating an installed skill

bunx skills update -g works for public, non-internal skills (and third-party skills). It does not work for:

• Private-repo skills — update checks the GitHub tree over an unauthenticated API call and can't see a private repo, so it reports "Failed to fetch tree."
• internal: true skills (even in the public repo) — update's internal handoff filters them out and reports "Failed to update."

For both, refresh by re-running bunx skills add (which installs internal skills fine, since naming a skill with --skill opts it in):

bunx skills add nweii/agent-stuff-private --skill  -a claude-code zed -g -y

Repairing a copied (non-symlink) install

First check readlink ~/.claude/skills — if the skills dir is itself a symlink to ~/.agents/skills (as on Nathan's MacBook), real directories inside it are the canonical copies and there is nothing to repair. Otherwise: if ~/.claude/skills/ is a real directory rather than a symlink into ~/.agents/skills/, it was installed in copy mode. Reinstall it with the two-agent command above — that rebuilds the canonical copy and the symlink, and refreshes the skill from upstream in the same step (so a drifted local copy is reconciled to source, not preserved).

--skill takes the frontmatter name:, not the repo folder name. When the two differ, pass the frontmatter name. Bunx will silently install nothing if you pass the folder name in this case.

Cleaning up multi-agent spread

If a previous install spread to multiple agents, pass agents space-separated to a single -a flag (the comma-separated form does not parse):

bunx skills remove --skill  -a augment codebuddy cursor -g -y

Pushing changes

Commit freely in either repo working copy — that's local-only. Pushing is where the gate is:

• agent-stuff (public) — always get explicit user confirmation before git push. Public commits are world-readable on GitHub and feed the auto-generated catalog. Don't push opportunistically.
• agent-stuff-private — push as needed, no extra gate.

Writing conventions

Skill content gets read by a human as often as by an agent, so write it to be read. Sort the substance first (the instructions, gotchas, and structure), then make a separate succinctness pass over the finished draft: cut filler, merge split sentences, tighten wording. Drop words that don't earn their place, but don't compress the prose into something illegibly terse. If a trim makes a sentence harder to read, it went too far. Compactness should serve readability.

Keep procedure skills operational. When a skill exists to do something (write a note, scaffold a file, drive a tool) write the body as the steps to follow, in order, with the decision-points and gotchas inline. Lead with what to do, not with background or rationale the agent doesn't need. Defer anything it already knows or can read elsewhere (the vault's AGENTS.md, a sibling skill) rather than restating it. However, reference skills that exist to explain (a system, a set of conventions) may carry more exposition.

Skill content craft

When available, lean on the /writing-great-skills skill (user-invoked — type its name) for any new skill or non-trivial edit.

Essentials:

• Skills give agents more predictable behavior A skill exists to pull determinism out of a stochastic agent. The aim isn't to produce identical output, but to run the same process each time — or reliably understand important context.
• Lead with a completion criterion the agent can check. End a step (or a rule) on a condition that distinguishes done from not-done, and make it exhaustive where it matters ("every modified file accounted for", not "produce a change list"). Vague criteria invite the agent to stop early.
• Reach for leading words — a compact concept the model already holds from pretraining (tight loop, tracer bullet, red, fog of war) anchors a whole region of behaviour in one token by recruiting priors the agent already has. Prefer one strong word to a restated triad ("fast, deterministic, low-overhead" → tight). It sharpens both execution (same behaviour each time the word appears) and invocation (shared language across prompts/docs makes the agent fire the skill more reliably).
• Diagnose with the failure-mode names. When a skill misbehaves, name what's wrong: premature completion (ending a step before it's done — fix the completion criterion first, split the sequence only if that fails), duplication (same meaning in two places — costs tokens and inflates its apparent importance), sediment (stale layers that pile up because adding feels safe), sprawl (too long even when every line is live — cure with progressive disclosure and splitting), no-op (a line the agent already obeys by default — pays load to say nothing).
• Single source of truth. Keep each meaning in one authoritative place so changing behaviour is a one-place edit. On the pruning pass, run the no-op test sentence by sentence and delete whole sentences that fail rather than trimming words.

Cross-cutting habits for what goes in the body:

• Add what the agent lacks, omit what it knows. Spend tokens on project conventions, domain procedures, non-obvious edge cases, and which exact tool/API to use — not on explaining what a PDF or an HTTP request is. The test per line: would the agent get this wrong without it? If no, cut it.
• Provide defaults, not menus. When several tools or approaches work, pick one and mention alternatives briefly as an escape hatch, rather than listing equals the agent has to choose between.
• Match specificity to fragility. Be prescriptive — exact commands, "don't add flags" — where a step is fragile or order-dependent; give freedom (and say why) where variation is fine and judgment helps.
• Progressive disclosure. Keep SKILL.md to the core path (the spec targets /skills//`

1. Fix the description — wrap it in double quotes if it isn't already
2. Commit and push (private repo: ensure the remote is private)
3. Trash the local install: trash ~/.agents/skills/
4. Reinstall via bunx from the appropriate slug:

``bash # Public bunx skills add nweii/agent-stuff --skill -a claude-code zed -g -y # Private bunx skills add nweii/agent-stuff-private --skill -a claude-code zed -g -y ``

Future edits happen in the repo, then re-run bunx skills add (private or internal) or bunx skills update (public, non-internal) to sync the install.

The install dir is downstream, not source — if you suspect the install drifted before migrating, diff it against the repo and reconcile to the repo before reinstalling.

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: nweii
• Source: nweii/agent-stuff
• License: MIT

Install and usage instructions live in the source repository linked above.