devstack 0.1.0

package/vendor/skills/skills/writing-clearly-and-concisely/README.md

@@ -0,0 +1,167 @@
+# Writing Clearly and Concisely
+
+A skill that applies William Strunk Jr.'s timeless writing principles to produce clearer, stronger, more professional prose while avoiding common AI writing patterns.
+
+## Purpose
+
+This skill helps you write better prose for human readers. It draws from two sources:
+
+1. **The Elements of Style** (Strunk, 1918) - Time-tested rules for clear, forceful writing
+2. **AI Pattern Avoidance** - Research-backed guidance on avoiding generic, puffy language that LLMs tend to produce
+
+Whether you're writing documentation, commit messages, error messages, or any text humans will read, this skill helps you cut fluff and say what you mean.
+
+## When to Use
+
+Use this skill whenever you write prose for humans:
+
+- **Documentation** - README files, API docs, technical explanations
+- **Git workflow** - Commit messages, pull request descriptions
+- **User-facing text** - Error messages, UI copy, help text, tooltips
+- **Code comments** - Inline documentation, docstrings
+- **Reports and summaries** - Status updates, analysis, explanations
+- **Editing** - Improving clarity of existing text
+
+**Trigger phrases:**
+
+- "Write documentation for..."
+- "Draft a README"
+- "Edit this for clarity"
+- "Make this more concise"
+- "Review this commit message"
+
+## How It Works
+
+1. **Load the skill** when writing prose for human readers
+2. **Apply Strunk's core principles** - active voice, positive form, concrete language, cut needless words
+3. **Avoid AI patterns** - no puffery, no empty phrases, no promotional adjectives
+4. **Reference detailed guides** when needed for specific rules
+
+### Context-Efficient Approach
+
+The skill uses progressive disclosure to save context:
+
+- **SKILL.md** (~1,000 tokens) loads first with the core rules
+- **Reference files** (1,000-4,500 tokens each) load only when needed
+- **Most tasks need only one file**: `03-elementary-principles-of-composition.md`
+
+For tight context situations, dispatch a subagent with your draft and the relevant section file.
+
+## Key Features
+
+### Strunk's Core Rules
+
+The skill emphasizes these principles from _The Elements of Style_:
+
+| Rule | Principle                                 |
+| ---- | ----------------------------------------- |
+| 10   | Use active voice                          |
+| 11   | Put statements in positive form           |
+| 12   | Use definite, specific, concrete language |
+| 13   | Omit needless words                       |
+| 16   | Keep related words together               |
+| 18   | Place emphatic words at end of sentence   |
+
+### AI Pattern Detection
+
+The skill identifies and eliminates common LLM writing patterns:
+
+- **Puffery**: pivotal, crucial, vital, testament, enduring legacy
+- **Empty "-ing" phrases**: ensuring reliability, showcasing features
+- **Promotional adjectives**: groundbreaking, seamless, robust, cutting-edge
+- **Overused AI vocabulary**: delve, leverage, multifaceted, foster, realm, tapestry
+- **Formatting overuse**: excessive bullets, emoji decorations, bold on every other word
+
+## Reference Files
+
+| Section                | File                                           | Tokens  | Content                                        |
+| ---------------------- | ---------------------------------------------- | ------- | ---------------------------------------------- |
+| Grammar & punctuation  | `02-elementary-rules-of-usage.md`              | ~2,500  | Comma rules, possessives, sentence structure   |
+| Composition principles | `03-elementary-principles-of-composition.md`   | ~4,500  | Active voice, concision, paragraph structure   |
+| Formatting             | `04-a-few-matters-of-form.md`                  | ~1,000  | Headings, quotations, formatting conventions   |
+| Word choice            | `05-words-and-expressions-commonly-misused.md` | ~4,000  | Common errors, word selection                  |
+| AI patterns            | `signs-of-ai-writing.md`                       | ~25,000 | Wikipedia editors' field guide to AI detection |
+
+## Usage Examples
+
+### Example 1: Tightening a Commit Message
+
+**Before:**
+
+> This commit implements the functionality for ensuring that user authentication is properly handled, showcasing robust error handling capabilities.
+
+**After:**
+
+> Add user authentication with error handling
+
+### Example 2: Rewriting Documentation
+
+**Before:**
+
+> This groundbreaking feature leverages cutting-edge technology to deliver a seamless experience, fostering better engagement and driving impactful results.
+
+**After:**
+
+> This feature uses WebSocket connections to update the dashboard in real time.
+
+### Example 3: Fixing Passive Voice
+
+**Before:**
+
+> The configuration file is read by the application at startup.
+
+**After:**
+
+> The application reads the configuration file at startup.
+
+### Example 4: Removing Hedging
+
+**Before:**
+
+> It is important to note that the API might potentially return an error in certain situations.
+
+**After:**
+
+> The API returns an error when the token expires.
+
+## Best Practices
+
+1. **Be specific, not grandiose** - Say what it actually does, not how important it is
+2. **Cut first, add later** - Remove words until meaning suffers, then add back what's needed
+3. **Prefer active voice** - "The function returns X" beats "X is returned by the function"
+4. **State positively** - "He forgot" beats "He did not remember"
+5. **Use concrete language** - "The server crashed" beats "An issue occurred"
+6. **Load reference files sparingly** - Most tasks need only `03-elementary-principles-of-composition.md`
+
+## Directory Structure
+
+```
+writing-clearly-and-concisely/
+  SKILL.md                 # Main skill definition
+  README.md                # This file
+  signs-of-ai-writing.md   # AI pattern detection guide
+  elements-of-style/
+    01-introductory.md
+    02-elementary-rules-of-usage.md
+    03-elementary-principles-of-composition.md
+    04-a-few-matters-of-form.md
+    05-words-and-expressions-commonly-misused.md
+```
+
+## Installation
+
+**Claude Code:**
+
+```bash
+cp -r skills/writing-clearly-and-concisely ~/.claude/skills/
+```
+
+**Claude.ai:**
+Add the skill to project knowledge or paste SKILL.md contents into your conversation.
+
+## Attribution
+
+- Original skill by @joshuadavidthomas from [joshuadavidthomas/agent-skills](https://github.com/joshuadavidthomas/agent-skills) (MIT)
+- Adapted from [obra/the-elements-of-style](https://github.com/obra/the-elements-of-style)
+- Writing principles from _The Elements of Style_ by William Strunk Jr. (1918)
+- AI pattern research from Wikipedia's field guide to AI-generated content detection

package/vendor/skills/skills/writing-clearly-and-concisely/SKILL.md

@@ -0,0 +1,93 @@
+---
+name: writing-clearly-and-concisely
+description: Use when writing prose humans will read—documentation, commit messages, error messages, explanations, reports, or UI text. Applies Strunk's timeless rules for clearer, stronger, more professional writing.
+---
+
+# Writing Clearly and Concisely
+
+## Overview
+
+Write with clarity and force. This skill covers what to do (Strunk) and what not to do (AI patterns).
+
+## When to Use This Skill
+
+Use this skill whenever you write prose for humans:
+
+- Documentation, README files, technical explanations
+- Commit messages, pull request descriptions
+- Error messages, UI copy, help text, comments
+- Reports, summaries, or any explanation
+- Editing to improve clarity
+
+**If you're writing sentences for a human to read, use this skill.**
+
+## Limited Context Strategy
+
+When context is tight:
+
+1. Write your draft using judgment
+2. Dispatch a subagent with your draft and the relevant section file
+3. Have the subagent copyedit and return the revision
+
+Loading a single section (~1,000-4,500 tokens) instead of everything saves significant context.
+
+## Elements of Style
+
+William Strunk Jr.'s _The Elements of Style_ (1918) teaches you to write clearly and cut ruthlessly.
+
+### Rules
+
+**Elementary Rules of Usage (Grammar/Punctuation)**:
+
+1. Form possessive singular by adding 's
+2. Use comma after each term in series except last
+3. Enclose parenthetic expressions between commas
+4. Comma before conjunction introducing co-ordinate clause
+5. Don't join independent clauses by comma
+6. Don't break sentences in two
+7. Participial phrase at beginning refers to grammatical subject
+
+**Elementary Principles of Composition**:
+
+8. One paragraph per topic
+9. Begin paragraph with topic sentence
+10. **Use active voice**
+11. **Put statements in positive form**
+12. **Use definite, specific, concrete language**
+13. **Omit needless words**
+14. Avoid succession of loose sentences
+15. Express co-ordinate ideas in similar form
+16. **Keep related words together**
+17. Keep to one tense in summaries
+18. **Place emphatic words at end of sentence**
+
+### Reference Files
+
+The rules above are summarized from Strunk's original text. For complete explanations with examples:
+
+| Section                                      | File                                           | ~Tokens |
+| -------------------------------------------- | ---------------------------------------------- | ------- |
+| Grammar, punctuation, comma rules            | `02-elementary-rules-of-usage.md`              | 2,500   |
+| Paragraph structure, active voice, concision | `03-elementary-principles-of-composition.md`   | 4,500   |
+| Headings, quotations, formatting             | `04-a-few-matters-of-form.md`                  | 1,000   |
+| Word choice, common errors                   | `05-words-and-expressions-commonly-misused.md` | 4,000   |
+
+**Most tasks need only `03-elementary-principles-of-composition.md`** — it covers active voice, positive form, concrete language, and omitting needless words.
+
+## AI Writing Patterns to Avoid
+
+LLMs regress to statistical means, producing generic, puffy prose. Avoid:
+
+- **Puffery:** pivotal, crucial, vital, testament, enduring legacy
+- **Empty "-ing" phrases:** ensuring reliability, showcasing features, highlighting capabilities
+- **Promotional adjectives:** groundbreaking, seamless, robust, cutting-edge
+- **Overused AI vocabulary:** delve, leverage, multifaceted, foster, realm, tapestry
+- **Formatting overuse:** excessive bullets, emoji decorations, bold on every other word
+
+Be specific, not grandiose. Say what it actually does.
+
+For comprehensive research on why these patterns occur, see `signs-of-ai-writing.md`. Wikipedia editors developed this guide to detect AI-generated submissions — their patterns are well-documented and field-tested.
+
+## Bottom Line
+
+Writing for humans? Load the relevant section from `elements-of-style/` and apply the rules. For most tasks, `03-elementary-principles-of-composition.md` covers what matters most.

package/vendor/skills/skills/writing-clearly-and-concisely/elements-of-style/01-introductory.md

@@ -0,0 +1,3 @@
+## I. Introductory
+
+This handbook summarizes the essentials of plain English style. It focuses on the rules of usage and principles of composition most often broken, offering a compact alternative to exhaustive manuals. Master the guidance here, then look to the best authors for finer points of style.

package/vendor/skills/skills/writing-clearly-and-concisely/elements-of-style/02-elementary-rules-of-usage.md

@@ -0,0 +1,214 @@
+## II. Elementary Rules Of Usage
+
+### Rule 1. Form the possessive singular of nouns by adding 's.
+
+Follow this rule whatever the final consonant. Thus write,
+
+Charles's friend
+
+Burns's poems
+
+the witch's malice
+
+This is the usage of the United States Government Printing Office and of the Oxford University Press.
+
+Exceptions are the possessive of ancient proper names ending in _-es_ and _-is_, the possessive _Jesus'_, and such forms as _for conscience' sake_, _for righteousness' sake_. But such forms as _Achilles' heel_, _Moses' laws_, _Isis' temple_ are commonly replaced by
+
+the heel of Achilles
+
+the laws of Moses
+
+the temple of Isis
+
+The pronominal possessives _hers_, _its_, _theirs_, _yours_, and _oneself_ have no apostrophe.
+
+### Rule 2. In a series of three or more terms with a single conjunction, use a comma after each term except the last.
+
+Thus write,
+
+red, white, and blue
+
+gold, silver, or copper
+
+He opened the letter, read it, and made a note of its contents.
+
+This is also the usage of the Government Printing Office and of the Oxford University Press.
+
+In the names of business firms the last comma is omitted, as,
+
+Brown, Shipley & Co.
+
+### Rule 3. Enclose parenthetic expressions between commas.
+
+The best way to see a country, unless you are pressed for time, is to travel on foot.
+
+This rule is difficult to apply; it is frequently hard to decide whether a single word, such as _however_, or a brief phrase, is or is not parenthetic. If the interruption to the flow of the sentence is but slight, the writer may safely omit the commas. But whether the interruption be slight or considerable, he must never insert one comma and omit the other. Such punctuation as
+
+Marjorie's husband, Colonel Nelson paid us a visit yesterday,
+
+or
+
+My brother you will be pleased to hear, is now in perfect health,
+
+is indefensible.
+
+If a parenthetic expression is preceded by a conjunction, place the first comma before the conjunction, not after it.
+
+He saw us coming, and unaware that we had learned of his treachery, greeted us with a smile.
+
+Always to be regarded as parenthetic and to be enclosed between commas (or, at the end of the sentence, between comma and period) are the following:
+
+\(1\) the year, when forming part of a date, and the day of the month, when following the day of the week:
+
+February to July, 1916.
+
+April 6, 1917.
+
+Monday, November 11, 1918.
+
+\(2\) the abbreviations _etc._ and _jr._
+
+\(3\) non-restrictive relative clauses, that is, those which do not serve to identify or define the antecedent noun, and similar clauses introduced by conjunctions indicating time or place.
+
+The audience, which had at first been indifferent, became more and more interested.
+
+In this sentence the clause introduced by _which_ does not serve to tell which of several possible audiences is meant; what audience is in question is supposed to be already known. The clause adds, parenthetically, a statement supplementing that in the main clause. The sentence is virtually a combination of two statements which might have been made independently:
+
+The audience had at first been indifferent. It became more and more interested.
+
+Compare the restrictive relative clause, not set off by commas, in the sentence,
+
+The candidate who best meets these requirements will obtain the place.
+
+Here the clause introduced by _who_ does serve to tell which of several possible candidates is meant; the sentence cannot be split up into two independent statements.
+
+The difference in punctuation in the two sentences following is based on the same principle:
+
+Nether Stowey, where Coleridge wrote The Rime of the Ancient Mariner, is a few miles from Bridgewater.
+
+The day will come when you will admit your mistake.
+
+Nether Stowey is completely identified by its name; the statement about Coleridge is therefore supplementary and parenthetic. The _day_ spoken of is identified only by the dependent clause, which is therefore restrictive.
+
+Similar in principle to the enclosing of parenthetic expressions between commas is the setting off by commas of phrases or dependent clauses preceding or following the main clause of a sentence.
+
+Partly by hard fighting, partly by diplomatic skill, they enlarged their dominions to the east, and rose to royal rank with the possession of Sicily, exchanged afterwards for Sardinia.
+
+Other illustrations may be found in sentences quoted under Rules 4, 5, 6, 7, 16, and 18.
+
+The writer should be careful not to set off independent clauses by commas: see under Rule 5.
+
+### Rule 4. Place a comma before a conjunction introducing a co-ordinate clause.
+
+The early records of the city have disappeared, and the story of its first years can no longer be reconstructed.
+
+The situation is perilous, but there is still one chance of escape.
+
+Sentences of this type, isolated from their context, may seem to be in need of rewriting. As they make complete sense when the comma is reached, the second clause has the appearance of an afterthought. Further, _and_ is the least specific of connectives. Used between independent clauses, it indicates only that a relation exists between them without defining that relation. In the example above, the relation is that of cause and result. The two sentences might be rewritten:
+
+As the early records of the city have disappeared, the story of its first years can no longer be reconstructed.
+
+Although the situation is perilous, there is still one chance of escape.
+
+Or the subordinate clauses might be replaced by phrases:
+
+Owing to the disappearance of the early records of the city, the story of its first years can no longer be reconstructed.
+
+In this perilous situation, there is still one chance of escape.
+
+But a writer may err by making his sentences too uniformly compact and periodic, and an occasional loose sentence prevents the style from becoming too formal and gives the reader a certain relief. Consequently, loose sentences of the type first quoted are common in easy, unstudied writing. But a writer should be careful not to construct too many of his sentences after this pattern (see Rule 14).
+
+Two-part sentences of which the second member is introduced by _as_ (in the sense of _because_), _for_, _or_, _nor_, and _while_ (in the sense of _and at the same time_) likewise require a comma before the conjunction.
+
+If the second member is introduced by an adverb, a semicolon, not a comma, is required (see Rule 5). The connectives _so_ and _yet_ may be used either as adverbs or as conjunctions, accordingly as the second clause is felt to be co-ordinate or subordinate; consequently either mark of punctuation may be justified. But these uses of _so_ (equivalent to _accordingly_ or to _so that_) are somewhat colloquial and should, as a rule, be avoided in writing. A simple correction, usually serviceable, is to omit the word _so_ and begin the first clause with _as_ or _since_:
+
+| Original                                                                           | Revision                                                                           |
+| ---------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------- |
+| I had never been in the place before; so I had difficulty in finding my way about. | As I had never been in the place before, I had difficulty in finding my way about. |
+
+If a dependent clause, or an introductory phrase requiring to be set off by a comma, precedes the second independent clause, no comma is needed after the conjunction.
+
+The situation is perilous, but if we are prepared to act promptly, there is still one chance of escape.
+
+When the subject is the same for both clauses and is expressed only once, a comma is required if the connective is _but_. If the connective is _and_, the comma should be omitted if the relation between the two statements is close or immediate.
+
+I have heard his arguments, but am still unconvinced.
+
+He has had several years' experience and is thoroughly competent.
+
+### Rule 5. Do not join independent clauses by a comma.
+
+If two or more clauses, grammatically complete and not joined by a conjunction, are to form a single compound sentence, the proper mark of punctuation is a semicolon.
+
+Stevenson's romances are entertaining; they are full of exciting adventures.
+
+It is nearly half past five; we cannot reach town before dark.
+
+It is of course equally correct to write the above as two sentences each, replacing the semicolons by periods.
+
+Stevenson's romances are entertaining. They are full of exciting adventures.
+
+It is nearly half past five. We cannot reach town before dark.
+
+If a conjunction is inserted the proper mark is a comma (Rule 4).
+
+Stevenson's romances are entertaining, for they are full of exciting adventures.
+
+It is nearly half past five, and we cannot reach town before dark.
+
+A comparison of the three forms given above will show clearly the advantage of the first. It is, at least in the examples given, better than the second form, because it suggests the close relationship between the two statements in a way that the second does not attempt, and better than the third, because briefer and therefore more forcible. Indeed it may be said that this simple method of indicating relationship between statements is one of the most useful devices of composition. The relationship, as above, is commonly one of cause or of consequence.
+
+Note that if the second clause is preceded by an adverb, such as _accordingly_, _besides_, _then_, _therefore_, or _thus_, and not by a conjunction, the semicolon is still required.
+
+Two exceptions to the rule may be admitted. If the clauses are very short, and are alike in form, a comma is usually permissible:
+
+Man proposes, God disposes.
+
+The gate swung apart, the bridge fell, the portcullis was drawn up.
+
+Note that in these examples the relation is not one of cause or consequence. Also in the colloquial form of expression,
+
+I hardly knew him, he was so changed,
+
+a comma, not a semicolon, is required. But this form of expression is inappropriate in writing, except in the dialogue of a story or play, or perhaps in a familiar letter.
+
+### Rule 6. Do not break sentences in two.
+
+In other words, do not use periods for commas.
+
+I met them on a Cunard liner several years ago. Coming home from Liverpool to New York.
+
+He was an interesting talker. A man who had traveled all over the world and lived in half a dozen countries.
+
+In both these examples, the first period should be replaced by a comma, and the following word begun with a small letter.
+
+It is permissible to make an emphatic word or expression serve the purpose of a sentence and to punctuate it accordingly:
+
+Again and again he called out. No reply.
+
+The writer must, however, be certain that the emphasis is warranted, and that he will not be suspected of a mere blunder in syntax or in punctuation.
+
+Rules 3, 4, 5, and 6 cover the most important principles in the punctuation of ordinary sentences; they should be so thoroughly mastered that their application becomes second nature.
+
+### Rule 7. A participial phrase at the beginning of a sentence must refer to the grammatical subject.
+
+Walking slowly down the road, he saw a woman accompanied by two children.
+
+The word _walking_ refers to the subject of the sentence, not to the woman. If the writer wishes to make it refer to the woman, he must recast the sentence:
+
+He saw a woman accompanied by two children, walking slowly down the road.
+
+Participial phrases preceded by a conjunction or by a preposition, nouns in apposition, adjectives, and adjective phrases come under the same rule if they begin the sentence.
+
+| Original                                                                    | Revision                                                                             |
+| --------------------------------------------------------------------------- | ------------------------------------------------------------------------------------ |
+| On arriving in Chicago, his friends met him at the station.                 | When he arrived (or, On his arrival) in Chicago, his friends met him at the station. |
+| A soldier of proved valor, they entrusted him with the defence of the city. | A soldier of proved valor, he was entrusted with the defence of the city.            |
+| Young and inexperienced, the task seemed easy to me.                        | Young and inexperienced, I thought the task easy.                                    |
+| Without a friend to counsel him, the temptation proved irresistible.        | Without a friend to counsel him, he found the temptation irresistible.               |
+
+Sentences violating this rule are often ludicrous.
+
+Being in a dilapidated condition, I was able to buy the house very cheap.
+
+Wondering irresolutely what to do next, the clock struck twelve.