Agent Instructions

[Shrinks99]

Motivation

I have a lot of component docs pages to write! Much of this work involves checking the component, noting down all the properties and slots, documenting various states, and formatting this into MDX flavoured Markdown files. This is somewhat time consuming, not novel work in any way... and therefore not a bad thing to try and throw at Claude!

LLMs aren't always consistent about their formatting choices — what is bold in one list may not be bold in another similar list on a different document. The component library is a prime example of a very rigidly structured docs site. Each component has a corresponding docs page, and we'd do well to keep the format of each page consistent for developers (and agents) referencing implementation guidelines.

While I still won't be using Claude to author written work that is created with the aim of sharing my perspective (like this post!), these docs aim to be an objective reference and are not really a good medium for personal expression. Many of the differences between what Claude would generate and what I might write unassisted seem to be able to be codified into a skill file with a good template to follow.

Changes & Future Plans

To this end, I've created a docs template along with some rules for writing each section in a skill. I've also written an AGENTS.md file and symlinked CLAUDE.md to it for compatibility with other coding agents that follow the standard. I haven't tested this with component creation just yet (I expect there is still more to do with the create-component skill) but I have committed an example docs page made with this workflow for Alert.

TL;DR, the robot did a good job, but there were still a few changes that I wanted to make. While the skill file guided the LLM away from spiraling into a large wall of text (the unedited publishing of which, I find, can deteriorate trust built between the author and reader). It wasn't perfect right out of the gate, the "overview" section at the top of each page is a place where I suspect I will be making the most changes as it will contain guidelines for component usage — though some of this I'll continue to try and codify in create-component).

I've included separate commits with Claude's one shot attempt and my revisions. The changes for this component were pretty minor which is exciting!

I may not split future commits up this way, but I won't be committing future docs changes without review. If you see large one-shot file additions from me in the future, expect that I have edited them for consistency, design intent, and proofing before pushing and I would appreciate if others did the same.

Existing docs pages will be reformatted to follow the new standard in a separate PR.

[tmccoy14]

Looks good to me - Quick note, there's a handful of lint errors being shown

[Shrinks99]

Hmm, maybe the linter isn't running locally for me... Will investigate.

[Shrinks99]

Lint issues are unrelated (but still important!), will address in another PR