netcracker/ai-for-dummies
3
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

feat: review Gustavo and Marcos submitted skills

Browse Source
This commit is contained in:
Marcos Silva
2026-09-04 09:07:54 -03:00
parent 6694897ae9
commit 5756dceb5a
38 changed files with 2749 additions and 6 deletions
Download Patch File Download Diff File Expand all files Collapse all files
submitted-skills/Marcos Silva/skills/unslop/SKILL.md
+100
View File
@@ -0,0 +1,100 @@
---
name: unslop
description: Strip AI phrasing from prose before it is posted to a Confluence page, sent to a customer, or shared in chat. Use when a draft sounds like it was written by an LLM: ornamental hedging, breathless transitions, vague intensifiers, symmetrical bullet padding, or any of the other tells listed in references/tells.md.
---
# Unslop
The page-reviewer catches structural problems; this skill catches voice
problems. Both run before a page goes live.
The unslop pass is line-anchored, deterministic, and reversible. It returns a
diff-style report; the author or the calling skill applies the changes.
## Hard rules
- **Never edit silently.** Every change appears in the report with the line,
the original phrase, and the suggested replacement.
- **Never invent voice.** The rewrite defaults to short, declarative, and
Netcracker-house — see [references/house-style.md](references/house-style.md).
- **Don't rewrite technical content.** If a sentence is slop but the
technical claim is correct, fix the phrasing, not the claim.
- **Don't rewrite quotes.** Code, command output, error messages, and
customer-quoted text stay literal.
- **Don't touch structured data.** Tables, lists of identifiers, file paths,
URLs, and version numbers are not slop.
## Workflow
1. Read the draft. Mark each line with one of: `clean`, `slop`, `unsure`.
2. For each `slop` line, look up the tell in
[references/tells.md](references/tells.md) and propose a concrete rewrite.
3. For each `unsure` line, leave it alone and flag it for the author with a
short rationale.
4. Cluster check. If more than 5 slop lines appear in a 30-line block, mark
the block `rewrite-block` — voice problems cluster, and the author should
rewrite that section by hand rather than accept a chain of small fixes.
5. Return the report.
## Report shape
```
# Unslop report — <page slug>
L<line>: <tell> — <phrase>
> <original>
+ <proposed rewrite>
L<line>: <tell> — <phrase>
> <original>
+ <proposed rewrite>
# Rewrite-block sections (cluster of >5 slop lines)
- L<start>-L<end>: <section title>
# Uncertain — author decides
- L<line>: <short rationale>
```
The calling skill applies line-by-line fixes; the author rewrites the marked
sections.
## What counts as slop
Full list with examples in [references/tells.md](references/tells.md). The
high-frequency ones:
| Tell | Example | Fix |
|------|---------|-----|
| Ornamental hedging | "It's important to note that…" | Delete the preamble. |
| Breathless transition | "Let's dive in!" | Replace with the next fact. |
| Vague intensifier | "really", "very", "quite" (when not load-bearing) | Delete. |
| Symmetric padding | "X is Y. X is also Z. Both X's are…" | Pick the one that matters. |
| AI résumé | "With over X years of experience…" | Replace with the actual fact. |
| Performative caveat | "It's worth mentioning that…" | Delete or move to the conclusion. |
| Marketing tone | "seamlessly", "robust", "powerful", "leverage" | Replace with the specific capability. |
| Triplet | "fast, reliable, and scalable" | Pick the one that is actually true, drop the rest. |
| Heading question | "Why is X important?" | State the answer, not the question. |
| Sign-off | "Hope this helps!", "Let me know if you have questions!" | Delete. |
## When to refuse
- The text is a customer-quoted block, a log line, or a code comment — leave
it alone.
- The text is technical and correct; only the framing is fluffy. Fix the
framing, not the substance.
- The rewrite would change the meaning. Mark it `unsure` and let the author
decide.
## Related
| Skill | Role |
|-------|------|
| `page-reviewer` | Calls unslop as part of the pre-post gate |
| `confluence-page` | Uses the report to apply line-by-line fixes |
## Limitations
Unslop is a heuristic pass, not a guarantee. A page can be technically
slop-free and still sound corporate, and a page that sounds conversational
can still be slop-free. Voice is not the only quality dimension; this skill
addresses one of them.
submitted-skills/Marcos Silva/skills/unslop/references/house-style.md
+74
View File
@@ -0,0 +1,74 @@
# Netcracker House Style
The voice and shape unslop rewrites toward when nothing else is specified.
This is the default, not a mandate — pages with a stated owner voice
override this list.
## Sentence
- Active voice by default.
- One idea per sentence. Two if they're tightly coupled.
- Sentence length mostly 8–25 words. Long sentences only when the structure
is parallel.
- No run-on lines (>200 chars) in body paragraphs. Code and tables exempt.
## Paragraph
- First sentence carries the claim.
- Body sentences support it.
- Last sentence ties it to the next paragraph or to a link.
- 3–6 sentences for most paragraphs. Lists break up long paragraphs; they do
not replace them.
## Headings
- Verb-first when possible: "Run the migration" not "Migration".
- Question headings only when the body answers the question in the first
sentence.
- No emoji in h1 / h2. Emoji ok in h3 and below when it's a stable convention.
## Lists
- Parallel grammatical form across items.
- One concept per item. Two ideas → two items.
- Bullet list for unordered; numbered list for steps.
## Tables
- Column headers in `Title case`.
- Numbers right-aligned in monospace columns; labels left-aligned in prose.
- Empty cells get `<empty>` or are filled — never blank.
## Code
- Inline code for file names, env vars, commands, identifiers.
- Fenced blocks with language tag for anything longer than one line.
- Comments inside code blocks explain *why*, not *what*.
## Links
- Anchor text describes the destination. "click here" is a smell.
- External links open in same tab; the Confluence renderer adds the
indicator.
- Internal page links by title, not by URL — rename the page and the link
follows.
## Voice
- First person plural ("we") when the team owns the page.
- Third person when describing a component or a product.
- Avoid "I" on team-owned pages.
- Avoid the passive voice when it hides who did the thing.
## What unslop does not change
- Code blocks, command output, error messages, log lines.
- Customer quotes (marked as such).
- Commit messages, ticket numbers, identifiers.
- Acronyms the audience uses.
## Calibration
A page rewritten by unslop should pass the "would a senior engineer send
this to their team?" test. If yes, ship. If the page still reads corporate,
escalate to the owner — unslop is not the right tool for that.
submitted-skills/Marcos Silva/skills/unslop/references/tells.md
+75
View File
@@ -0,0 +1,75 @@
# Slop Tells
A worked catalogue of the phrases that mark prose as AI-generated. The
`unslop` skill greps the draft for each row and reports a fix.
The list is heuristic. A page can match several tells and still read well;
a page can match none and still feel corporate. Use this as a checklist, not a
verdict.
## High-frequency tells
| Tell | Example | Default fix |
|------|---------|-------------|
| Ornamental hedging | "It's important to note that…" | Delete the preamble |
| Breathless transition | "Let's dive in!", "Now, let's explore…" | Replace with the next fact |
| Vague intensifier | "really", "very", "quite", "rather" (when not load-bearing) | Delete |
| Symmetric padding | "X is Y. X is also Z. Both X's are…" | Pick the one that matters |
| AI résumé | "With over X years of experience…" | Replace with the actual fact |
| Performative caveat | "It's worth mentioning that…" | Delete or move to the conclusion |
| Marketing tone | "seamlessly", "robust", "powerful", "leverage", "cutting-edge" | Replace with the specific capability |
| Triplet | "fast, reliable, and scalable" | Pick the one that is actually true |
| Heading question | "Why is X important?" | State the answer, not the question |
| Sign-off | "Hope this helps!", "Let me know if you have questions!" | Delete |
| Throat-clearing | "In this article, we will…" | Delete the article and start with the subject |
| Mirror transition | "As we have seen…" | Replace with the actual finding |
| Manufactured urgency | "In today's fast-paced world…" | Delete |
| Generic closer | "To learn more, contact…" | Replace with the actual link or contact |
## Mid-frequency
| Tell | Example | Default fix |
|------|---------|-------------|
| Bureaucratic noun | "perform a verification of" | "verify" |
| Nominalised verb | "the implementation of the feature" | "implementing the feature" |
| Possessive hedge | "in our experience" | Drop unless backed by data |
| Padded qualifier | "essentially", "basically", "fundamentally", "literally" | Delete |
| Redundant pair | "each and every", "first and foremost", "any and all" | Pick one |
| Process name as action | "we will be performing a build" | "we will build" |
| Apology | "Apologies for the inconvenience" | Replace with the fix |
| Hyperbole | "game-changer", "revolutionary", "paradigm shift" | Replace with the actual claim |
| Cult of positivity | "We are excited to announce…" | Replace with the news |
| Generic advice | "Best practices include…" | Replace with the specific practice |
## Low-frequency (still flag)
| Tell | Example | Default fix |
|------|---------|-------------|
| Anachronism | "in the year 2026" | Drop the year unless it disambiguates |
| Self-reference | "this article", "this section", "as stated above" | Replace with the thing |
| Passive that hides the actor | "It was decided that…" | "We decided…" |
| Telegraphic metaphor | "drowning in data", "needle in a haystack" | Replace with the literal state |
| Fake precision | "in 90% of cases" | Replace with the source |
## What is NOT slop
- Technical jargon used precisely (`asynchronous`, `idempotent`,
`backpressure`).
- Repetition for emphasis that the reader actually needs.
- Headings that match a list of canonical section titles (`Overview`,
`Steps`, `Verification`).
- Code, command output, error messages, customer-quoted text.
- Acronyms and abbreviations the audience knows.
## Cluster detection
Slop tends to cluster. A single slop line in 30 is a minor fix. Five slop
lines in 10 means the author wrote the paragraph by stream-of-prompting; the
whole section should be rewritten by hand. The `unslop` skill flags cluster
sections as `rewrite-block` rather than proposing per-line fixes.
## When to escalate
A draft that reads well but uses a non-AAVE corporate voice should not be
unslopped into something else; flag it for the author. The skill rewrites
*slop*, not *voice*.