Blackscience Tech Skills

Task-first agent skills for research, evaluation, developer tooling, and document workflows.

This repository distributes the same skills/ tree in three practical ways:

• as a native Codex repo plugin
• as a generated Claude Code marketplace
• as a plain local skills directory for tools that read skill roots directly

The repository is intentionally project-owned. First-party skills live here; official or third-party skills should stay in their own upstream repositories instead of being vendored into this tree.

Choose the shortest path for your environment.

Install this repository as a repo-local plugin when you already have the checkout on disk.

1. Clone the repository locally.
2. Open the repository in the Codex app.
3. Restart Codex if the repo was already open before the marketplace files existed.
4. Open the plugin directory, choose the Blackscience Tech Skills marketplace, and install the Blackscience Tech Skills plugin.

The Codex marketplace entry points at the repository root, so Codex loads .codex-plugin/plugin.json and the existing skills/ tree without an extra wrapper directory.

If you do not want to clone the repository first, install from the GitHub URL with skill-installer.

Use $skill-installer to install skills from https://github.com/tcztzy/skills.

To install only one skill:

Use $skill-installer to install the `skill-manager` skill from https://github.com/tcztzy/skills.

If a newly installed skill does not appear immediately, restart Codex.

This repository also exposes a Claude marketplace manifest at .claude-plugin/marketplace.json.

After the repository is pushed to GitHub:

1. Add the repository as a marketplace in Claude Code.
2. Enable the individual plugins you want from that marketplace.

The Claude manifest is generated from the installable skill directories under skills/, so the plugin list stays aligned with the repository contents.

If you prefer direct filesystem-based loading, point your local skill roots at this repository's skills/ directory.

REPO_ROOT=/path/to/tcztzy-skills
ln -sfn "$REPO_ROOT/skills" "$HOME/.codex/skills"
ln -sfn "$REPO_ROOT/skills" "$HOME/.claude/skills"

That keeps skill lookup stable for repository-local helpers such as:

• $CODEX_HOME/skills/skill-manager/scripts/validate-skill.py
• $CODEX_HOME/skills/paper-visualizer/scripts/manuscript_figure.py

The same layout is also suitable for OpenClaw-compatible workflows that read a skills/ directory directly.

The catalog is organized around user tasks instead of tool brands.

The repository is strongest when multiple research-oriented skills are composed into one loop instead of used as isolated one-off tools.

flowchart TD
    A["Research question / initial observation / spark"] --> B{"Is the direction already shaped?"}
    B -->|No| C["research-ideation-novelty-check<br/>Generate candidate ideas and run novelty sanity checks"]
    B -->|Yes| D["research-impact-strategy<br/>Decide GO / KILL / PIVOT / SCOPE-DOWN"]
    C --> D
    D -->|KILL| Z["Stop this direction / change topics / tighten the scope again"]
    D -->|GO / PIVOT / SCOPE-DOWN| E["zotero + paper-writer<br/>Collect literature, harvest citations, export BibTeX"]
    E --> F["Collect data / run experiments / organize raw artifacts"]
    F --> G["paper-visualizer<br/>Route chart family and generate manuscript-ready figures and plots"]
    G --> J["experiment-log-summarizer<br/>Condense the run directory into summary.md / summary.json"]
    J --> K{"Do the evidence and story now close the loop?"}
    K -->|No: positioning or claim is weak| D
    K -->|No: data or experiments are still insufficient| F
    K -->|Yes| L["paper-writer<br/>Turn ideas, logs, plots, and citations into a paper draft"]
    L --> M["paper-reviewer<br/>Pre-review argument, structure, figures, and layout"]
    M --> N{"Is it ready to submit?"}
    N -->|Run more experiments| F
    N -->|Revise the story or tighten the claim| D
    N -->|Revise the draft, figures, or citations| L
    N -->|Yes| O["Submit / rebuttal / next revision round"]

Recommended minimum loop:

1. research-ideation-novelty-check
2. research-impact-strategy
3. zotero or paper-writer for bibliography work
4. paper-visualizer
5. experiment-log-summarizer
6. paper-writer
7. paper-reviewer

The intended operating model is:

• decide whether the story is worth pursuing before drafting
• summarize experiment artifacts before turning them into prose
• use one visualization entry point instead of splitting by plotting backend
• use one manuscript-writing entry point instead of fragmenting adjacent paper tasks
• run a bounded review pass before submission

• skills/: all discoverable skills
• skills/<skill-name>/: installable skills when the directory contains SKILL.md
• helper-only directories may exist under skills/ without being exported as installable entries

Repository metadata is split by consumer:

• .codex-plugin/plugin.json: native Codex plugin manifest
• .agents/plugins/marketplace.json: Codex marketplace entry for this repository
• .claude-plugin/marketplace.json: Claude marketplace manifest generated from skill metadata

Regenerate the Claude marketplace after adding, removing, renaming, or updating installable skills:

python3 scripts/generate_claude_marketplace.py

Validate both Codex and Claude plugin metadata before pushing:

python3 scripts/validate_plugin_metadata.py

• Use precise, professional English unless a skill is explicitly language-specific.
• Keep top-level skills task-first rather than tool-first whenever possible.
• Keep upstream official skills such as playwright, pdf, or openai-docs in their original source repositories or use the built-in system skills that ship with Codex.