Metadata-Version: 2.5
Name: sk4n
Version: 0.1.0
Summary: Command-line tools and agent skills for NUS services
Project-URL: Homepage, https://github.com/hykzr/sk4n
Project-URL: Repository, https://github.com/hykzr/sk4n
Project-URL: Issues, https://github.com/hykzr/sk4n/issues
Project-URL: Changelog, https://github.com/hykzr/sk4n/blob/main/CHANGELOG.md
Author: hykzr
Maintainer: hykzr
License-Expression: MIT
License-File: LICENSE
Classifier: Development Status :: 3 - Alpha
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Requires-Python: >=3.11
Requires-Dist: beautifulsoup4>=4.14.3
Requires-Dist: platformdirs>=4.5.1
Requires-Dist: playwright>=1.60.0
Requires-Dist: requests>=2.34.2
Requires-Dist: rich>=15.0.0
Requires-Dist: urllib3>=2.7.0
Description-Content-Type: text/markdown

# SkillKit for NUS

SkillKit for NUS (`sk4n`) is a small toolkit for everyday NUS student tasks.
It can help you look through Canvas, search NUSMods, browse TalentConnect jobs, 
and give supported AI assistants a reliable way to use the same tools.

## What can it do?

- **Canvas:** sign in with NUS SSO; ckeck courses, read assignments, upcoming
  items, files, announcements, modules, pages, people, and groups.
- **NUSMods:** search courses, view course details and comments, and keep a
  local timetable using NUSMods share links. No login is needed.
- **TalentConnect:** search jobs and companies, including information available
  after signing in with NUS SSO.
- **Agent skills:** install ready-made skills for ChatGPT Work / Codex, GitHub
  Copilot, Claude Code, and Google Antigravity.

## Before you use it

This is an unofficial, independent project. It is not affiliated with,
endorsed by, or supported by the National University of Singapore (NUS),
Instructure/Canvas, NUSMods, Kinobi/TalentConnect, or any supported AI
platform.

It is intended as a personal study and workflow aid. Follow NUS policies and
the terms, rules, and acceptable-use requirements of every platform you access.
AI and CLI output can be incomplete or wrong, so check important information
against the original source. The software comes with no warranty of accuracy,
reliability, or fitness for a particular purpose; see the
[MIT License](https://github.com/hykzr/sk4n/blob/main/LICENSE).

## Install

**Not computing major or don't want to struggle with installation? You can try to ask your agent `help me install https://github.com/hykzr/sk4n/` and let it do everything in this step for you**

You need to install Python 3.11 or newer with pip first.

```bash
python -m pip install sk4n
```

If this command fail because the system cannot find `python` command,
try replacing `python` with `py` (for Windows), or `python3` (on MacOS or Linux)

The one `sk4n` installation gives you four commands:

```text
sk4n
canvas
nusmods
talent-connect
```

### One extra setup step for Canvas and TalentConnect

Canvas and TalentConnect use a small automated browser (chromium) to handle NUS SSO. Set
it up once after installing:

```bash
sk4n browser install chromium
```

NUSMods does not need this browser or an NUS login.

### One extra setup step for AI assistants

Sometimes an AI assistant needs to look at a Canvas or TalentConnect page that
the regular commands cannot fully read. For those cases, sk4n uses
`playwright-cli`, a browser tool made for coding agents.

`playwright-cli` needs Node.js 18 or newer. After
[installing Node.js](https://nodejs.org/en/download), run:

```bash
npm install -g @playwright/cli@latest
playwright-cli install-browser
```

This is separate from the Chromium setup above: that browser handles your NUS
login, while this one lets your AI assistant inspect a signed-in page when
needed.

sk4n also comes with a `doctor` command to help you check if everything is
correctly installed:

```bash
sk4n doctor
```

## Use it with an AI assistant

The package includes optional agent skills for Canvas, NUSMods, and
TalentConnect. To install them for all supported assistants on your computer:

```bash
sk4n skills install --agents all --scope user
sk4n skills status --agents all --scope all
```

You can choose one assistant instead, for example `--agents codex`. Installing
a skill helps the assistant call the CLI consistently, but it does not make AI
answers automatically correct. Check important dates, requirements, course
information, and job details against the original platform.

## CLI examples

### Find courses with NUSMods

```bash
nusmods search "machine learning"
nusmods course CS1010
```

You can also import an existing timetable share link:

```bash
nusmods schedule import 'https://nusmods.com/timetable/sem-1/share?...'
```

[More NUSMods examples](https://github.com/hykzr/sk4n/blob/main/src/sk4n/nusmods/README.md)

### Check Canvas

The first login opens a browser window for NUS SSO:

```bash
canvas auth login
canvas list
canvas todo
canvas upcoming
```

Once a course has been synced, you can inspect its saved content:

```bash
canvas course CS1010 assignments list
canvas course CS1010 announcements list
```

[More Canvas examples](https://github.com/hykzr/sk4n/blob/main/src/sk4n/canvas/README.md)

### Search TalentConnect

```bash
talent-connect auth login
talent-connect fetch --query engineer --max-jobs 20
talent-connect fetch --saved
```

For a public search that does not open the NUS login:

```bash
talent-connect fetch --no-login --query engineer --max-jobs 20
```

[More TalentConnect examples](https://github.com/hykzr/sk4n/blob/main/src/sk4n/talent_connect/README.md)

### Check the NUS academic week

```bash
sk4n calendar
sk4n calendar --date 2026-08-14
```

This uses public NUSMods calendar data and does not need an NUS login.

## Where is my data?

Run this to see the exact folders used on your computer:

```bash
sk4n paths
```

Canvas and TalentConnect save browser session information so you do not need to
sign in for every command. Treat those session files like login credentials:
do not share or upload them.

To forget a saved login without signing your other browsers out of NUS SSO:

```bash
canvas auth logout
talent-connect auth logout
```

## If the command is not found

First, close and reopen your terminal after installing. If the command is still
missing, Python's Scripts folder may not be on your `PATH`. 

## Contribute

This section is for contributors working from a repository clone. Ordinary
users do not need any of these tools.

### `uv` workflow

This repo uses `uv` to manage venv. see [uv install](https://docs.astral.sh/uv/getting-started/installation/)

```bash
uv sync
uv run pytest -q
uv run ruff --config pyproject.toml check .
uv run pyright
uv run python scripts/generate_skill_references.py --check
uv run pip-audit --strict --progress-spinner off .
```

### Optional `just` shortcuts

If [`just`](https://github.com/casey/just#installation) is installed, these
shortcuts are available:

```bash
just format
just check # same as test + lint + check references
just build
```

Neither `just` nor `uv` is needed by people who install `sk4n` from PyPI.
