awl-academic-rewriter

Rewrite English prose sentence by sentence into a more academic version using the bundled AWL/NAWL vocabulary list. Use when the user asks to academicize, po...

Security Scan

This skill is internally consistent with its stated purpose: it rewrites text into a more academic register using the bundled AWL/NAWL word lists, and it does not request credentials, network access, or suspicious installs.

Purpose & Capability

The skill name, description, SKILL.md, bundled vocabulary files, and helper script all align with an academic-rewriting purpose. Minor mismatch: the registry metadata lists no required binaries, but the SKILL.md examples invoke 'python3 scripts/awl_lookup.py' and a Python helper script is included — so a runtime with Python is effectively required even though it's not declared.

Instruction Scope

SKILL.md instructions are narrowly scoped to reading user-provided text (message or files), consulting the bundled AWL headwords/CSV via the included helper, and producing two Markdown output files. The helper script can read files passed via CLI flags (--headwords, --csv, --text-file), so if an agent or user deliberately supplies arbitrary paths the script could read other local files — but the documented normal workflow only accesses files inside the skill directory and user-provided input.

Install Mechanism

No install spec, no external downloads, and all required resources are bundled (script + reference files). This is low-risk from an install perspective.

Credentials

The skill declares no required environment variables, no credentials, and does not attempt to access external services. There are no disproportionate secret or env requirements.

Persistence & Privilege

The skill does not request 'always: true' and does not modify other skills or system-wide settings. It can be invoked autonomously per platform defaults, which is expected for skills and not flagged here.

Assessment

This skill appears to do what it says: it uses the included AWL/NAWL lists and a small Python helper to produce a sentence-level change report and a full revised document. Before installing, note: (1) the skill assumes a runtime with Python available if you want to run the helper script; (2) it will read any user-supplied input files and write two Markdown output files to the working directory; (3) the helper script accepts file-path arguments, so avoid passing sensitive system paths as inputs; and (4) there are no network calls or credential requests, but you should still review the bundled vocabulary files if you have intellectual-property or privacy concerns. If you need the agent to not execute local scripts, disallow executing python commands in the agent environment or instruct the agent to run in a restricted mode.

Purpose

Use the first-column AWL/NAWL headword list in references/awl-headwords.txt to revise English text into a more academic register. Let the model judge, sentence by sentence, which ordinary or imprecise expressions can be replaced by suitable academic vocabulary. Preserve the original meaning, tense, aspect, modality, negation, certainty level, evidence strength, and document structure unless a grammar correction requires a local change.

Resources

• references/awl-headwords.txt: default vocabulary source; one first-column AWL/NAWL headword per line.
• references/awl.csv: full source table for selected headwords only. Columns are Word, Derivatives, and English Definition.
• scripts/awl_lookup.py: headword helper for listing, filtering, verifying first-column membership, retrieving all three CSV columns for selected headwords, and detecting headwords already present in input text. It does not score semantic replacement candidates.

Use the helper from the skill directory, for example:

python3 scripts/awl_lookup.py --all --limit 40
python3 scripts/awl_lookup.py --contains analy
python3 scripts/awl_lookup.py --word analysis --word analyze
python3 scripts/awl_lookup.py --details analysis --details factor
python3 scripts/awl_lookup.py --text-file input.txt

Required Output Files

Always save two Markdown files unless the user explicitly asks for a different format:

1. Change report: if the input has a filename, use <stem>-academic-changes.md; otherwise use academic-revision-changes.md.
2. Complete revised document: if the input has a filename, use <stem>-academic-revised.md; otherwise use academic-revised-document.md.

The change report must contain a sentence-by-sentence table with these columns:

| # | Original sentence | Revised sentence | AWL/NAWL terms used | Modification method |
|---|---|---|---|---|

In Modification method, state concrete edits, such as vocabulary substitution, grammar correction, clause restructuring, hedging, nominalization, or cohesion improvement. Keep explanations concise and do not invent reasons not visible in the text.

The complete revised document must contain only the revised text, preserving the original headings, paragraph order, list structure, citations, quoted material, numbers, and formatting as much as possible.

Workflow

1. Read the input text from the user's message or file. If the user gives multiple files, process each file separately unless they ask for a merged output.
2. Preserve structural units first: headings, paragraphs, lists, tables, citations, code blocks, formulas, references, and quoted passages.
3. Split prose into sentences within each paragraph. Avoid splitting inside common abbreviations, decimal numbers, initials, citations, or parenthetical references.
4. Identify sentence meaning and rhetorical function before rewriting. Do not replace words merely because an academic synonym exists.
5. Use references/awl-headwords.txt as the candidate vocabulary set. Do not rely on automatic synonym scoring. For each sentence, let the model decide whether any source word or phrase can be replaced by a headword from the list without changing meaning.
6. After selecting candidate headwords, query references/awl.csv for those specific headwords and retrieve all three columns. Prefer python3 scripts/awl_lookup.py --details <headword> instead of loading the full CSV.
7. Use the retrieved Derivatives and English Definition to confirm semantic fit and select the correct grammatical form.
8. Rewrite each sentence according to the constraints below.
9. Reassemble the revised document in the original order and write both required Markdown files.
10. Run a final consistency pass comparing original and revised sentences for meaning, tense, factual claims, entity names, citations, and formatting.

Headword-Based Replacement Method

For each sentence:

1. Identify the sentence's core proposition, tense, stance, and logical relations.
2. Identify ordinary, vague, conversational, or grammatically weak expressions that could be made more academic.
3. Consult references/awl-headwords.txt and select tentative headwords that may express the intended meaning in context.
4. Query references/awl.csv for each tentative headword and inspect all three columns: Word, Derivatives, and English Definition.
5. Confirm the definition fits the sentence meaning. Use a listed derivative when it is the best grammatical form; otherwise use an inflected form of the headword only if it remains semantically faithful.
6. Record the first-column headword in the change report even when the revised sentence uses a derivative.
7. Do not replace a word if the retrieved definition or derivative list suggests the headword would make the sentence less precise, more inflated, or semantically different.

This skill deliberately places semantic judgment on the model rather than on scripts/awl_lookup.py. The script is only a compact vocabulary access and verification tool.

Rewriting Constraints

• Preserve the source meaning and factual scope. Do not add claims, evidence, citations, statistics, causal relationships, or certainty that the source does not contain.
• Preserve tense, aspect, modality, polarity, and degree. For example, do not turn "may reduce" into "reduces" or "did not find" into "found".
• Replace only vocabulary that improves academic precision, formality, or cohesion. It is acceptable for a sentence to receive no AWL/NAWL substitution if substitution would distort meaning.
• Introduce academic vocabulary only when its first-column headword appears in references/awl-headwords.txt and its full references/awl.csv row has been checked. Use a grammatical derivative or inflected form when necessary, but list the base headword in AWL/NAWL terms used.
• Correct grammar, punctuation, article use, agreement, and awkward syntax when needed.
• Prefer concise academic phrasing over inflated prose. Avoid overloading a sentence with multiple academic terms when one precise substitution is enough.
• Preserve technical terms, proper nouns, named methods, discipline-specific terms, citations, quoted text, numbers, units, and defined labels unless they contain clear grammar errors outside the quoted or fixed material.
• Keep paragraph structure and logical transitions stable. Add or adjust transitions only when they clarify an existing relationship.
• If the input includes non-prose elements such as code, equations, reference lists, or raw data, preserve them unchanged unless the user explicitly asks to revise them.

Quality Checks

Before finalizing, verify that:

• Every original prose sentence has one corresponding revised sentence in the change report.
• The complete revised document contains the same substantive content and order as the original.
• Each listed AWL/NAWL term maps to a first-column headword in references/awl-headwords.txt.
• Each selected headword has been checked against its full references/awl.csv row before final use.
• Grammar fixes do not change meaning or tense.
• The revised document reads as coherent academic English without sounding artificially synonym-substituted.