Skill: rycen7822/obclip (version 1.0.0)

--- name: obclip description: Install, verify, and operate the obclip CLI to clip live web pages into Markdown or Obsidian notes. Use when Codex needs to install the @harris7/obclip npm package, choose between default Playwright Chromium and a real Chromium executable/profile, run clipping commands with stable waiting rules, save notes to disk or Obsidian, or diagnose incomplete capture, login walls, and browser startup issues. --- # Obclip Use this skill to make `obclip` work predictably instead of trial-and-error. ## Workflow 1. Verify how `obclip` should be invoked. 2. Pick the browser mode that matches the target site. 3. Run the smallest command that can succeed. 4. Escalate waiting and browser state only when the output is incomplete. 5. Report the final saved path or the concrete failure reason. ## 1. Verify Invocation - Prefer `obclip` if it is already on `PATH`. - If `obclip` is missing, install the npm package from [install-and-invoke.md](./references/install-and-invoke.md). - If you are working inside the source repo and the global command is unavailable, fall back to `node <repo>\\dist\\cli.cjs ...`. - After installation, verify with `obclip --help` or `npx @harris7/obclip --help`. ## 2. Pick Browser Mode - Use the default bundled Playwright Chromium for public pages that do not need login state. - Use `--browser-executable "<path>"` when the user already has a dedicated Chromium build and wants a fixed browser binary. - Use `--browser-profile "<dir>"` for sites that require login state, cookies, or a persistent session. - Use `--headful` when the user needs to see the browser or perform the initial login into a fresh profile. - Do not point `--browser-profile` at the user's normal daily Chrome profile. Prefer a dedicated profile directory. ## 3. Start With The Smallest Command - Default public-page capture: `obclip <url> --output "<dir>\\"` - Logged-in or anti-bot page: add `--browser-executable`, `--browser-profile`, and usually `--headful` - If the user wants Markdown on stdout, omit `--output` - If the user wants the note opened in Obsidian, add `--open` and the optional vault/URI flags Use the concrete command templates in [command-recipes.md](./references/command-recipes.md). ## 4. Escalate Waiting In Order - First run without custom waits when the page is simple. - If the page is incomplete but visibly loading dynamic content, add `--settle-ms 3000` or `--settle-ms 5000`. - If the page is an SPA and the content mounts later, add `--wait-selector "<css>"`. - Prefer broad, content-bearing selectors such as `article`, `main`, `[role="main"]`, or a stable post container. Avoid selectors that only match nav, login shells, or skeleton loaders. - If the page still shows a login wall, fix browser state with `--browser-profile`; extra delay does not solve missing authentication. Use [troubleshooting.md](./references/troubleshooting.md) when the first pass fails. ## 5. Interpret Results Correctly - Successful file saves print `Saved note: <full-path>` to `stderr`. - Failures print a direct reason such as save failure, invalid browser path, or wait timeout. - Keep `stdout` clean unless the user explicitly wants the Markdown body in the terminal or piped into another command. ## 6. Windows Path Rules - Quote Windows paths that may contain spaces. - For `--output`, prefer an existing directory or a path ending in `\\` or `/` when you want directory semantics. - Example: `--output "D:\\data\\Clippings\\"` ## References - Installation and invocation: [install-and-invoke.md](./references/install-and-invoke.md) - Command templates: [command-recipes.md](./references/command-recipes.md) - Failure handling: [troubleshooting.md](./references/troubleshooting.md)

path: references/command-recipes.md
content: # Command Recipes

## Public Page To Markdown File

```powershell
obclip "https://example.com/article" --output "D:\data\Clippings\"
```

## Public Page To stdout

```powershell
obclip "https://example.com/article"
```

## Real Chromium With Dedicated Profile

```powershell
obclip "https://example.com/article" `
  --browser-executable "D:\app\chrome-win\chrome.exe" `
  --browser-profile "D:\obclip-profile" `
  --headful `
  --output "D:\data\Clippings\"
```

## Dynamic SPA With Extra Delay

```powershell
obclip "https://example.com/app" `
  --settle-ms 5000 `
  --output "D:\data\Clippings\"
```

## Dynamic SPA With Explicit Wait Selector

```powershell
obclip "https://example.com/app" `
  --wait-selector "article" `
  --settle-ms 3000 `
  --output "D:\data\Clippings\"
```

## Logged-In X Or Similar Social Page

```powershell
obclip "https://x.com/<user>/status/<id>" `
  --browser-executable "D:\app\chrome-win\chrome.exe" `
  --browser-profile "D:\obclip-x-profile" `
  --headful `
  --wait-selector "article" `
  --settle-ms 5000 `
  --output "D:\data\Clippings\"
```

## Open The Result In Obsidian

```powershell
obclip "https://example.com/article" `
  --output "D:\data\Clippings\" `
  --open `
  --vault "MyVault"
```

## Template Override

```powershell
obclip "https://example.com/article" `
  --template "D:\data\obclip-templates" `
  --output "D:\data\Clippings\"
```

## Notes

- Add `--wait-selector` only when the default waiting rules plus `--settle-ms` are insufficient.
- Use a dedicated browser profile for login-heavy or anti-bot sites.
- Successful saves print the final full path to `stderr`.


path: references/install-and-invoke.md
content: # Install And Invoke `obclip`

## Install The Codex Skill

When the user wants this skill installed into Codex, use:

```text
Use $skill-installer to install the skill from https://github.com/Rycen7822/obclip-skill/tree/main/skills/obclip
```

After installation, tell the user to restart Codex so the new skill is discovered.

## Install The npm Package

Prefer a global install when the user wants the `obclip` command on `PATH`:

```powershell
npm install -g @harris7/obclip
obclip --help
```

Use `npx` when the user does not want a global install:

```powershell
npx @harris7/obclip --help
```

## Local Source-Repo Fallback

When working directly in the source repo and no global command exists:

```powershell
cd D:\dev\ob-web-clip\obclip
npm run build
node .\dist\cli.cjs --help
```

## Decide Which Invocation To Use

- Use `obclip ...` when the command already resolves.
- Use `npx @harris7/obclip ...` when the package is not installed globally.
- Use `node .\dist\cli.cjs ...` when developing inside the repo.

## Verify Before Clipping

Run one of these before using the tool on a real page:

```powershell
obclip --help
npx @harris7/obclip --help
node .\dist\cli.cjs --help
```


path: references/troubleshooting.md
content: # Troubleshooting

## `obclip` Is Not Recognized

Cause:
- The npm package is not installed globally.
- The shell has not picked up the global npm bin path yet.

Fix:
- Run `npm install -g @harris7/obclip`
- Open a new shell and retry
- Or use `npx @harris7/obclip ...`
- Or use `node .\dist\cli.cjs ...` inside the source repo

## Saved Note Is Incomplete

Cause:
- The page was still hydrating when extraction ran.
- The site mounted content after initial load.

Fix:
1. Add `--settle-ms 3000` or `--settle-ms 5000`
2. If still incomplete, add `--wait-selector "<css>"`
3. Use a content selector such as `article`, `main`, or a stable post container

## Page Shows Login Or Signup Shell

Cause:
- The browser session has no login state.

Fix:
1. Use `--browser-profile "<dir>"`
2. Use `--headful` the first time if manual login is needed
3. Reuse the same dedicated profile on later runs

Delay alone does not solve authentication problems.

## Browser Path Fails

Cause:
- `--browser-executable` points to a missing file or a non-Chromium browser path.

Fix:
- Verify the file exists
- Quote the full Windows path
- Retry with the known good Chromium path

## Profile Directory Is Busy

Cause:
- Another browser process is already using the same profile directory.

Fix:
- Close the other browser process
- Or use a different dedicated profile directory

## Output Directory Behaves Like A File Path

Cause:
- `--output` points to a non-existent path without a trailing slash

Fix:
- Use an existing directory
- Or make directory intent explicit: `--output "D:\data\Clippings\"`

## Chromium Prompts For Network Access

Cause:
- The OS or security software is asking whether the browser binary may access the network

Fix:
- Allow the browser once in the OS dialog
- Prefer a fixed Chromium executable path instead of relying on temporary bundled browser locations


path: assets/install-obclip-skill.txt
content: Use $skill-installer to install the skill from https://github.com/Rycen7822/obclip-skill/tree/main/skills/obclip and then restart Codex to pick up the new skill.


path: agents/openai.yaml
content: interface:
  display_name: "Obclip"
  short_description: "Install and run obclip for reliable page clipping"
  default_prompt: "Use $obclip to install or run the obclip CLI and capture a target page into a note."
policy:
  allow_implicit_invocation: true


Security scan verdicts — ClawScan: clean | static analysis: clean | VirusTotal: clean | SkillSpector: clean (LOW)