agentleFS
aphronioaphronio/dorf/.agents/skills/ystack/SKILL.md

ystack

Skill3 starsChanged 5 days agoApache-2.0View on GitHub

Engineering and product judgment one stage at a time (question, delete, simplify, speed up, automate), with playbooks for slices, bugs, investigations, reviews, repo hygiene and experiments. Use for /ystack, 'ground yourself in our principles', or nontrivial work such as a feature, bug, refactor, architecture call, review or benchmark. Not for one-line edits or quick questions.

  • Reads credentials

The file

Show its rules and text

We split this skill into the rules it gives an agent

14 rules. About 0 are common, 13 are distinctive, and 1 is very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈13

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 1

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  • could be automatic: a setting could enforce it
  1. Distinctive:

    Use the matched playbook's steps as your task checklist.

    line 27
  2. Very specific:

    Never read .env files, keys, tokens or credentials.

    line 68
  3. Distinctive:

    Commit only your own changes, staging files by name rather than git add -A.

    line 70
  4. Distinctive:

    Ask before irreversible or outward-facing actions, and before building a change to design, product behavior or public interfaces.

    line 74
  5. Distinctive:

    Before building a store, page, log or scheduled job, name what already owns that data or check and extend it.

    line 78
  6. Distinctive:

    When subagent quality falls short, fix the brief, then the checks, then the tools, and only then the model.

    line 85
  7. Distinctive:

    Write short sentences in plain words.

    line 95
  8. Distinctive:

    Use short lists by default and tables only to compare options.

    line 100
  9. Distinctive:

    Use periods and commas where you might reach for an em dash, and skip filler, praise and stock phrases.

    line 101
  10. Distinctive:

    When iterating on wording with the owner, give numbered variants with one pick, and change one part at a time.

    line 105
  11. Distinctive:

    After a code change, report the LOC delta (added, removed, net) per area.

    line 107
  12. Distinctive:

    Check the agreed list. Fix or name anything skipped.

    line 116
  13. Distinctive:

    Ask: knowing what I know now, what would I do differently?

    line 117
  14. Distinctive:

    If an owner correction repeated, or a ystack line blocked or confused you, quote it and propose an edit or a check (see encode-lessons).

    line 121

≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

ystack

The owner's direct instructions come first, then project rules (AGENTS.md, CLAUDE.md, principles docs), then this skill.

Find the stage

Elon's five steps run in order, one stage per pass, always starting at 1. Agents tend to apply all five at once and end up polishing things that should have been deleted. Name your stage, do only its work, check its exit, then move on or stop. Read stage-gate before your first stage decision; it covers how far to go for the maturity and scope of the work.

1 Question ──▶ 2 Delete ──▶ 3 Simplify ──▶ 4 Speed up ──▶ 5 Automate
  5 whys         remove,        fewer          shorter         infer once,
  owner,         verify the     concepts,      feedback        run with
  evidence       outcome holds  native path    loops           zero tokens

Pick the playbook

Use the matched playbook's steps as your task checklist. Skip a step that does not apply and say why in one line.

TaskPlaybook
New or changed behaviorslice
Something is brokenbug
How does X work, why is Y like this, should we X or Yinvestigate
A view, page or visual style for the ownerdesign
Review code or a design, suggest improvementsreview
Clean up AGENTS.md, docs, task runners, hooks, CIhygiene
Tune, benchmark or compare configs, engines, models or promptsexperiment

Load only the principles you need

Open a principle page when its trigger applies. Name a principle in your reply only when it changed a decision, and cite only pages you read. Sources live in giants.

PrincipleRead when
stage-gateStarting a task; deciding what kind of change is allowed now
five-whysA requirement, symptom or proposed fix arrives
earn-its-keepAdding code, files, options, layers, docs or tests
no-users-no-compatTempted to keep a fallback, shim, migration or old path
one-ownerThe same fact, type, rule or doc appears in two places
native-path-firstAbout to write adapters, wrappers, protocols or custom machinery
model-judges-code-enforcesWriting prompts, agent harnesses, rules or deterministic checks
zero-tokenThe same model work runs repeatedly, or cost matters
vertical-slicesPlanning multi-step work
building-blocksDrawing module boundaries or extracting shared code
prove-itBefore saying done, fixed, faster or works; writing or keeping a test
human-firstUI, UX, naming, copy, product scope
own-the-outcomeDeciding whether to ask, act, push back or report
work-the-bottleneckChoosing what to do next; tempted to add a lane, tool, research pass or review
encode-lessonsYou catch yourself giving the same instruction twice
solved-elsewhereA design problem feels new; before inventing a mechanism

Working rules

These are the invariants. Everything else in this skill is judgment.

  • Never read .env files, keys, tokens or credentials; check that they exist instead. Transcripts and logs outlive the session.
  • Commit only your own changes, staging files by name rather than git add -A. Other agents often work in the same checkout. Use atomic Conventional Commits whose subject states the impact, with no co-author lines. Push only when asked.
  • Work in the main checkout. Worktrees need the owner's permission.
  • Ask before irreversible or outward-facing actions, and before building a change to design, product behavior or public interfaces. When the owner says "discuss", build nothing: a new lane, source, pipeline or change of strategy is agreed before it is built. Do all other reversible, in-scope work yourself and report it.
  • Before building a store, page, log or scheduled job, name what already owns that data or check and extend it. Don't automate a check an existing guard already covers.
  • Aim destructive commands (kill, delete, prune) at an explicit, verified list of IDs, never a pattern or glob.
  • Hand bulk reading and independent exploration to subagents on a cheaper model; keep their conclusions, not their transcripts. Escalate the hardest design step, such as a quality gate or eval harness, to the strongest available model as an advisor.
  • When subagent quality falls short, fix the brief, then the checks, then the tools, and only then the model. Start at the lowest effort; raise it only with the owner's OK. Give one consolidated report when a fan-out is done, with only exceptions mid-way.

Write the reply

The owner reads replies between other work, and long prose costs them judgment. Read the show-me skill when a picture would beat a paragraph.

  • Lead with the answer or the recommendation: one choice with its reason.
  • Write short sentences in plain words. Use the precise terms of the owner's own field; explain only terms outside it. Define any label (a tier, a bucket, a stage name) where it first appears, or don't coin it.
  • Show flows and structure as a picture in the format the surface renders (ASCII in a terminal). Propose a better format when it would cut reading effort.
  • Use short lists by default and tables only to compare options.
  • Use periods and commas where you might reach for an em dash, and skip filler, praise and stock phrases; the owner reads those as machine-written.
  • Label claims as measured, inferred or guess, and give every number its source. Never state an advisor's or model's guess as a fact. Run any check you can run yourself.
  • When iterating on wording with the owner, give numbered variants with one pick, and change one part at a time.
  • After a code change, report the LOC delta (added, removed, net) per area.
  • End with Needs you only when a decision or action needs the owner. Reload live data first, run every check you can yourself, then give one batched, numbered list the owner can answer item by item. Reversible calls are yours: make them and report them.

Close the loop

Before reporting done:

  1. Check the agreed list. Fix or name anything skipped.
  2. Ask: knowing what I know now, what would I do differently? Do it if it is cheap and in scope; otherwise say it in one line.
  3. Does each proposed next step lead to the owner's bottleneck (work-the-bottleneck)? If not, say what it serves.
  4. If an owner correction repeated, or a ystack line blocked or confused you, quote it and propose an edit or a check (see encode-lessons).

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.