agentleFS
kamenkurtevkamenkurtev/ui-consistency/.claude/skills/uic-writing/SKILL.md

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.

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
  1. Distinctive:

    Only what the model does not already know: an instruction, a definition, a template or an example.

    line 28
  2. Distinctive:

    Remove an instruction the current models follow without being told: one written for an earlier model is often too prescriptive for a newer …

    line 29
  3. Distinctive:

    When a change adds a line to a skill, remove what that line makes unnecessary in the same skill.

    line 30
  4. Distinctive:

    No story of an earlier run, no history of the plugin, no argument for its design, no maxim.

    line 31
  5. Distinctive:

    Keep a clause of why where it changes a judgment.

    line 32
  6. Distinctive:

    Keep a concrete failure where it shows a rule nobody would guess.

    line 33
  7. Distinctive:

    Write what holds through a task as a standing instruction — *re-read the checklist before every page*, not *re-read the checklist*: Claude …

    line 41
  8. Distinctive:

    Write an exception as its own line, its condition first — *If …, …* — never as a clause inside the rule it limits.

    line 42
  9. Distinctive:

    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 …

    line 44
  10. Distinctive:

    Put the instructions that matter most near the top, for the same reason.

    line 51
  11. Distinctive:

    Keep in it what every run of the skill needs.

    line 52
  12. Very specific:

    Keep the files flat in the skill's folder: scripts/check-skills.sh reads no subfolder.

    line 60
  13. Distinctive:

    Do not summarise the steps.

    line 67
  14. Distinctive:

    Keep a rule repeated across skills: each skill can be loaded alone.

    line 75
  15. Distinctive:

    Before the change is done:

    line 81
  16. Distinctive:

    Stale references: Search for every file, section, skill, test and command the changed text names.

    line 83
  17. Distinctive:

    Ask it to find every such line first, then to name at most five, ranked by how much each changes what an agent does.

    line 92
  18. Very specific:

    Leave older wording that no changed line touches or contradicts: reviewing whole files is uic-auditing's, which runs only when somebody …

    line 96
  19. Distinctive:

    Do the read once. Do not repeat it after the fixes, and never run the skill on a project for it.

    line 97
  20. Distinctive:

    If the harness has no subagents, skip it and say so.

    line 98

≈ “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.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

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, ## Overview in 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, implementing and verifying: when one grows, add up their SKILL.md sizes, 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 ## Contents when 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.sh reads 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 the SKILL.md.
  • Link it directly from the SKILL.md of 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.md defines 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. Reach values, conventions and decisions only 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:

  1. Stale references. Search for every file, section, skill, test and command the changed text names; each must still exist.
  2. 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.
  3. Fix every stale reference and every contradiction in the same change, and say in the pull request which copies were found.
  4. 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.md if 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.md does 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.

Download now (ZIP)

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
What did you use it for? e.g. Reviewing pull requests in a Rails app

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.