uic-writing
Skill1 starsChanged 10 days agoMITView on GitHub
Writes and edits this plugin's skills and documents to Anthropic's skill authoring practices, then finds and fixes the stale references and contradictions the edit left. Use when changing a skill, USING.md, README.md, .claude/CLAUDE.md, AGENTS.md, CONTRIBUTING.md, docs/ or .claude/rules/ in this repository.
In this repository13 other files it gives its agents.
- AGENTS.mdAGENTS.md
- .claude/CLAUDE.mdCLAUDE.md
- uic-auditingSkill
- accessibilitySkill
- adjustingSkill
- conventionsSkill
- decisionsSkill
- designSkill
- finding-patternsSkill
- implementingSkill
- planningSkill
- valuesSkill
- verifyingSkill
The file
Show its rules and text
We split this skill into the rules it gives an agent
20 rules. About 0 are common, 18 are distinctive, and 2 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈18
Distinctive · estimate
This author's own choices. Worth a look.
2
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 28
Only what the model does not already know: an instruction, a definition, a template or an example.
- Distinctive: line 29
Remove an instruction the current models follow without being told: one written for an earlier model is often too prescriptive for a newer …
- Distinctive: line 30
When a change adds a line to a skill, remove what that line makes unnecessary in the same skill.
- Distinctive: line 31
No story of an earlier run, no history of the plugin, no argument for its design, no maxim.
- Distinctive: line 32
Keep a clause of why where it changes a judgment.
- Distinctive: line 33
Keep a concrete failure where it shows a rule nobody would guess.
- Distinctive: line 41
Write what holds through a task as a standing instruction — *re-read the checklist before every page*, not *re-read the checklist*: Claude …
- Distinctive: line 42
Write an exception as its own line, its condition first — *If …, …* — never as a clause inside the rule it limits.
- Distinctive: line 44
Ask for what was done and what settled it, never for the reasoning written out: the current models may decline a request to write out their …
- Distinctive: line 51
Put the instructions that matter most near the top, for the same reason.
- Distinctive: line 52
Keep in it what every run of the skill needs.
- Very specific: line 60
Keep the files flat in the skill's folder: scripts/check-skills.sh reads no subfolder.
- Distinctive: line 67
Do not summarise the steps.
- Distinctive: line 75
Keep a rule repeated across skills: each skill can be loaded alone.
- Distinctive: line 81
Before the change is done:
- Distinctive: line 83
Stale references: Search for every file, section, skill, test and command the changed text names.
- Distinctive: line 92
Ask it to find every such line first, then to name at most five, ranked by how much each changes what an agent does.
- Very specific: line 96
Leave older wording that no changed line touches or contradicts: reviewing whole files is uic-auditing's, which runs only when somebody …
- Distinctive: line 97
Do the read once. Do not repeat it after the fixes, and never run the skill on a project for it.
- Distinctive: line 98
If the harness has no subagents, skip it and say so.
≈ “Common” is an estimate: at least 1 in 5 of the 372,429 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.
Files
Writing the plugin
Overview
The plugin is Markdown an agent acts on. Judge a change by one thing — whether the plugin gets more effective: fewer words for the agent to carry, clearer steps, better results on real projects.
While writing
Anthropic's skill authoring guide (https://platform.claude.com/docs/en/agents-and-tools/agent-skills/best-practices), applied here.
What goes in
- Only what the model does not already know: an instruction, a definition, a template or an example.
- Remove an instruction the current models follow without being told: one written for an earlier model is often too prescriptive for a newer one (the model pages of the prompting guide, https://platform.claude.com/docs/en/build-with-claude/prompt-engineering/claude-prompting-best-practices).
- When a change adds a line to a skill, remove what that line makes unnecessary in the same skill.
- No story of an earlier run, no history of the plugin, no argument for its design, no maxim.
- Keep a clause of why where it changes a judgment.
- Keep a concrete failure where it shows a rule nobody would guess.
- Earlier issues, commits and decisions are not arguments for or against a change; how the plugin behaves now is.
How a line is written
- One instruction to a line, in the imperative: what to do, not how it was arrived at.
- Say what to do, rather than only what not to do.
- Name the scope a rule covers — every page, each line of the checklist — where it holds beyond the item in front of it: the current models read an instruction literally and do not carry it to the next item.
- Write what holds through a task as a standing instruction — re-read the checklist before every page, not re-read the checklist: Claude Code does not load a skill again on later turns (https://code.claude.com/docs/en/skills, Skill content lifecycle).
- Write an exception as its own line, its condition first — If …, … — never as a clause inside the rule it limits.
- Fix a line that reads two ways by rewriting it, and two lines that disagree by rewriting the pair, rather than by adding a clause beside them.
- Ask for what was done and what settled it, never for the reasoning written out: the current models may decline a request to write out their reasoning (the Fable 5.1 and Opus 5 pages of the prompting guide).
- Have a check note every finding, the uncertain ones included, and filter in a step of its own: a check told to report only what matters finds less (the Sonnet 5 and Opus 4.8 pages).
A SKILL.md
- Frontmatter, title,
## Overviewin one or two sentences, then the steps in order. - Under 500 lines and 16,000 characters: after compaction Claude Code re-attaches only the first 5,000 tokens of a skill (https://code.claude.com/docs/en/skills, Skill content lifecycle).
- Put the instructions that matter most near the top, for the same reason.
- Keep in it what every run of the skill needs.
- Move what only one case of the work needs to a reference file, linked from that case's step: the file costs nothing until that step opens it.
- The skills one piece of work invokes share 25,000 tokens after compaction, the most recently invoked first, and an older one past the budget is dropped whole. A new page invokes
finding-patterns,conventions,values,decisions,planning,implementingandverifying: when one grows, add up theirSKILL.mdsizes, each counted up to 16,000 characters, and keep the total under 80,000 characters (25,000 tokens at 3.2 characters a token). Over it, shorten one.
A reference file
- Title, then one line
**Read when:** …, then## Contentswhen it runs over 100 lines. - One case to a file, named for it: a step opens only the case it meets (the authoring guide, Domain-specific organization).
- Keep the files flat in the skill's folder:
scripts/check-skills.shreads no subfolder. - Link it with its title —
[*A position no member has*](position-no-member-has.md)— so a case another skill names is found in theSKILL.md. - Link it directly from the
SKILL.mdof its own skill that needs it, never only from another reference file. Another skill that needs it gives its path, below.
A description
- Say what the skill does, then Use when … with the words a request uses.
- Do not summarise the steps.
- Third person, at most 1,024 characters, no XML tags.
- A shipped skill's description says in its first words that the work is what an end user sees.
Terms and rules
- One term per meaning. In a shipped skill, use the plugin's own terms as
skills/finding-patterns/words.mddefines them; a word a model already knows is not defined there. - Say a rule once inside a skill, where it is first needed, and link it everywhere else in that skill.
- Keep a rule repeated across skills: each skill can be loaded alone.
- Name another skill for the agent to invoke as
ui-consistency:<name>, with the section. Reachvalues,conventionsanddecisionsonly that way, their own files included: an invoked skill is re-attached after compaction, a file read with a tool is not. - Where a step reads a file of another skill rather than invoking the skill, write the file as its path from the skill's folder,
`../<skill>/<file>.md`, never as a link: a catalog's linter fails a skill whose link leaves its folder.
After writing
Before the change is done:
- Stale references. Search for every file, section, skill, test and command the changed text names; each must still exist.
- Contradictions. For every rule the change touched, search for its other copies — in other words as well as the same ones — in
skills/,USING.md,README.md,.claude/CLAUDE.md,AGENTS.md,CONTRIBUTING.md,docs/,.claude/rules/and.claude/skills/.- Each copy now says the same thing, or the change is not done.
- Fix every stale reference and every contradiction in the same change, and say in the pull request which copies were found.
One fresh read, once — if a skill changed. Hand a subagent with no other context the diff of the changed skill files, and those files in full as context only — with
skills/finding-patterns/words.mdif a shipped skill changed. Ask it about the changed lines only:- a changed line that can be read two ways;
- a changed line that disagrees with any line of the full files;
- a word a changed line uses in a sense different from its other uses in the full files — or, in a shipped skill, a term of the plugin's own that
words.mddoes not define.
Ask it to find every such line first, then to name at most five, ranked by how much each changes what an agent does. Then:
- Fix every item that changes what an agent does. If a changed line disagrees with older wording, fix the pair, as step 2 asks.
- Say in the pull request what was fixed and name any other item; "nothing" is a result.
- Leave older wording that no changed line touches or contradicts: reviewing whole files is
uic-auditing's, which runs only when somebody asks for an audit. - Do the read once. Do not repeat it after the fixes, and never run the skill on a project for it.
- If the harness has no subagents, skip it and say so.
How a wrong statement is corrected, and what may never be written publicly, is .claude/rules/uic-docs.md.
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
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.

