diff --git a/.agents/skills/clean-writing b/.agents/skills/clean-writing new file mode 120000 index 0000000..b3fbe60 --- /dev/null +++ b/.agents/skills/clean-writing @@ -0,0 +1 @@ +../../skills/clean-writing \ No newline at end of file diff --git a/README.md b/README.md index d706ced..14f071a 100644 --- a/README.md +++ b/README.md @@ -16,13 +16,14 @@ This repo is a shared home for installable agent skills. ## Available skills -| Skill | Description | Install | -| ---------------------- | ---------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------ | -| `git-workflow` | Commit work, create branches, and open pull requests using conventional git workflow conventions | `npx skills add https://github.com/LayeredCraft/skills --skill git-workflow` | -| `engineering-workflow` | Project-agnostic process for design, implementation, testing, review, feedback, security, and documentation | `npx skills add https://github.com/LayeredCraft/skills --skill engineering-workflow` | -| `simple-dotnet-architecture` | Pragmatic .NET 8+ Minimal API, worker, and consumer architecture guidance | `npx skills add https://github.com/LayeredCraft/skills --skill simple-dotnet-architecture` | -| `zensical-site` | Tooling and guidance for Zensical-flavored documentation work | `npx skills add https://github.com/LayeredCraft/skills --skill zensical-site` | -| `partiql-dynamodb` | DynamoDB-specific PartiQL guidance with focused references for statements, functions, operators, transactions, and IAM | `npx skills add https://github.com/LayeredCraft/skills --skill partiql-dynamodb` | +| Skill | Description | Install | +| ---------------------------- | ---------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------ | +| `git-workflow` | Commit work, create branches, and open pull requests using conventional git workflow conventions | `npx skills add https://github.com/LayeredCraft/skills --skill git-workflow` | +| `engineering-workflow` | Project-agnostic process for design, implementation, testing, review, feedback, security, and documentation | `npx skills add https://github.com/LayeredCraft/skills --skill engineering-workflow` | +| `simple-dotnet-architecture` | Pragmatic .NET 8+ Minimal API, worker, and consumer architecture guidance | `npx skills add https://github.com/LayeredCraft/skills --skill simple-dotnet-architecture` | +| `zensical-site` | Tooling and guidance for Zensical-flavored documentation work | `npx skills add https://github.com/LayeredCraft/skills --skill zensical-site` | +| `partiql-dynamodb` | DynamoDB-specific PartiQL guidance with focused references for statements, functions, operators, transactions, and IAM | `npx skills add https://github.com/LayeredCraft/skills --skill partiql-dynamodb` | +| `clean-writing` | Clear, calm, natural writing for conversation, technical explanations, and prose editing | `npx skills add https://github.com/LayeredCraft/skills --skill clean-writing` | ## Install a skill @@ -74,6 +75,16 @@ Zensical-flavored documentation skill for structured authoring, reference-driven - Includes supporting references and templates inside `skills/zensical-site` - Install with `npx skills add https://github.com/LayeredCraft/skills --skill zensical-site` +### `clean-writing` + +General writing skill for clear, direct communication without AI-like filler, hype, or rigid templates. + +- Applies to every user-facing response, draft, rewrite, and technical explanation +- Leads with answer, then adds only needed context +- Preserves facts, uncertainty, code, commands, and technical precision +- Uses direct language without becoming clipped or harsh +- Install with `npx skills add https://github.com/LayeredCraft/skills --skill clean-writing` + ### `partiql-dynamodb` DynamoDB PartiQL skill for statement syntax, practical usage guidance, caveats, and IAM-aware operational safety. diff --git a/skills/clean-writing/SKILL.md b/skills/clean-writing/SKILL.md new file mode 100644 index 0000000..1424899 --- /dev/null +++ b/skills/clean-writing/SKILL.md @@ -0,0 +1,19 @@ +--- +name: clean-writing +description: "Use for all user-facing prose: responses, drafts, edits, reviews, documentation, and technical explanations. Write clearly and naturally, without filler or lost nuance." +--- + +# Clean writing + +Write clearly, directly, and respectfully. Follow higher-priority and explicit user instructions. Do not add forced personality or imitation. + +- Lead with the answer, decision, action, or point. Add context only when it helps readers understand or act. +- Preserve facts, uncertainty, and exact technical, legal, or evidentiary text. Do not invent specificity or turn uncertainty into certainty. +- Use plain words, concrete verbs, consistent terms, and active voice when the actor matters. Name relevant actors, reasons, limits, and failures. +- Match length and format to the task. Use structure only when it helps readers scan or act. Retain required syntax, labels, and formatting. + +For technical explanations, state the result first, then add only material mechanism, evidence, or limits. Procedures need steps and expected results. Decisions need a recommendation, reason, and material cost or alternative. + +For edits, return clean copy unless annotations or source formatting are requested. Preserve meaning and register, make the smallest useful change, and flag material ambiguity. + +Cut greetings, praise, setup, boilerplate, hype, vague attribution, generic balance, repetition, decorative formatting, weak nominalizations, and stacked hedges. Keep contrasts, passive voice, and lists when helpful. diff --git a/skills/clean-writing/evals/evals.json b/skills/clean-writing/evals/evals.json new file mode 100644 index 0000000..65cfb71 --- /dev/null +++ b/skills/clean-writing/evals/evals.json @@ -0,0 +1,49 @@ +{ + "skill_name": "clean-writing", + "evals": [ + { + "id": 1, + "prompt": "The build failed because the database migration was not applied. Tell the user what happened and what to do next.", + "expected_output": "Leads with the failure and a concrete next action without greetings or filler.", + "files": [], + "expectations": [ + "States that the migration is missing.", + "Gives the command or action needed to apply it when available.", + "Preserves uncertainty if the cause is not confirmed." + ] + }, + { + "id": 2, + "prompt": "Explain why an HTTP cache can return stale data after an update.", + "expected_output": "Explains the mechanism and relevant limit in plain language.", + "files": [], + "expectations": [ + "States the explanation before background detail.", + "Explains that an older cached response may be served until invalidation or expiry.", + "Avoids unsupported claims about the application's cache settings." + ] + }, + { + "id": 3, + "prompt": "Rewrite this customer message: Great news! We are thrilled to announce that your report is now available. Let us know if you have any questions!", + "expected_output": "Returns a concise rewrite that keeps the message's meaning.", + "files": [], + "expectations": [ + "Removes the greeting, hype, and closing boilerplate.", + "Preserves the fact that the report is available.", + "Returns only the rewrite unless a note is needed." + ] + }, + { + "id": 4, + "prompt": "Review a pull request that removes a required authentication check. Start the finding with the repository's required blocking emoji.", + "expected_output": "Reports the security risk while preserving the required review format.", + "files": [], + "expectations": [ + "Keeps the required leading emoji.", + "Names the removed authentication check and concrete impact.", + "Suggests restoring the check." + ] + } + ] +} diff --git a/skills/clean-writing/evals/trigger-evals.json b/skills/clean-writing/evals/trigger-evals.json new file mode 100644 index 0000000..b3bd62e --- /dev/null +++ b/skills/clean-writing/evals/trigger-evals.json @@ -0,0 +1,18 @@ +[ + { + "query": "Implement this API endpoint and tell me what changed.", + "should_trigger": true + }, + { + "query": "Review this pull request for bugs and explain the findings.", + "should_trigger": true + }, + { + "query": "Rewrite this update for customers.", + "should_trigger": true + }, + { + "query": "Use a tool to take a screenshot of the open browser tab.", + "should_trigger": true + } +]