2 posts tagged with "software-engineering"

Meta Description: Matt Pocock's "skills" repo hit 26K+ stars in days — a curated set of agent skills for planning, TDD, refactoring, and architecture. Here's what it means for real engineering workflows.

The Problem: AI Agents That Don't Think Like Engineers​

Most AI coding assistants fall into the same trap. You describe what you want, and they immediately start writing code. No planning. No questioning. No validation. It's "vibe coding" — and it produces the kind of software that looks right but falls apart under pressure.

Matt Pocock — the TypeScript educator behind Total TypeScript — dropped an open-source repo this week that takes a fundamentally different approach. Called simply skills, it's a collection of reusable agent skills designed for real engineering, not casual code generation.

The repo gained over 26,000 stars in its first week. That's not hype — that's developers recognizing a missing layer in their AI workflows.

What Are Agent Skills?​

If you've used Claude Code, you know about .claude directories — configuration files that shape how the AI agent behaves in your project. Skills take this further. They're self-contained instruction sets that give an AI agent a specific workflow, not just knowledge.

Think of it this way: a system prompt tells an agent what it knows. A skill tells an agent what to do — step by step, with guardrails, in a repeatable way.

Matt Pocock's collection targets the phases of development where most AI tools fall short: planning before code, structured refactoring, and disciplined testing.

The Planning & Design Skills (Think Before You Code)​

This is where the collection shines brightest. These five skills force the agent to slow down and think:

• to-prd — Takes your conversation context and synthesizes it into a proper Product Requirements Document, filed as a GitHub issue. No back-and-forth interview. The agent reads what you've already discussed and writes the spec.

• to-issues — Breaks a PRD or plan into independently grabbable GitHub issues, sliced vertically (each one delivers user value on its own). This alone solves one of the biggest problems in AI-assisted development: the agent tries to do everything at once.

• grill-me — The agent relentlessly interviews you about your plan or design. It doesn't stop until every branch of the decision tree is resolved. It's like having a senior engineer who won't let you merge until you've answered all the hard questions.

• design-an-interface — Generates multiple radically different interface designs for a module using parallel sub-agents. Instead of the first idea that comes to mind, you get options to compare.

• request-refactor-plan — Walks you through a refactor via interview, creates a detailed plan with tiny commits, and files it as a GitHub issue. The plan itself is valuable documentation.

The Development Skills (Code With Discipline)​

Once planning is done, these skills enforce engineering best practices:

• tdd — Test-driven development with a strict red-green-refactor loop. Features get built one vertical slice at a time. The agent writes a failing test, makes it pass, then refactors. This is how TDD is supposed to work, and most developers never do it manually. With an agent enforcing the loop, it actually happens.

• triage-issue — When a bug comes in, the agent explores the codebase, identifies the root cause, and files a GitHub issue with a TDD-based fix plan. No more rubber-ducking a stack trace alone at 2 AM.

• improve-codebase-architecture — The agent reads your CONTEXT.md and docs/adr/ (Architecture Decision Records) to find opportunities for deepening — making the codebase's structure better reflect its domain. It's like a periodic architecture review that actually produces action items.

Why This Matters for Engineering Teams​

The real insight here isn't any single skill. It's the philosophy: AI agents should enforce process, not skip it.

Here's what that looks like in practice:

1. You talk through an idea with your agent
2. to-prd captures it as a proper spec
3. grill-me stress-tests the spec
4. to-issues breaks it into grabbable work items
5. tdd implements each one with test-first discipline
6. triage-issue handles bugs the same way

Every step has structure. Every step produces artifacts (GitHub issues, test files, PRs) that persist beyond the conversation. The agent isn't just writing code — it's participating in your engineering workflow.

Getting Started​

Each skill installs with a single command:

npx skills@latest add mattpocock/skills/<skill-name>

They work with Claude Code out of the box. The npx skills CLI handles the setup — adding the skill's instructions to your .claude configuration.

If you're using other agent frameworks (like OpenClaw, Cursor, or Windsurf), the skills are just markdown files. You can read the source and adapt the patterns to your setup. The workflows are framework-agnostic; only the installation method changes.

The Bigger Picture: Agent Skills as Infrastructure​

This repo represents something larger than a collection of prompts. It's evidence that agent skills are becoming infrastructure — the same way linters, formatters, and CI pipelines became standard.

Consider the parallels:

• Prettier standardizes formatting. Everyone on the team writes code that looks the same.
• Husky + lint-staged enforces checks before commits. Nobody skips the linter.
• Agent skills standardize how AI participates in your process. The agent doesn't just generate — it follows a workflow.

As AI coding tools become ubiquitous, the teams that differentiate won't be the ones using AI the most. They'll be the ones using AI the most disciplined way. Skills are how you encode that discipline.

FAQ​

Q: Do these skills only work with Claude Code? A: They're designed for Claude Code's skill system, but the underlying patterns are markdown-based and framework-agnostic. You can adapt them for any AI coding assistant that supports custom instructions.

Q: Which skill should I start with? A: Start with grill-me. It's the fastest way to see the difference between "AI that writes code" and "AI that thinks through problems." Run it on any design decision you're currently wrestling with.

Q: Are agent skills the same as custom system prompts? A: No. A system prompt sets context and personality. A skill defines a repeatable multi-step workflow with specific inputs, outputs, and guardrails. It's closer to a CI pipeline than a prompt.

Q: Can I create my own skills? A: Yes — the repo includes a write-a-skill skill that teaches the pattern. Matt Pocock also runs a newsletter at aihero.dev where he shares new skills and updates.

Overthinking doesn't look like procrastination. It looks like productivity. You're researching, reading, exploring prior art, comparing tools. It feels like work — because technically it is. But your project isn't moving forward. The code isn't shipping. And by the time you realize what's happening, you've spent hours (or weeks) going nowhere.

Kevin Lynagh, a software engineer and toolsmith, wrote a brilliant essay on this exact trap. His diagnosis is sharp: the root cause isn't laziness or lack of skill — it's unclear success criteria combined with an instinct to research before building.

This article breaks down why overthinking and scope creep are the silent killers of software projects, and what you can actually do about it.

The Two Outcomes of Every Project Idea​

Every project idea tends to go one of two ways:

1. You just do it. You build it, make minor revisions, and it turns out roughly how you imagined. You ship. You're done.
2. You start researching. You look for prior art. There's a lot of it. The scope broadens. You start wondering if you should build on top of existing solutions. Or maybe you should just use the popular thing. But you could do better, if you invested more time. But you don't want to maintain something big. And now you've spent hours without shipping anything — or experiencing the joy of creating something.

Outcome #1 is obviously better. The question is: what determines which path you take?

Fuzzy Success Criteria Is the Root Cause​

The pivotal factor is how well you've internalized your success criteria before you start.

When Lynagh wanted to build a kitchen shelf with a friend, the success criteria was crystal clear: make a shelf for my exact kitchen, and have fun doing woodworking with a friend. Done in a weekend. No overthinking.

But when he went down a rabbit hole researching structural diffing tools, he spent four hours reading about PhD-level tree diffing algorithms before remembering his actual goal: build a nicer diffing workflow for myself in Emacs. Estimated time: four hours. He spent those four hours researching instead of building.

The pattern is clear: fuzzy goals invite scope creep. When you can't articulate exactly what "done" looks like, your brain fills the void with more research, more comparison, more planning.

This is especially dangerous for founders and indie developers who wear multiple hats. You don't have a product manager telling you to stop researching and start shipping. You are the scope creep.

The Conservation of Scope Creep​

Here's a particularly painful observation from Lynagh's essay: when he used an LLM to help build a fuzzy file search tool, the LLM found a great library (Nucleo) that had extra functionality — anchor-based matching. This triggered a chain of "what if" questions:

• What if anchors worked differently for file paths?
• What if we anchored to path segments instead of lines?
• What about handling slashes in anchored queries?

Several hours of design work and code later, he realized: he had never once wished his original tool had anchor functionality. He threw it all out.

This is what Lynagh calls a "conservation law" of software development: any increase in programming speed (from AI tools, better libraries, faster languages) will be offset by a corresponding increase in unnecessary features, rabbit holes, and diversions.

The LLM didn't cause the scope creep. But it accelerated it. Faster code generation means you can go down rabbit holes faster — and dig yourself deeper before realizing you should have stopped.

Why Smart People Are the Most Vulnerable​

There's a painful irony here: the people most susceptible to overthinking-driven scope creep are often the most capable engineers.

Why? Because they can see the broader implications. They can imagine the edge cases. They can design elegant abstractions. And all of that capability becomes a liability when it's deployed against a problem that just needed a simple, direct solution.

Lynagh describes his own long-running interests — designing a programming language that fuses Clojure and Rust, building interfaces for hardware prototyping, creating a CAD language — as being stuck in the research phase for hundreds of hours. He's learned a lot by reading. But he hasn't shipped.

His self-diagnosis: "My inner critic (fear of failure?) is silencing my generative tendencies, keeping me from the much more enjoyable (and productive!) learning by doing."

How to Actually Ship: Practical Anti-Overthinking Strategies​

1. Write Down Your Success Criteria Before Starting​

Not in your head. On paper. One to three sentences that define "done."

Example: "A CLI tool that diffs two files by function/class, showing added/removed/changed entities. Must work with TypeScript and Python. I use it myself in Emacs."

If you can't write it in three sentences, you don't have clear enough criteria yet. Don't start building until you can.

2. Apply the YAGNI Rule Aggressively​

"You Ain't Gonna Need It" isn't just a software design principle — it's a project survival strategy.

Every time you think "it would be nice if...", ask: "Do I have a concrete use case for this right now?" If the answer is no, skip it. You can always add it later. You can rarely undo the time spent building things nobody needed.

3. Set a Time Box​

Before starting, estimate how long the task should take if you scope it correctly. Then set a hard deadline. If you estimated four hours and you're two hours deep into researching alternatives, you've already failed the time box. Stop researching and start building.

4. Default to Building, Not Researching​

Research is valuable. But it has diminishing returns fast. The first 30 minutes of research will give you 80% of what you need. The next four hours will give you the remaining 20% — and probably introduce enough scope creep to kill the project entirely.

When in doubt, build first. You'll learn more from a working prototype than from reading ten blog posts about how other people solved similar problems.

5. Embrace the "Clueless 20-Year-Old" Mindset​

Lynagh's closing advice: embrace your inner clueless 20-year-old and just do things. Some will turn out "obviously bad" in hindsight. But you'll come out ahead on net — because the experience of building, failing, and iterating teaches you more than the experience of endlessly planning and never shipping.

This isn't about being reckless. It's about recognizing that the cost of a bad first version is almost always lower than the cost of never shipping.

The Real Cost of Overthinking​

Every hour spent researching instead of building is an hour you could have had a working prototype. Every feature added to the scope is a feature that delays the ship date. Every "what if" question that doesn't have a concrete user behind it is scope creep in disguise.

The projects that succeed aren't the ones with the most features or the most elegant architecture. They're the ones that shipped. That got into users' hands. That generated feedback and iteration data.

If you're building something — a startup, a side project, a tool for yourself — the single most impactful thing you can do today is clarify what "done" looks like, resist the urge to broaden the scope, and start building.

The enemy of shipped product isn't laziness. It's perfectionism in disguise.

FAQ​

Q: How do I know if I'm overthinking vs. doing necessary research? A: If your research has a clear stopping point tied to a specific decision, it's necessary. If you're "just browsing" or keep finding new rabbit holes, you're overthinking. Set a time limit: 30 minutes of research, then decide and move on.

Q: What's the difference between good scope and scope creep? A: Good scope addresses a real user need you can articulate in one sentence. Scope creep addresses a hypothetical need — "what if someone wants to..." — without a concrete use case behind it.

Q: How do AI coding assistants affect scope creep? A: They accelerate it. LLMs can generate scope creep faster than you can think through whether you actually need it. Be extra vigilant about success criteria when using AI tools — they'll happily build features you never asked for.

Q: Is overthinking always bad in software development? A: No. For infrastructure decisions, security architecture, and data model design, careful thinking is essential. The key is knowing which category your current task falls into. Most feature work and prototypes benefit from moving fast, not thinking deep.

About the Author​

Arkin is a startup founder and developer building Orbits Studio, a clip farming marketplace connecting everyday creators with brands. He writes about software engineering, startup lessons, and building in public.