{"id":51734335,"url":"https://github.com/mukiwu/hyday-skills","last_synced_at":"2026-07-18T05:13:12.859Z","repository":{"id":358578235,"uuid":"1241957695","full_name":"mukiwu/hyday-skills","owner":"mukiwu","description":"Agent skills for Hyday — teach external CLI agents (Claude Code / Codex CLI / OpenCode) how to correctly read and write a Hyday vault on disk.","archived":false,"fork":false,"pushed_at":"2026-05-18T04:21:56.000Z","size":40,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-05-18T04:37:19.843Z","etag":null,"topics":["agent-skills","claude-code","hyday","markdown","mcp","obsidian-alternative"],"latest_commit_sha":null,"homepage":null,"language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/mukiwu.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-05-18T02:11:57.000Z","updated_at":"2026-05-18T04:22:00.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/mukiwu/hyday-skills","commit_stats":null,"previous_names":["mukiwu/hyday-skills"],"tags_count":4,"template":false,"template_full_name":null,"purl":"pkg:github/mukiwu/hyday-skills","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mukiwu%2Fhyday-skills","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mukiwu%2Fhyday-skills/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mukiwu%2Fhyday-skills/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mukiwu%2Fhyday-skills/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/mukiwu","download_url":"https://codeload.github.com/mukiwu/hyday-skills/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mukiwu%2Fhyday-skills/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":35605991,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-07-18T02:00:07.223Z","response_time":61,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["agent-skills","claude-code","hyday","markdown","mcp","obsidian-alternative"],"created_at":"2026-07-18T05:13:12.257Z","updated_at":"2026-07-18T05:13:12.850Z","avatar_url":"https://github.com/mukiwu.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Hyday Skills\n\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n[![GitHub stars](https://img.shields.io/github/stars/mukiwu/hyday-skills?style=social)](https://github.com/mukiwu/hyday-skills/stargazers)\n\n\u003e 中文版本：[README.zh-TW.md](README.zh-TW.md)\n\nAgent skills for [Hyday](https://hyday.tw) — a desktop notes \u0026 journal app.\n\nThese skills follow the [Agent Skills specification](https://agentskills.io/specification) so they can be used by any skills-compatible agent, including Claude Code, Codex CLI, and OpenCode.\n\nOnce installed, your AI agent will know how to read and write notes inside your Hyday vault correctly — frontmatter shape, journal filename conventions, the five Life Log marks, where files go, and what the whiteboard can and cannot do.\n\n## If you only do one thing\n\n**Install `hyday-markdown` first.** Every other skill builds on its conventions (frontmatter shape, `#tag` / `@(entity)` / `[[backlink]]` syntax), and 80% of an agent's value in Hyday is \"write me a note that won't break Hyday's parser.\" `hyday-lifelog`, `hyday-vault-layout`, and `hyday-whiteboard` are worth adding once that one is in place — but a single `hyday-markdown` already gets the agent past the most common failure mode (writing files Hyday can't read back cleanly).\n\n## Quick start for agents\n\n**The first thing any Hyday skill does is locate the vault root**: the folder on disk where the user's notes live. Read it from Hyday's config file before doing anything else:\n\n- macOS: `~/Library/Application Support/Hyday/settings.json` → `journalPath` field\n- Windows: `%APPDATA%\\Hyday\\settings.json` → `journalPath` field\n- Fallback: `~/.hyday-recovery` (same JSON shape)\n- Last resort: ask the user\n\nSee `skills/hyday-vault-layout/SKILL.md` Step 0 for the full resolution chain and sanity checks. Every other skill assumes you've already done this — skipping it means writing to the wrong directory or failing silently.\n\n## Installation\n\n\u003e Pick ONE of the methods below. Installing through more than one (e.g. plugin marketplace + npx skills) puts duplicate SKILL.md files in your Claude Code session and behavior gets confusing — pick the one that fits your agent and stick with it.\n\n### Claude Code plugin marketplace (recommended for Claude Code)\n\n```sh\n/plugin marketplace add mukiwu/hyday-skills\n/plugin install hyday@hyday-skills\n```\n\nUpdate / remove later via `/plugin` commands. This is the cleanest path if Claude Code is your only agent.\n\n### npx skills (cross-agent: Claude Code / Codex CLI / OpenCode)\n\n```sh\n# install\nnpx skills add https://github.com/mukiwu/hyday-skills\n# (or with SSH)\nnpx skills add git@github.com:mukiwu/hyday-skills.git\n\n# list installed\nnpx skills list\n\n# update (all / or a specific one)\nnpx skills update\nnpx skills update hyday-skills\n\n# remove\nnpx skills remove hyday-skills\n```\n\n\u003e After `update`, restart your agent (Cmd+Q Claude Code and reopen) so the new `SKILL.md` files reload.\n\n### Manually\n\n#### Claude Code\n\nClone this repo somewhere and copy the `skills/` directory into your project's `.claude/skills/`. Claude Code auto-loads every `SKILL.md` inside `.claude/skills/`.\n\nFrom your Hyday vault folder (or wherever you launch Claude Code from):\n\n```sh\n# clone once\ngit clone https://github.com/mukiwu/hyday-skills.git ~/hyday-skills\n\n# install into a Claude Code workspace\nmkdir -p .claude/skills\ncp -R ~/hyday-skills/skills/* .claude/skills/\n\n# (optional) install the whiteboard MCP server too\ncp -R ~/hyday-skills/mcp-servers .claude/\ncd .claude/mcp-servers/hyday-whiteboard \u0026\u0026 npm install \u0026\u0026 cd -\n```\n\nThen add the MCP server entry to your `.mcp.json` (see [`mcp-servers/hyday-whiteboard/README.md`](mcp-servers/hyday-whiteboard/README.md)). See the [Claude Skills documentation](https://platform.claude.com/docs/en/agents-and-tools/agent-skills/overview) for the full reference.\n\n#### Codex CLI\n\nCopy the `skills/` directory into your Codex skills path (typically `~/.codex/skills/`):\n\n```sh\ngit clone https://github.com/mukiwu/hyday-skills.git /tmp/hyday-skills\nmkdir -p ~/.codex/skills\ncp -R /tmp/hyday-skills/skills/* ~/.codex/skills/\n```\n\nSee the [Agent Skills spec](https://agentskills.io/specification) for the standard skill format.\n\n#### OpenCode\n\nClone the full repo into `~/.opencode/skills/`:\n\n```sh\ngit clone https://github.com/mukiwu/hyday-skills.git ~/.opencode/skills/hyday-skills\n```\n\nOpenCode auto-discovers `SKILL.md` files. Restart OpenCode after cloning.\n\n## Skills\n\n| Skill | Description |\n|-------|-------------|\n| [hyday-markdown](skills/hyday-markdown) | Write Hyday-flavored Markdown — frontmatter, note types, inline `#tag` / `@(entity)` / `[[backlink]]` syntax, callouts, math, and Mermaid diagrams. |\n| [hyday-lifelog](skills/hyday-lifelog) | Write journal entries with the five Life Log marks: `\u003e()` task start, `\u003c()` task end, `-()` current, `%()` thought, `!()` important. |\n| [hyday-vault-layout](skills/hyday-vault-layout) | Understand the folder convention — where journal entries, regular notes, templates, and assets live, plus what files an agent should leave alone. |\n| [hyday-whiteboard](skills/hyday-whiteboard) | Create, edit, and lay out boards through the bundled `hyday-whiteboard` MCP server — add cards, sticky notes, groups, and connections programmatically. |\n\n## Bundled MCP server\n\nThe `hyday-whiteboard` skill depends on the **`hyday-whiteboard` MCP server**, which is shipped in this repo at [`mcp-servers/hyday-whiteboard/`](mcp-servers/hyday-whiteboard). Set it up once:\n\n1. `cd mcp-servers/hyday-whiteboard \u0026\u0026 npm install`\n2. Add an entry to your agent's `.mcp.json` pointing `node` at `mcp-servers/hyday-whiteboard/whiteboard-server.cjs` (full example in [`mcp-servers/hyday-whiteboard/README.md`](mcp-servers/hyday-whiteboard/README.md)).\n3. The server auto-detects your Hyday vault from `settings.json`; override with `--data-root` if you have multiple vaults.\n\nThe other three skills (`hyday-markdown`, `hyday-lifelog`, `hyday-vault-layout`) operate on plain `.md` files and don't need an MCP server — they work with the agent's built-in file tools.\n\n## What this is for\n\nThese skills are for **end users of Hyday** who want to use an AI coding agent (Claude Code / Codex / OpenCode) to read, write, and organize notes in their vault. After installing:\n\n- \"幫我把今天的會議筆記寫成一個 Hyday 筆記\" → agent produces a `.md` file with correct frontmatter.\n- \"把這篇文章存成 link note，加上 #reading 標籤\" → agent creates a `link`-type note with the right `sourceUrl`, `sourceTitle`, etc.\n- \"幫我把今天的日誌寫起來，我上午處理 inbox、下午做了 migration\" → agent writes `journal/2026/2026-05-17.md` with appropriate Life Log marks.\n- \"幫我做一張白板來回顧 Q3 讀的書\" → agent uses the MCP server to create the notes, place them as cards, group them, and draw connections — all in your whiteboard, no manual placement needed.\n\nThese skills do **not** cover Hyday plugin/theme development or internal architecture. They're focused on the end-user workflow of capturing and organizing notes.\n\n## Contributing\n\nBug reports, skill clarifications, new skills, translations, and MCP server fixes all welcome. See [CONTRIBUTING.md](CONTRIBUTING.md) for what helps and how to keep skills aligned with real Hyday behavior.\n\n## License\n\nMIT\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmukiwu%2Fhyday-skills","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmukiwu%2Fhyday-skills","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmukiwu%2Fhyday-skills/lists"}