Scratchpad Example Extractor
Extracts the nearest JSDoc example from source into a runnable TypeScript scratchpad file.
The skill only reads source files and writes locally to a scratchpad directory, with no external network calls or sensitive data handling, and minimal permissions. However, the workflow requires automatic extraction and writing of code locally without explicit user confirmation (unless a runner is needed), and there is no rollback or cleanup mechanism beyond avoiding overwriting existing files. As an unverified publisher, source attribution is unclear. Therefore, score 12, with deductions for lacking explicit permission requests, user confirmation, and rollback mechanisms.
The script is well-structured with parameter validation and error handling, but no tests are provided and execution is not verified. The key paths (finding examples, selecting, generating unique filenames) appear sound under static analysis, but abnormal inputs (e.g., missing file, no examples) only print an error and exit, with feedback that could be more detailed. Since this is a static review, runnability cannot be confirmed, hence score 8, deductions for lack of tests and execution evidence, and mediocre error feedback.
The skill definition is clear, with well-defined usage scenarios (extract JSDoc examples to scratchpad), appropriate trigger conditions (user requests), and explicit non-fit cases (e.g., asking when no example). Environment fit is good as it relies only on local Node.js and filesystem, with no dependency on overseas services, thus accessible from mainland China. However, handling of Chinese comments or file names is not specified, which could lead to unreadable slugs, and when no example exists user interaction is required, slightly reducing trigger precision. Score 10, deductions for unspecified Chinese support and partial reliance on user interaction for triggers.
Documentation is clear with description, workflow, and behavior sections, and the script has usage comments. However, there is no version number, changelog, explicit maintenance owner, or known limitations disclosure. License is at repository level (MIT), not specific to the skill. Examples are in the overall README but the skill directory lacks FAQ or troubleshooting. Therefore score 8, deductions for missing versioning, maintenance responsibility, and limitations disclosure.
The core function is clear: extract JSDoc examples into TypeScript files, with automatic runner attachment to produce runnable code, offering marginal value over manual copy-paste. However, static review cannot verify that outputs are directly usable, and no evidence of actual usage is provided. When no runner exists, user intervention is required, adding interaction cost. As a static assessment, capped at 7, deductions for lack of execution verification and evidence of output usability.
The skill comes with script source code as primary evidence, but no test cases or CI integration covering this skill path are provided. The repository has CI workflows but they do not cover this skill. There is no cross-corroboration or independent reproduction. Therefore score 4, deductions for static-only review and lack of reproducible test evidence.
- The skill's script reads any specified file and extracts examples to a local scratchpad; if misused, it may read sensitive file contents, though it does not exfiltrate them, so use with care.
- The script lacks an explicit user confirmation step (unless runner selection is needed); auto mode may write files directly, so consider adding confirmation before critical actions.
- Publisher is unverified, so long-term maintenance is uncertain; review the code before use.
- For Chinese file names, the script may generate unreadable slugs, affecting output file recognizability.
What does this skill do, and when should you use it?
This skill locates the JSDoc `**Example**` section closest to the active cursor or selection in the source code and extracts it into a standalone TypeScript file in the `./scratchpad` directory. It runs a Node script to perform the extraction, intelligently handles filename conflicts, and optionally appends a runner call if a top-level `program` binding exists. This allows developers to quickly try out code examples without manually copying and pasting. The skill reports the created file path as a clickable link for easy access.
Determines the source path and line (from the IDE active file or explicit user input). Runs the command node .agents/skills/scratchpad/scripts/extract-example.mjs <source-path> <line>. The script selects the JSDoc Example block containing the line, or the nearest following/previous example. It writes a TypeScript file named like scratchpad/Schedule-retrying-and-repeating-effects.ts. If the file exists, it appends a numeric suffix to avoid overwriting. In auto mode, if a top-level program binding exists, it appends Effect.runPromise(program).then(console.log, console.error). If no obvious runner is found (exit code 2), it asks the user how to proceed: preserve exactly (--mode preserve) or specify a runner (--runner <identifier>). Finally, it reports the created file path as a clickable link.
- A developer wants to quickly test a JSDoc example from a library: they place the cursor in the example and ask to 'dump this example into scratchpad'.
- A user provides an explicit file path and line number to extract a specific example.
- When an example already contains an Effect runner, the skill preserves it, allowing immediate testing.
- When a user wants to run a specific Effect value from the example, they can use the `--runner` parameter.
- When a user needs to preserve the example exactly as-is without modifications, they can use `--mode preserve`.
- When a user wants to open the scratchpad file, the skill provides a clickable link.
What are this skill's strengths and limitations?
- Automates extraction of the nearest JSDoc example, saving time over manual copy-paste.
- Handles filename collisions by appending numeric suffixes.
- Automatically identifies and runs `program` bindings, or preserves existing Effect runners, enabling quick testing.
- Supports specifying a particular Effect value to run via `--runner`.
- Provides a clickable file link for easy opening in the editor.
- The script logic is clear and adaptable.
- Only supports JSDoc-style examples; other doc formats are not handled.
- Requires Node.js and the script from the repo; standalone use may require migrating dependencies.
- If no obvious runner exists, it requires user interaction, adding a step.
- No test suite is provided; stability is unverified.
- Extracted code may depend on project-specific types or modules, lacking context when run in isolation.
- Tested primarily in specific IDEs; compatibility with other environments is unconfirmed.
How do you install this skill?
This skill is part of the T3 Code repository. After obtaining the repo, the skill is located at .repos/effect-smol/.agents/skills/scratchpad/. To use it as a standalone skill, copy that folder into your agent skills directory (e.g., ~/.claude/skills/ or a project .agents/skills/). Node.js is required. For broader installation, see the README which offers methods like npx t3@latest or desktop apps.
How do you use this skill?
In a compatible IDE (Claude Code, Codex, Cursor, OpenCode), open a source file, place the cursor or selection near a JSDoc example. Trigger the skill by saying something like: "Put the nearest example into scratchpad." The skill will run the extraction script and return a clickable file link. To specify a file and line, provide them explicitly, e.g., "Extract the example at line 42 of src/foo.ts into scratchpad." Note: the skill will not automatically run the generated file unless you explicitly ask.
How does this skill compare with similar options?
This is a niche skill for a specific repo; it primarily competes with manual copying. Compared to generic code snippet tools, it is more focused on JSDoc examples and preserving Effect semantics. No other named alternatives exist.