Content Alchemy

Turn articles, web pages, PDFs, and excerpts into structured notes, key insights, practical actions, and reusable takeaways.

Security Scan

The skill's code, required binaries, and runtime instructions align with its stated purpose of extracting and transforming web and PDF content into notes; there are no obvious incoherent or disproportionate requirements, but some files were truncated in the report so a full audit of the web extractor and remaining scripts is recommended.

Purpose & Capability

The name/description (transform articles, web pages, PDFs into structured notes) matches the included scripts and instructions. Requesting python3, pdftotext and pdfinfo is appropriate for a PDF/text extraction and processing workflow.

Instruction Scope

SKILL.md limits behavior to three routes (plain_text, web_url, pdf_file) and instructs running the local Python scripts. The scripts read PDFs, plan/maintain session state, extract text, and save results. They accept user-supplied file paths and save session artifacts under ~/.content-alchemy by default — expected for persistent PDF sessions. No instructions ask the agent to read unrelated system config or secret env vars. Caveat: some files were truncated in the report (notably the full content of the web extractor and remaining scripts), so those specific scripts should be inspected to confirm they only fetch the requested URLs and do not phone home or exfiltrate data.

Install Mechanism

There is no install spec (instruction-only execution of bundled scripts). That minimizes supply-chain risk because nothing is downloaded or executed from remote URLs during install. The runtime does call system binaries (pdftotext/pdfinfo) which are standard for PDF text extraction.

Credentials

The skill declares no required environment variables or credentials. It writes session files under a user-owned directory (~/.content-alchemy/sessions) and otherwise operates on user-supplied files/URLs — this is proportional to its stated functionality.

Persistence & Privilege

The skill is not flagged as always: true and does not request elevated privileges. It stores its own session artifacts (normal for a long-PDF workflow) and does not modify other skills or system-wide agent settings in the visible code.

Assessment

This skill appears coherent with its stated purpose: it uses python3 plus pdftotext/pdfinfo to extract text and contains scripts to plan/read/record PDF sessions and to extract web text. Before installing or running it, review the full contents of the omitted/truncated files (especially extract_web_text.py and any other network-handling code) to confirm they only fetch the URLs you provide and do not transmit data to unknown endpoints. Be aware the scripts will read user-supplied file paths and write session artifacts (default: ~/.content-alchemy/sessions). Avoid pointing the skill at sensitive system files and confirm pdftotext/pdfinfo are the official system packages on your machine. If you need higher assurance, request the full listing of the omitted scripts for a complete audit.

Skill Purpose

Use this skill to transform reading input into reusable personal outcomes rather than plain summaries.

Supported input types:

• article text
• web URLs
• extracted web text
• PDF files
• book excerpts
• long explanatory passages

Expected output shape:

• structured notes
• key insights
• actionable next steps
• reusable takeaway

When To Use

Prefer this skill when the user wants something like:

• "Turn this article into something I can keep"
• "Extract the useful takeaways from this page"
• "Turn this PDF into notes and actions"
• "Help me continue reading this long PDF"
• "Summarize this content, but make it more useful than a plain summary"

Differentiation Rules

Always follow these rules:

1. Do not treat the task as plain summarization.
2. Reconstruct value, structure, and usefulness instead of merely compressing content.
3. The output should feel like a saved personal artifact, not model paraphrase.
4. Every result should improve at least one of these:
   • easier to revisit
   • easier to retain
   • easier to act on
   • easier to reuse
5. If the result still reads like a generic summary, restructure it again.

Scope and Limits

This release supports three routes:

• plain_text
• web_url
• pdf_file

This release does not directly handle:

• OCR for scanned PDFs
• code analysis workflows
• pure table-first analysis
• fragmented, image-first inputs with little readable text

If text extraction fails or text quality is too low, say so clearly and recommend OCR or source text.

Script Rules

When running bundled scripts:

• always use python3
• prefer absolute paths from the installed skill directory
• do not assume the current working directory is the skill directory

Recommended setup:

SKILL_ROOT="$HOME/.claude/skills/content-alchemy"

Content transformation is performed directly by the model.

• There is no process_content_alchemy.py script.
• Do not invent a hidden processing script.
• If you need a fixed output structure, use:
  • templates/result_template.md
  • templates/checkpoint_template.md

Input Route A: plain_text

Use this route for:

• article bodies
• extracted web content
• excerpts
• long explanatory text

Process directly in-model using the outcome-oriented structure.

Input Route B: web_url

When the input is a URL:

1. Run extract_web_text.py
2. Extract title, site, author, publication time, and body text
3. Check whether the extraction is strong enough to support transformation
4. If not, explain the limit and ask for source text

Command:

python3 "$SKILL_ROOT/scripts/extract_web_text.py" "https://example.com/article"

Troubleshooting only:

python3 "$SKILL_ROOT/scripts/extract_web_text.py" "https://example.com/article" --insecure

Input Route C: pdf_file

When the input is a PDF:

1. Run plan_pdf_reading.py
2. Determine the strategy from page count and text quality
3. Use extract_pdf_text.py for the appropriate page range
4. For longer PDFs, initialize or restore state and proceed segment by segment

Plan command:

python3 "$SKILL_ROOT/scripts/plan_pdf_reading.py" "/path/to/file.pdf"

The planning result returns:

• session_root
• plan_file
• state_file
• commands
• segment_results_dir
• checkpoint_results_dir

Prefer the exact returned paths and commands instead of guessing filenames.

Extract a page range:

python3 "$SKILL_ROOT/scripts/extract_pdf_text.py" "/path/to/file.pdf" --page-start 1 --page-end 5

Initialize or restore state:

python3 "$SKILL_ROOT/scripts/update_pdf_session_state.py" init --plan-file "<returned plan_file>" --state-file "<returned state_file>"

Force reset only when the user explicitly wants to restart:

python3 "$SKILL_ROOT/scripts/update_pdf_session_state.py" init --plan-file "<returned plan_file>" --state-file "<returned state_file>" --force-reset

Move to the next segment:

python3 "$SKILL_ROOT/scripts/update_pdf_session_state.py" next --state-file "<returned state_file>"

Save the current segment result:

python3 "$SKILL_ROOT/scripts/record_pdf_segment_result.py" --state-file "<returned state_file>" --content-file "/path/to/segment-result.md"

Build the next checkpoint package:

python3 "$SKILL_ROOT/scripts/build_pdf_checkpoint.py" --state-file "<returned state_file>"

Save a checkpoint summary:

python3 "$SKILL_ROOT/scripts/record_pdf_checkpoint.py" --state-file "<returned state_file>" --content-file "/path/to/checkpoint-summary.md"

Show session progress:

python3 "$SKILL_ROOT/scripts/summarize_pdf_session.py" --state-file "<returned state_file>"

Find the most recent saved PDF session:

python3 "$SKILL_ROOT/scripts/find_recent_pdf_session.py"

PDF Routing Rules

Default routing by page count:

• 1-40 pages -> single_pass
• 41-150 pages -> segmented_read
• 151-400 pages -> long_form_read
• 401+ pages -> book_mode

If multi-window sampling still reports low_text_pdf = true, treat the PDF as likely scanned, image-based, or low-quality text.

Session State Rules

For segmented_read, long_form_read, and book_mode:

1. Initialize state before the first reading step.
2. Read state before continuing.
3. Update state before previous / next / jump actions.
4. Do not rely on chat memory alone in a new session.
5. If state is missing, re-plan or re-initialize instead of pretending progress exists.
6. Prefer returned commands from the planning result whenever available.
7. Restore saved progress by default unless the user explicitly asks to restart.
8. Save every completed segment result immediately.
9. Build checkpoint source material before writing a checkpoint summary.

Existing Session Behavior

If plan_pdf_reading.py returns an existing_session:

1. "Continue next segment" should restore state and then move forward.
2. "Resume from last position" should restore state and read the current segment without advancing.
3. "Where am I?" or "reading status" should call summarize_pdf_session.py.
4. Only use --force-reset when the user explicitly wants to restart from the beginning.

In status summaries, distinguish clearly between:

• total completed segments
• contiguous completion from the beginning
• the earliest incomplete checkpoint window

Output Structure

Default segment results should use this shape:

1. Source information
2. Content theme
3. Three core ideas
4. Reconstructed structure
5. Key insights
6. Actionable next steps
7. Reusable takeaway

For checkpoints:

1. stage range
2. stage theme
3. core findings
4. reconstructed structure
5. key insights
6. follow-up actions or reading guidance
7. reusable checkpoint takeaway

Writing Rules

• The model writes the transformation directly.
• Write result content to a temporary markdown file first.
• Then call the correct record script to save it into the official session structure.
• Do not manually write final segment-XXX.md or checkpoint-XXX.md files unless the record script is intentionally bypassed for debugging.