Skills

Skills is the set of instructions I maintain for my agents. Much of it is about the work around writing code. I need to agree on what to build, understand the choices, and see what the result will look like before an agent starts implementing it.

The repository began with a discovery skill and grew through use. I later retired the previous catalog so each skill could return only after proving useful. The current catalog separates engineering work from general skills such as asking hard questions or rewriting unclear prose. Each skill can be installed on its own.

The main workflow starts with shape. The human and agent agree on one spec with examples that define success. The examples also say how to prove the behavior. Then deliver writes the acceptance tests, watches them fail for the missing behavior, and implements it. refine reviews the working change with fresh eyes before ship takes it to a pull request. The human merges.

I shortened that workflow after it had grown into a much longer delivery chain. One spec replaced separate documents that repeated the same intent. Acceptance tests keep the behavior concrete while the agent works on the implementation. There is less value in another document describing completion than in evidence that the agreed example actually works.

For visual questions, I want to see alternatives. The prototype skill asks for different directions in a realistic product setting. The options use the same content and scenarios, so I can compare the design without also comparing different interpretations of the problem. I choose while looking at something I can use.

A later change came from a design I had accepted before I understood it well enough. I got its diagram after accepting the architecture and spent several rounds correcting how the documents explained it. That became walkthrough, which renders the design as a self-contained HTML page. The Markdown remains the source for agents. The page is for the human who needs to understand and accept it.

Maintaining the catalog also means removing instructions. A new failure does not automatically deserve another rule. The lifecycle asks whether an existing rule can be made clearer or more general, and whether another instruction has become redundant. A retired skill is deleted; git keeps its history.

The same preference appears in retro. It records evidence from a run and looks first for a fix in the project, such as a type or an executable check. A rule in a skill costs attention in every project that loads it. The current catalog includes maintenance and debugging skills too, while newer work such as walkthroughs and program design stays in the beta group until it has had more use.