The README previously listed skill package names without making the
actual user-facing capabilities obvious, and several linked docs used
local absolute paths instead of repository-relative links. This change
reframes the entry point around tasks users can accomplish, adds real
feature pages for each supported workflow, and connects the install and
security docs to those pages with working relative links.
Constraint: Keep the change documentation-only and avoid introducing new dependencies
Rejected: Link directly to each SKILL.md | too implementation-centric for a README first impression
Rejected: Keep one short README and defer detail to package names | does not make capabilities obvious enough
Confidence: high
Scope-risk: narrow
Reversibility: clean
Directive: Keep README organized by user-facing jobs rather than internal skill identifiers unless the product positioning changes
Tested: Local markdown link validation across all .md files
Not-tested: GitHub web rendering preview after push
The train skills no longer share a generic wrapper. SRT now documents the dedicated SRTrain surface, and KTX now documents korail2 directly, which makes the install path, imports, and reservation examples match the libraries the user explicitly validated.
Constraint: SRT and KTX should stay separate skills with their own native library surfaces
Rejected: Keep the shared koreantrain abstraction | it hides the real backend and weakens trust in the examples
Confidence: high
Scope-risk: narrow
Reversibility: clean
Directive: Keep future train-skill examples aligned with the concrete upstream library each skill depends on
Tested: bash scripts/validate-skills.sh
Tested: Import and signature inspection for SRTrain and korail2 from temporary installs
Not-tested: Live login and booking against SRT and Korail services
The top-level page now acts as a short landing page instead of a long manual. Installation steps, agent copy-paste text, and package-runner fallback guidance live in a dedicated install document so first-time users can find them without bloating the README.
Constraint: The README should stay extremely short while still pointing new users to the right next step
Rejected: Keep detailed install prose in README | it makes the landing page noisy and harder to scan
Confidence: high
Scope-risk: narrow
Reversibility: clean
Directive: Keep README short; move future onboarding detail into focused docs unless it is essential at first glance
Tested: Manual review of README and docs/install.md links
Not-tested: Render verification on GitHub after push
The README now includes ready-made prompts that tell an agent how to inspect available k-skill packages, choose suitable ones, include k-skill-setup when needed, and summarize the next setup step. This lowers friction for first-time users who want the agent to handle installation.
Constraint: The onboarding path should work even for users who do not want to manually learn the skills CLI first
Rejected: Keep install instructions purely command-oriented | agent-first onboarding is part of the repo pitch
Confidence: high
Scope-risk: narrow
Reversibility: clean
Directive: Keep the prompt blocks short and copy-pasteable; avoid turning them into long manuals
Tested: Manual README review after update
Not-tested: Live copy-paste flow against a published remote repo
The previous README explained the project but did not yet function as a practical start page. It now leads with what k-skill is, how to install it, when setup is required, how the shared secret model works, and which Korean-targeted skills are planned next.
Constraint: The README should be readable first in Korean because the repo is intentionally Korea-targeted
Rejected: Keep the README as a short landing page and push usage details into subfiles | too much context switching for first-time users
Confidence: high
Scope-risk: narrow
Reversibility: clean
Directive: Keep the README optimized for first-use flow, and move deeper implementation detail into per-skill docs when it starts to bloat
Tested: Manual README review after rewrite
Not-tested: Render verification on GitHub after push
The first end-to-end verification exposed a mismatch between the documented .sops.yaml regex and the temporary plaintext filename used during bootstrap. The rule now matches both secrets.env and secrets.env.plain so the setup skill works exactly as documented.
Constraint: Setup docs must be mechanically correct, not just conceptually correct
Rejected: Change the bootstrap filename instead | broader docs churn for no practical gain
Confidence: high
Scope-risk: narrow
Reversibility: clean
Directive: Re-run the documented setup path after any future secret-handling doc edits
Tested: bash scripts/validate-skills.sh
Tested: sops --encrypt via .sops.yaml + sops exec-env with dummy secrets
Not-tested: Windows-specific setup commands beyond documentation review
Credential-bearing skills now point to a shared cross-platform setup based on sops plus age instead of a hosted password manager. The repo also gains a default setup skill and a small verification script so users can bring one encrypted secrets file to every relevant skill.
Constraint: The secret workflow must work on macOS, Linux, and Windows without mandatory vendor signup
Rejected: Keep 1Password CLI as the default | it requires account creation and sign-in
Rejected: Plaintext .env as the default | too easy to leak in a repo and too easy for tools to read at rest
Confidence: high
Scope-risk: moderate
Reversibility: clean
Directive: If a future skill needs stronger isolation than exec-env provides, expose a capability wrapper instead of injecting the raw secret
Tested: bash scripts/validate-skills.sh
Tested: npx --yes skills add . --list
Tested: bash scripts/check-setup.sh (expected failure without sops/age installed)
Not-tested: End-to-end sops encryption and exec-env flow on a machine with sops and age installed
KBO, lotto, and Seoul subway arrival are good v1 complements to train booking because they provide obvious Korean-local utility without requiring a thick integration layer. The subway skill still enforces secret injection because the official Open API key should never be handled as plaintext.
Constraint: v1 should prefer thin wrappers over existing packages and official APIs
Rejected: Add SmartStore or Kakao flows in the first pass | auth and policy surfaces are too heavy for a fast v1
Confidence: medium
Scope-risk: narrow
Reversibility: clean
Directive: Keep live-data skills compact and timestamped so answers do not overclaim freshness
Tested: bash scripts/validate-skills.sh
Not-tested: Live upstream responses from kbo-game, korean-lotto, and Seoul Open Data
SRT and KTX were the highest-signal v1 skills because existing Python tooling already exposes search and reservation flows. The skills intentionally split search from reservation so the agent can summarize choices before performing side effects.
Constraint: Booking actions are side-effectful and must not run on ambiguous train choices
Rejected: Merge SRT and KTX into one generic train skill | separate entry points are easier to discover and install
Confidence: medium
Scope-risk: moderate
Reversibility: clean
Directive: Keep reserve and cancel steps gated on an identified train or reservation target
Tested: bash scripts/validate-skills.sh
Not-tested: Live login and reservation against SRT/Korail services
The repo starts as a markdown-first multi-skill package with one shared security policy, one validation script, and lightweight install docs. This keeps v1 easy to publish and easy to review before any skill-specific automation grows deeper.
Constraint: Skills must stay compatible with the skills CLI package layout
Rejected: Add a repo-level manifest or build system | the package spec only requires per-skill SKILL.md
Confidence: high
Scope-risk: narrow
Reversibility: clean
Directive: Keep credential-bearing skills on 1Password CLI runtime injection, not plaintext env files
Tested: bash scripts/validate-skills.sh
Not-tested: Fresh-machine install via npx skills add
Jeffrey (Dongkyu) Kim