agentleFS
Sign inStart free
RecusiveRecusive/Skills/blueprint-first/SKILL.md

blueprint-first

Skill2 starsChanged 8 months agoMITView on GitHub

Guide any engineering task — building, fixing, expanding, refactoring, investigating — like a senior engineer at a big company. Teaches the thinking process, not just rules. Study first, plan properly, implement with discipline. Use this skill whenever the user mentions "follow the patterns", "replicate the architecture", "proper system design", "production-ready plan", "do it properly", "don't hardcode", "build it like they would", "find the root cause", "fix it properly", "don't just patch it", "expand this feature", "refactor this", "how does this work", or asks for any engineering work to follow existing conventions exactly. Also trigger when the user is frustrated that previous work was half-baked, used hardcoded values, created workarounds, suppressed lints, or didn't follow the repo's architecture. Even if the user just says "plan this properly" or "I want it done right" or "check the codebase first", use this skill. When in doubt, prefer this skill — studying the codebase first never makes anything worse.

The file

We split this skill into the rules it gives an agent

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

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈10

    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
  1. Distinctive:

    Do NOT write code, propose fixes, or suggest architecture until you have studied the relevant code and documented what you found.

    line 17
  2. Distinctive:

    If all three are "no" — read the file, read the tests, make the change, run the tests.

    line 28
  3. Distinctive:

    If unsure: Start with Investigation.

    line 44
  4. Very specific:

    Read references/engineering-stages.md.

    line 50
  5. Distinctive:

    "What does this code actually do?": Read the file.

    line 70
  6. Distinctive:

    "What tests exist?": Read them.

    line 71
  7. Distinctive:

    "What's the closest analog?": Use it as your template.

    line 72
  8. Distinctive:

    "What do the conventions say?": Read CLAUDE.md. Follow it.

    line 74
  9. Distinctive:

    Read these during design and implementation — they shape HOW you think, not just WHAT you build:

    line 81
  10. Distinctive:

    If no, the work isn't done.

    line 94
  11. Distinctive:

    Do not jump to implementation without a plan: If the user wants to proceed:

    line 98

≈ “Common” is an estimate: at least 1 in 5 of the 350,495 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

Proper Engineering

Think like a senior engineer. Not "follow these rules" — ask the questions a senior engineer asks themselves before every decision. The rules emerge from the thinking.

Why This Exists

You optimize for speed. You jump to solutions. A senior engineer slows down and asks questions first. This skill teaches that thinking process.

<HARD-GATE> Do NOT write code, propose fixes, or suggest architecture until you have studied the relevant code and documented what you found. Reading the codebase is not prep work — it IS the first deliverable. </HARD-GATE>

Before Anything: Is This Trivial?

  • "Does this change affect anything beyond the file I'm editing?"
  • "Could this break something I'm not looking at?"
  • "Do I fully understand the context, or am I assuming?"

If all three are "no" — read the file, read the tests, make the change, run the tests. The moment anything surprises you, escalate to the full workflow.

What Kind of Work Is This?

Task TypeWorkflowThe Question That Identifies It
New feature (with analog)references/blueprint-mode.md"Does something like this already exist that I can study?"
New feature (no analog)references/vocabulary-mode.md"Nothing similar exists — how does this repo introduce new concepts?"
Bug fixreferences/bug-fix.md"Something's wrong — where does the data first become incorrect?"
Expand existing featurereferences/expanding-features.md"This works today — how do I add to it without breaking what exists?"
Refactorreferences/refactoring.md"The structure needs to change — how do I prove behavior is preserved?"
Investigationreferences/investigation.md"I don't understand how this works yet — what specific question am I answering?"
Remove/deprecatereferences/removing-code.md"This needs to go — what depends on it that I can't see?"

If unsure: Start with Investigation.

Engineering Stages

Read references/engineering-stages.md. For each stage, ask: "Does this feature have implications here?" Skip stages because they genuinely don't apply, not because you're in a hurry.

Implementation: The Questions That Matter

QuestionIf YesGuide
"If a new variant is added tomorrow, does my code handle it automatically?"If not → you're hardcodingreferences/never-hardcode.md
"Am I fixing this at the source, or patching where I noticed it?"If patching → pipeline is brokenreferences/no-inline-workarounds.md
"Does this codebase already have infrastructure for this?"If yes → extend itreferences/reusing-patterns.md
"Where do files like this live? How are they named?"Don't guess → lookreferences/file-structure.md
"Why is this lint firing?"It's telling you something realreferences/lint-and-quality.md
"If this breaks, how quickly will I know?"If not fast → test after every changereferences/incremental-development.md
"Am I rationalizing a shortcut?"If yes → stopreferences/gotchas.md

Before Writing Any Code

  • "What does this code actually do?" Read the file.
  • "What tests exist?" Read them.
  • "What's the closest analog?" Use it as your template.
  • "Who depends on this?" Trace the callers.
  • "What do the conventions say?" Read CLAUDE.md. Follow it.
  • "How do I verify this works?" Know the command. Run it after every change.

Quality of Thinking

Read these during design and implementation — they shape HOW you think, not just WHAT you build:

GuideWhat It Teaches
references/auditors.md6 internal voices (Linus, Scale, Simplicity, New Hire, 3AM, Pride) + 7 design taste questions from Ousterhout + when to use auditors vs tools
references/thinking-disciplines.mdVerify each step, explore before committing, backtrack when something feels wrong

The Final Question

"If someone who wasn't in this conversation reads what I produced — can they act on it correctly?"

If no, the work isn't done.

Do not jump to implementation without a plan. If the user wants to proceed:

  • TDD decomposition → writing-plans
  • Direct execution → executing-plans or subagent-driven-development
  • Audit first → plan-review-board or audit-plan

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.

Check your setup, free