AI
Building Great Agent Skills: The Missing Manual
- Tutorial hell, then framework hell, then skill hell. Hell = lots of new information without much help in figuring how to put things together or evaluate components.
- 4 things to consider: trigger (how it’s invoked), structure (composition), steering (telling the agent what to do), pruning (lean as possible).
- Skills are invoked manually (by the user) or by the model.
- Model-invoked skills have a cost in unpredictability. The model can choose a certain skill or it may not. By invoking manually you remove an entire class of problem.
- Tip 1: Decide if your skill is user-invoked (more cognitive load on you) or model-invoked (more context load on the LLM).
- Tip 2: Structure skills into steps (how to complete the procedure) and references (supporting information to help the skill do the steps).
- Tip 3: Make the SKILL.md as small as possible. Easier to maintain, audit. Reduces token costs. Having massive skill definitions is a symptom of some other problem.
- Tip 4: Look for content that can be moved into separate files that can be loaded only when needed.
- Tip 5: Use leading words (phrases to encourage the agent to follow a particular path).
- Tip 6: Increase legwork by hiding future steps. If you tell AI where the end is, it’s almost compelled to get to the end, meaning it can shortcut the work in required milestones before reaching that end.
- Tip 7: Don’t repeat yourself.
- Tip 8: Try removing parts of your skills and see if you get the same results.
Why AI Has Failed to Take Your Job Since 1976
There have been many advancements in machine learning (e.g., Mycin, Watson, LLMs) that ultimately fail(ed) to deliver a radical change. This video explains the main premise of Theory of Constraints, highlighting that bottlenecks go away; new ones pop up. The visualization of the pipe infrastructure is a good one: task, job, organization/environment, product-market fit, physical infrastructure, social infrastructure (including institutions, values, possible futures).
Software Development
Why Care About Agent Authored Code Quality
This post corrects the argument that software development has reached another layer of abstraction similar to how very few people write assembly code. The flaw is that compilers are deterministic; LLMs are not. Your prompt may produce correct code today, but may have flaws tomorrow. The author also mentions cost (tokens, time) and how well-architected code is not only good for humans, it’s good for AI. “Good architecture isn’t about making developers feel good about their code. It’s about minimizing the surface area that needs to change for any given requirement, making it easy to verify that a change is correct, and keeping each piece of the system focused on one thing. Those properties matter for human developers. They matter at least as much – and maybe more – for AI agents operating at scale.”
Software Architecture’s Biggest Enemy (Not What You Think)
- The ability to change your software is the single defining characteristic of its quality.
- Coupling is the enemy, but you can’t get rid of it.
- No coupling = parts can’t talk to each other (useless). Coupling is the connection that turns piles of separate parts into a working system.
- Strong coupling is acceptable if the thing you’re coupling to is fairly stable (e.g., SQL Server). Coupling to unstable things (e.g., your DB schema that’s being evolved) is a problem.
- Operational coupling — can’t operate without the coupling (e.g., app can’t start if DB isn’t running)
- Developmental coupling — two components must be changed together and requires coordination; gets more complicated as systems and teams grow in size and complexity
- Semantic coupling — two components share a concept (e.g., order, account), such that if a meaning changes in one component the other must change (and frequently tooling won’t warn you about this)
- Functional coupling — two parts of the system address the same problem in two different ways (e.g., validate email address)
- Incidental coupling — two parts are connected for no apparent reason
- Symptoms: slow builds, complex test setup, brittle tests, blocked teams, lockstep platform releases, long parameter lists
- Tools to cope with coupling: design, speed of feedback. CI helps here.
- Strategies to avoid disaster: compartmentalize your design (modular architecture), and get fast feedback via CI & monitoring.
- Start with CI first.
- Hide information behind APIs so your services can vary without breaking the contract.
- Guard boundaries between modules, services, and teams.
- Translate and validate external data at the edge.
- Announce, don’t command (event-based design).
- Consume parsimoniously, produce generously.
- Use messages unless the semantics are fixed.
- Tighten what’s stable, loosen what’s uncertain.
- Use TDD because it shows places where tests are hard to write.
- Decide what coupling to accept and manage.