Smooth Research Writing

Introduce each idea when the reader needs it, and explain why each result leads to the next step.

A portable skill for writing, revising, and diagnosing research prose. It helps agents motivate concepts, give experiments a purpose, connect paragraphs through reasoning, and keep interpretations within the evidence.

The skill text is preserved as supplied. The same file powers every integration; there are no runtime dependencies, hooks, or MCP servers.

Install

Choose one installation method per app to avoid duplicate skills. The GitHub commands below work once this repository's package files have been pushed; local installation works from this checkout or an extracted full ZIP.

Claude Code

Run in your terminal:

claude plugin marketplace add lucaswychan/ml-paper-writing-skill
claude plugin install smooth-research-writing@ml-paper-writing

Start a new session and invoke:

/smooth-research-writing:smooth-research-writing Revise the introduction in paper.tex, preserving its technical claims.

To try a downloaded or cloned package without registering a marketplace, run this from its root:

claude --plugin-dir .

Codex

In Codex, ask its built-in installer:

Use $skill-installer to install the skill at https://github.com/lucaswychan/ml-paper-writing-skill/tree/main/skills/smooth-research-writing

Alternatively, download the standalone skill ZIP, extract it, and place the resulting smooth-research-writing folder inside ~/.agents/skills/. From a cloned repository or extracted full package, the equivalent macOS/Linux commands are:

mkdir -p "$HOME/.agents/skills"
cp -R skills/smooth-research-writing "$HOME/.agents/skills/"

If that destination already exists, review or back up your existing skill before replacing it. On Windows, copy the folder into %USERPROFILE%\.agents\skills\ using File Explorer. For a project-only installation, use <project>/.agents/skills/ instead.

Start a new Codex session, then invoke:

$smooth-research-writing Diagnose the largest logical gap in the results section of paper.tex.

The full package also includes a root plugin.json for hosts supporting the portable Agent Plugins format. The standalone skill installation above does not require marketplace registration.

Pi

Run in your terminal:

pi install git:github.com/lucaswychan/ml-paper-writing-skill

For a local checkout or extracted full package, use pi install /absolute/path/to/smooth-research-writing instead. Keep that folder in place: Pi loads local packages from their path.

Start a new session, then invoke:

/skill:smooth-research-writing Explain why each experiment in results.md follows from the preceding result.

Other coding agents

For agents supporting the Agent Skills format, copy skills/smooth-research-writing/ into the app's documented skills directory. The skill needs only Markdown support; follow the host's own discovery and invocation conventions.

Example requests

• Write: “Use smooth-research-writing to draft an introduction from these findings and references. Preserve the stated limitations.”
• Revise: “Use smooth-research-writing to revise this section. Preserve the equations, citations, and technical meaning; flag unsupported connections.”
• Diagnose: “Use smooth-research-writing to identify the largest argument-level obstacle, quote the relevant passages, and propose a concrete revision.”

The skill guides prose and reasoning; it does not independently verify the paper's evidence. Supply the relevant results and sources so the agent can keep claims grounded.

Downloadable packages

Build with Python 3; no additional libraries are needed:

python3 scripts/build.py

This creates:

The build uses fixed archive timestamps for reproducible downloads. Extract the full ZIP before using a local installation command.

Maintainer release steps

1. Set a distribution license and add its text to the package before a public release.
2. Keep the version in plugin.json, .claude-plugin/plugin.json, and package.json aligned.
3. Run claude plugin validate . and python3 scripts/build.py. Inspect the ZIP contents; npm pack --dry-run previews the Pi npm payload if npm distribution is desired.
4. Push the repository so the GitHub installation commands can resolve it.
5. Create a GitHub release and attach both ZIPs and SHA256SUMS. Git installation requires no npm publication.

No public release or npm publication is implied by a local build. No license has been selected yet.

Packaging references

• Claude Code plugin manifests and marketplaces
• Codex skills and local discovery and OpenAI plugin packaging
• Pi packages and Pi skills