@xiaotianxt/skills 0.1.0

package/EXCLUDED.md

@@ -0,0 +1,42 @@
+# Excluded Content
+
+The following content was intentionally not published.
+
+## System and Plugin Skills
+
+- `~/.codex/skills/.system`
+- `~/.codex/plugins/cache`
+
+These are managed by Codex or plugins and should be installed from their upstream
+sources instead of being re-published here.
+
+## Third-Party Installed Skills
+
+The following installed skills were not vendored because they are third-party or
+upstream-owned:
+
+- `~/.agents/skills/agent-browser`
+- `~/.agents/skills/find-skills`
+- `~/.agents/skills/frontend-design`
+- `~/.agents/skills/teach-impeccable`
+- `~/.agents/skills/vercel-cli`
+- `~/Develop.localized/agent-browser/skills/*`
+
+## Local Project Data
+
+Only skill instructions were extracted from local project repos. The following
+classes of files were excluded:
+
+- `.git/`
+- `target/`
+- `decrypted/`
+- `exported/`
+- `all_keys.json`
+- local auth files
+- local session files
+- local databases
+- build artifacts
+- editor and OS metadata
+
+In particular, the full `~/dev/tg` tree was not copied because it contained
+local decrypted databases and key material.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 xiaotianxt
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,165 @@
+# skills
+
+Personal Codex and agent skills, collected into one public, source-controlled repo.
+
+## Layout
+
+Each skill lives at:
+
+```text
+skills/<skill-name>/SKILL.md
+```
+
+Optional bundled resources live next to `SKILL.md`, for example `scripts/`,
+`references/`, `assets/`, or `agents/openai.yaml`.
+
+## Install One Skill
+
+Install exactly the skill you need. The installer intentionally has no
+"install every skill" mode.
+
+Before the npm package is published, install from GitHub:
+
+```bash
+npx -y github:xiaotianxt/skills bro-browser
+```
+
+After publishing to npm:
+
+```bash
+npx -y @xiaotianxt/skills bro-browser
+```
+
+Per-project examples:
+
+```bash
+npx -y @xiaotianxt/skills bro-browser
+npx -y @xiaotianxt/skills tg
+npx -y @xiaotianxt/skills cx
+npx -y @xiaotianxt/skills mon
+```
+
+For `tg`, prefer the project binary when it is installed:
+
+```bash
+tg skill install
+```
+
+That command renders the local machine-specific skill from tg's dictionary.
+The NPX command installs the public Telegram-worded central skill template.
+
+The default target is Codex: `~/.codex/skills/<skill-name>`. Other targets:
+
+```bash
+npx -y @xiaotianxt/skills bro-browser --target agents
+npx -y @xiaotianxt/skills bro-browser --target claude
+npx -y @xiaotianxt/skills bro-browser --dir ~/.codex/skills
+```
+
+List available packaged skills:
+
+```bash
+npx -y @xiaotianxt/skills list
+```
+
+Restart the target agent after installing or updating a skill.
+
+The older Codex skill installer still works when you want to install directly
+from this GitHub repo:
+
+```bash
+python3 ~/.codex/skills/.system/skill-installer/scripts/install-skill-from-github.py \
+  --repo xiaotianxt/skills \
+  --path skills/<skill-name>
+```
+
+## Development Model
+
+For this machine, `~/dev/skills` is the canonical source tree for user-owned
+skills. Treat `~/.codex/skills` and `~/.agents/skills` as runtime install views,
+not as the place to author durable skill changes.
+
+When creating or updating a user-owned skill:
+
+1. Edit `~/dev/skills/skills/<skill-name>/...`.
+2. Commit the change in this repo.
+3. Link the installed runtime copy back to this checkout.
+4. Restart Codex or the target agent when a refreshed skill must be loaded.
+
+This keeps skill history reviewable, avoids editing generated or installed
+copies directly, and makes local improvements publishable.
+
+## Runtime Links
+
+Create or refresh the runtime symlinks with:
+
+```bash
+git clone https://github.com/xiaotianxt/skills.git ~/dev/skills
+~/dev/skills/scripts/link-local-skills.sh
+```
+
+This maps selected `~/.codex/skills/*` and `~/.agents/skills/*` entries to
+`~/dev/skills/skills/*`. Existing installed directories are backed up before
+being replaced by symlinks.
+
+To update installed skills later:
+
+```bash
+git -C ~/dev/skills pull --ff-only
+~/dev/skills/scripts/link-local-skills.sh
+```
+
+To mirror canonical skill docs into local open source project repos:
+
+```bash
+~/dev/skills/scripts/sync-project-skills.sh
+```
+
+That script copies:
+
+- `~/dev/skills/skills/cx/SKILL.md` -> `~/dev/cx/SKILL.md`
+- `~/dev/skills/skills/tg/SKILL.md` -> `~/dev/tg/SKILL.md`
+- `~/dev/skills/skills/mimestreamctl` -> `~/dev/mimestreamctl/skills/mimestreamctl`
+
+Project repos keep real mirrored files rather than symlinks so GitHub can render
+the skill docs normally. Check drift without writing:
+
+```bash
+~/dev/skills/scripts/sync-project-skills.sh --check
+```
+
+## Included Skills
+
+This repo includes user-owned local skills from `~/.codex/skills`, selected
+generated Google Workspace `gws-*` skills, and lightweight skill wrappers from
+local `~/dev` tools.
+
+Notable curation choices:
+
+- System skills from `~/.codex/skills/.system` are not re-published here.
+- Third-party installed skills are not vendored here unless they are user-owned.
+- Large local project directories are not copied. For `~/dev/mon`, `~/dev/cx`,
+  and `~/dev/tg`, only the skill instructions are included.
+- The public `tg` skill keeps the Telegram-facing wording used by the open
+  source tool documentation.
+
+See [SOURCES.md](SOURCES.md) for source mapping and [EXCLUDED.md](EXCLUDED.md)
+for what was intentionally left out.
+
+## Skill Evolution
+
+Skills are maintained as operational memory, not as project notebooks. After
+real use, promote only durable lessons that improve future triggering,
+workflow, safety, validation, or semantic clarity.
+
+See [docs/skill-evolution.md](docs/skill-evolution.md) for the short-term,
+long-term, and far-term maintenance model.
+
+See [docs/skill-portfolio-governance.md](docs/skill-portfolio-governance.md)
+for skill roles, boundary rules, and the current portfolio map.
+
+## Safety
+
+Before publication this repo was assembled from a clean copy and scanned for
+credentials, local databases, decrypted chat data, generated build output, and
+Git internals. See [SECURITY.md](SECURITY.md) for the policy used here.

package/SECURITY.md

@@ -0,0 +1,23 @@
+# Security
+
+This repository is intended to contain public skill instructions only.
+
+Do not commit:
+
+- API keys, OAuth tokens, cookies, session files, or password files
+- `auth.json`, `env.conf`, `.env`, `session.json`, or equivalent credential state
+- local email, chat, calendar, document, or finance data
+- decrypted databases, exported chats, media caches, or generated reports
+- build output such as `target/`, `dist/`, or local binaries
+- `.git/`, `.DS_Store`, or tool cache directories
+
+Before publishing updates, run a secret scan similar to:
+
+```bash
+rg -n --hidden -i \
+  "(api[_-]?key|token|secret|password|credential|authorization|bearer|github_pat|ghp_|gho_|sk-[A-Za-z0-9]|AKIA|AIza|BEGIN [A-Z ]*PRIVATE KEY|auth\\.json|session\\.json|all_keys|decrypted/)" \
+  .
+```
+
+Treat matches as blockers unless they are clearly documentation examples or code
+that handles secret values without embedding real values.

package/SOURCES.md

@@ -0,0 +1,45 @@
+# Sources
+
+## Included
+
+| Skill | Source |
+| --- | --- |
+| `1password` | Created in this repo as scoped 1Password import/fallback guidance |
+| `apple-calendar-event` | `~/.codex/skills/apple-calendar-event` |
+| `bro-browser` | Created in this repo for the local bro browser MCP workflow |
+| `calendar` | Created in this repo as personal calendar governance guidance |
+| `canvas` | Created in this repo as the local source of truth |
+| `course-exam-review-planner` | `~/.codex/skills/course-exam-review-planner` |
+| `cx` | `~/dev/cx/SKILL.md` |
+| `gh-fix-ci` | Created in this repo as GitHub Actions PR check workflow guidance |
+| `gh-review-workflow` | `~/.codex/skills/gh-review-workflow` |
+| `github` | Created in this repo as GitHub triage and routing guidance |
+| `gws-*` | `~/.agents/skills/gws-*` |
+| `gws-shared` | Added to make generated `gws-*` skills self-contained |
+| `helium-browser-mcp` | Created in this repo from the local Helium/OpenBrowserMCP workflow |
+| `macos-messages` | Created in this repo as local Messages history guidance |
+| `memory` | Created in this repo as local agent history search guidance |
+| `mimestreamctl` | `~/dev/mimestreamctl/skills/mimestreamctl` |
+| `mon` | `~/dev/mon/SKILL.md` |
+| `panopto-mp4-bulk-download` | `~/.codex/skills/panopto-mp4-bulk-download` |
+| `rust-systems-style` | Created in this repo as the local source of truth |
+| `ship-ai-native-cli` | `~/.codex/skills/ship-ai-native-cli` |
+| `telegram-mtproto-session` | Created in this repo as local Telegram MTProto session guidance |
+| `tg` | `~/dev/tg/SKILL.md` |
+| `things3-manager` | `~/.codex/skills/things3-manager` |
+| `yeet` | Created in this repo as local GitHub publish workflow guidance |
+
+## Normalization
+
+- `mon` and `cx` were given standard YAML frontmatter.
+- The public `tg` skill preserves Telegram-facing wording.
+- `agent-browser-hints` was retired in favor of the narrower
+  `helium-browser-mcp` skill.
+- Backup files, `.DS_Store`, `.git`, build output, local databases, local keys,
+  and generated cache data were excluded.
+
+## Local Linking
+
+Use `scripts/link-local-skills.sh` to map installed local skills to this repo.
+Use `scripts/sync-project-skills.sh` to mirror canonical skill docs into local
+project repos while keeping those repos readable on GitHub.

package/bin/skills.mjs

@@ -0,0 +1,241 @@
+#!/usr/bin/env node
+import fs from 'node:fs'
+import os from 'node:os'
+import path from 'node:path'
+import process from 'node:process'
+import { fileURLToPath } from 'node:url'
+
+const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..')
+const SKILLS_DIR = path.join(ROOT, 'skills')
+const TARGETS = {
+  codex: path.join(os.homedir(), '.codex', 'skills'),
+  agents: path.join(os.homedir(), '.agents', 'skills'),
+  claude: path.join(os.homedir(), '.claude', 'skills'),
+}
+
+function main(argv) {
+  const [command, ...rest] = argv
+  switch (command) {
+    case undefined:
+    case '-h':
+    case '--help':
+    case 'help':
+      printHelp()
+      return
+    case 'list':
+      listSkills()
+      return
+    case 'install':
+    case 'add':
+      install(rest)
+      return
+    default:
+      install(argv)
+  }
+}
+
+function printHelp() {
+  console.log(`xiaotianxt-skills
+
+Usage:
+  npx @xiaotianxt/skills list
+  npx @xiaotianxt/skills bro-browser
+  npx @xiaotianxt/skills tg --target agents
+  npx @xiaotianxt/skills install cx --target codex
+
+Options:
+  --target <codex|agents|claude>  Install target. Default: codex.
+  --dir <path>                    Override install directory.
+  --dry-run                       Print actions without writing.
+  --force                         Replace existing skill without backup.
+
+Installs exactly one named skill. There is intentionally no "install all" mode.
+`)
+}
+
+function listSkills() {
+  for (const skill of availableSkills()) {
+    console.log(skill)
+  }
+}
+
+function install(args) {
+  const options = parseInstallArgs(args)
+  if (options.skills.length === 0) {
+    fail('install requires exactly one skill name')
+  }
+  if (options.skills.length > 1) {
+    fail('install accepts one skill name; run separate commands for separate skills')
+  }
+
+  const targets = resolveTargets(options)
+  for (const skill of options.skills) {
+    assertSkillExists(skill)
+  }
+
+  for (const target of targets) {
+    for (const skill of options.skills) {
+      installSkill(skill, target, options)
+    }
+  }
+}
+
+function parseInstallArgs(args) {
+  const options = {
+    dryRun: false,
+    force: false,
+    target: 'codex',
+    dir: undefined,
+    skills: [],
+  }
+
+  for (let i = 0; i < args.length; i += 1) {
+    const arg = args[i]
+    if (arg === '--dry-run') {
+      options.dryRun = true
+    } else if (arg === '--force') {
+      options.force = true
+    } else if (arg === '--target') {
+      options.target = requireValue(args, ++i, '--target')
+    } else if (arg.startsWith('--target=')) {
+      options.target = arg.slice('--target='.length)
+    } else if (arg === '--dir') {
+      options.dir = requireValue(args, ++i, '--dir')
+    } else if (arg.startsWith('--dir=')) {
+      options.dir = arg.slice('--dir='.length)
+    } else if (arg.startsWith('-')) {
+      fail(`unknown option: ${arg}`)
+    } else {
+      options.skills.push(arg)
+    }
+  }
+
+  return options
+}
+
+function requireValue(args, index, option) {
+  const value = args[index]
+  if (!value || value.startsWith('-')) {
+    fail(`${option} requires a value`)
+  }
+  return value
+}
+
+function resolveTargets(options) {
+  if (options.dir) {
+    return [path.resolve(expandHome(options.dir))]
+  }
+  const target = TARGETS[options.target]
+  if (!target) {
+    fail('--target must be codex, agents, or claude')
+  }
+  return [target]
+}
+
+function availableSkills() {
+  return fs
+    .readdirSync(SKILLS_DIR, { withFileTypes: true })
+    .filter((entry) => entry.isDirectory())
+    .map((entry) => entry.name)
+    .filter((name) => fs.existsSync(path.join(SKILLS_DIR, name, 'SKILL.md')))
+    .sort()
+}
+
+function assertSkillExists(skill) {
+  if (!/^[a-z0-9][a-z0-9-]*$/.test(skill)) {
+    fail(`invalid skill name: ${skill}`)
+  }
+  const src = path.join(SKILLS_DIR, skill)
+  if (!fs.existsSync(path.join(src, 'SKILL.md'))) {
+    fail(`unknown skill: ${skill}`)
+  }
+}
+
+function installSkill(skill, targetDir, options) {
+  const src = path.join(SKILLS_DIR, skill)
+  const dest = path.join(targetDir, skill)
+
+  if (skill === 'tg') {
+    console.error(
+      'note: `tg skill install` renders the local machine-specific tg skill; this installer copies the public Telegram-worded template.',
+    )
+  }
+
+  if (fs.existsSync(dest) || isSymlink(dest)) {
+    const current = describeExisting(dest)
+    if (current === src) {
+      console.log(`ok ${dest} -> ${src}`)
+      return
+    }
+
+    if (options.force) {
+      log(options, `remove ${dest}`)
+      if (!options.dryRun) fs.rmSync(dest, { recursive: true, force: true })
+    } else {
+      const backup = backupPath(targetDir, skill)
+      log(options, `backup ${dest} -> ${backup}`)
+      if (!options.dryRun) {
+        fs.mkdirSync(path.dirname(backup), { recursive: true })
+        fs.renameSync(dest, backup)
+      }
+    }
+  }
+
+  log(options, `copy ${dest} <- ${src}`)
+  if (options.dryRun) return
+  fs.mkdirSync(targetDir, { recursive: true })
+  fs.cpSync(src, dest, {
+    recursive: true,
+    filter: (source) => !shouldSkip(path.basename(source)),
+  })
+}
+
+function describeExisting(dest) {
+  try {
+    const stat = fs.lstatSync(dest)
+    if (stat.isSymbolicLink()) {
+      return path.resolve(path.dirname(dest), fs.readlinkSync(dest))
+    }
+    return 'directory'
+  } catch {
+    return undefined
+  }
+}
+
+function isSymlink(dest) {
+  try {
+    return fs.lstatSync(dest).isSymbolicLink()
+  } catch {
+    return false
+  }
+}
+
+function backupPath(targetDir, skill) {
+  const stamp = new Date()
+    .toISOString()
+    .replaceAll('-', '')
+    .replaceAll(':', '')
+    .replace(/\..+$/, '')
+  return path.join(targetDir, `.skills-backup-${stamp}`, skill)
+}
+
+function shouldSkip(name) {
+  return name === '.DS_Store' || name === '__pycache__' || name.endsWith('.pyc')
+}
+
+function expandHome(value) {
+  if (value === '~') return os.homedir()
+  if (value.startsWith('~/')) return path.join(os.homedir(), value.slice(2))
+  return value
+}
+
+function log(options, message) {
+  console.log(options.dryRun ? `dry-run ${message}` : message)
+}
+
+function fail(message) {
+  console.error(`error: ${message}`)
+  process.exit(1)
+}
+
+main(process.argv.slice(2))

package/package.json

@@ -0,0 +1,38 @@
+{
+  "name": "@xiaotianxt/skills",
+  "version": "0.1.0",
+  "description": "Install xiaotianxt agent skills for Codex, OpenCode-style agents, and Claude.",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/xiaotianxt/skills.git"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "type": "module",
+  "bin": {
+    "skills": "bin/skills.mjs"
+  },
+  "scripts": {
+    "check:public": "bash scripts/check-public-redactions.sh",
+    "prepack": "npm run check:public",
+    "prepublishOnly": "npm run check:public && npm run smoke",
+    "smoke": "npm run check:public && node bin/skills.mjs list && node bin/skills.mjs bro-browser --dir /tmp/xiaotianxt-skills-smoke --dry-run"
+  },
+  "files": [
+    "bin/",
+    "skills/",
+    "!skills/**/__pycache__/",
+    "!skills/**/*.pyc",
+    "!skills/**/.DS_Store",
+    "README.md",
+    "LICENSE",
+    "SECURITY.md",
+    "SOURCES.md",
+    "EXCLUDED.md"
+  ],
+  "engines": {
+    "node": ">=18"
+  }
+}

package/skills/1password/SKILL.md

@@ -0,0 +1,94 @@
+---
+name: 1password
+description: "Use when Codex needs to work with 1Password or the `op` CLI: reading a specific secret reference, injecting API keys or credentials into local commands, using `op run` or `op inject`, checking 1Password CLI auth state, handling `API_CREDENTIAL` items, creating or updating 1Password items, or deciding how to keep secrets out of code, logs, shell history, issues, PRs, and final responses."
+---
+
+# 1Password
+
+Use the local 1Password CLI only for scoped 1Password work. For local machine-only API keys on this Mac, prefer macOS Keychain through `keychain-secret` and use 1Password as an import/fallback source. Keep workflows local and avoid exposing secret values to chat, logs, files, source control, or command history.
+
+## Default Rules
+
+- Use only the specific credential needed for the current task.
+- Prefer `keychain-secret get <service> <account>` for local API-key reads after a secret has been migrated to Keychain.
+- Prefer `keychain-secret import-op <service> <account> <op-ref>` for one-time migration from a known 1Password reference.
+- Prefer a user-provided `op://...` secret reference over searching vaults.
+- Do not enumerate vaults, accounts, or items unless the user asks or the reference is ambiguous.
+- Do not print, summarize, quote, or reveal secret values in chat or final responses.
+- Do not paste plaintext secrets into source files, `.env` files, logs, issues, PRs, commit messages, or shell history.
+- Prefer `op run` only for workflows that cannot use Keychain yet and accept environment variables.
+- Prefer templates with secret references plus `op inject` only when a real config file is required and Keychain is unsuitable; delete resolved files when no longer needed.
+- Avoid `op run --no-masking` and `op item get --reveal` unless the user explicitly asks to display a secret.
+- Treat service account tokens, exported `.env` files, one-time passwords, private keys, cookies, and raw item JSON as sensitive.
+
+## Local Setup
+
+- Verify availability with `op --version`.
+- When a command needs to read secrets through the 1Password desktop app integration, request `sandbox_permissions="require_escalated"` by default. The workspace sandbox can block the local app socket and produce misleading errors such as "couldn't connect to the 1Password desktop app" even when 1Password is installed and working.
+- If `op read`, `op run`, or `op signin` fails with a desktop app connection error inside the sandbox, rerun the exact scoped command outside the sandbox with a concise approval request before asking the user to restart 1Password.
+- If auth is missing, use `op signin` and expect the user to approve in 1Password.
+- If multiple accounts are configured, use `--account` or `OP_ACCOUNT` only after identifying the intended account.
+- Do not require `tmux`; this machine may not have it. Use normal serialized shell commands unless an interactive TTY is genuinely needed.
+
+## Common Workflows
+
+### Inject A Secret Into A Command
+
+For local API keys, prefer Keychain:
+
+```bash
+API_KEY="$(keychain-secret get codex.service credential)" my-command
+```
+
+When the secret exists only in 1Password, ask for the secret reference, then run the target command without exposing the value:
+
+```bash
+API_KEY='op://Private/Service API/credential' op run -- my-command
+```
+
+For project commands, prefer a template env file containing `op://` references:
+
+```bash
+op run --env-file .env.op -- npm run dev
+```
+
+### Read A Specific Secret
+
+Use `op read` only when the secret is not yet migrated to Keychain and must be passed to a local process that cannot consume `op run` references. Do not echo the value back to the user.
+
+```bash
+op read 'op://Private/Service API/credential'
+```
+
+For `API_CREDENTIAL` items in this setup, the preferred field is `credential`:
+
+```bash
+op read 'op://Private/<title-or-id>/credential'
+```
+
+To migrate that item to Keychain:
+
+```bash
+keychain-secret import-op codex.service credential 'op://Private/<title-or-id>/credential'
+```
+
+### Create Or Update 1Password Items
+
+Do not ask the user to paste secret values into chat. If CLI item creation is required, avoid command-line assignment statements for sensitive values because command arguments can be logged or visible to local processes.
+
+Use the 1Password app when practical. If CLI is necessary, use a short-lived local JSON template or stdin flow, set restrictive file permissions, and delete any plaintext temporary file immediately after use.
+
+## When To Load References
+
+- Read `references/op-cli.md` for concrete `op read`, `op run`, `op inject`, auth, and account-selection patterns.
+- Read `references/item-management.md` before creating, editing, copying, or exporting 1Password items.
+
+## Stop Conditions
+
+Stop and ask the user before:
+
+- Listing vaults/items/accounts to discover a credential.
+- Exporting secrets to disk, even temporarily.
+- Creating service accounts, Connect tokens, Kubernetes secrets, or CI secrets.
+- Changing global shell, git, gh, or 1Password plugin configuration.
+- Running any command likely to display secret values.

package/skills/1password/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "1Password"
+  short_description: "Use 1Password CLI without leaking secrets"
+  default_prompt: "Use $1password to inject an API key from a 1Password secret reference into this local command."