{"id":51508302,"url":"https://github.com/lcy362/personal-skills-manager","last_synced_at":"2026-07-08T03:02:59.273Z","repository":{"id":369003838,"uuid":"1258990555","full_name":"lcy362/personal-skills-manager","owner":"lcy362","description":"Agent-agnostic skill manager for AI coding workflows. Package workflows as Markdown skills, inject per-project, switch agents freel","archived":false,"fork":false,"pushed_at":"2026-07-03T05:27:09.000Z","size":49,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"master","last_synced_at":"2026-07-03T07:23:20.368Z","etag":null,"topics":["ai-workflow","skill-management","skills"],"latest_commit_sha":null,"homepage":"","language":"Shell","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/lcy362.png","metadata":{"files":{"readme":"README.en.md","changelog":null,"contributing":null,"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-06-04T05:17:38.000Z","updated_at":"2026-07-03T05:27:13.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/lcy362/personal-skills-manager","commit_stats":null,"previous_names":["lcy362/personal-skills-manager"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/lcy362/personal-skills-manager","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lcy362%2Fpersonal-skills-manager","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lcy362%2Fpersonal-skills-manager/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lcy362%2Fpersonal-skills-manager/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lcy362%2Fpersonal-skills-manager/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/lcy362","download_url":"https://codeload.github.com/lcy362/personal-skills-manager/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lcy362%2Fpersonal-skills-manager/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":35249883,"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-08T02:00:06.796Z","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":["ai-workflow","skill-management","skills"],"created_at":"2026-07-08T03:02:57.911Z","updated_at":"2026-07-08T03:02:59.264Z","avatar_url":"https://github.com/lcy362.png","language":"Shell","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Personal Skills Manager (pks)\n\n\u003e [English](README.en.md) · [中文](README.md)\n\nA personal skill management tool for AI coding agents. Manage all instruction sets in one place, distribute them to projects or agents as needed — no vendor lock-in.\n\n---\n\n## Background\n\nI've written two posts on this topic:\n\n- [How to Farm Free Tokens: Building Agent-Independent AI Workflows](https://lichuanyang.top/en/posts/26060/): **Agents are just tools. Documentation is the core.** Every AI coding agent follows the same loop — read docs → assemble prompts → call a model → modify files. What actually matters is the documentation and workflows you maintain.\n- [From Token Farming to Skill Managing: My pks Tool in Practice](https://lichuanyang.top/en/posts/34689/): After switching between agents frequently, skill management became a real pain point — each agent has a different skill directory, and skills have different scopes. This needs proper tooling.\n\npks is the practical implementation: **package your documented workflows as skills, manage them globally, inject them on demand.** Plain Markdown, no proprietary config formats.\n\n---\n\n## What Problem Does This Solve?\n\nThe current agent ecosystem is fragmented — Cursor stores skills in `~/.cursor/skills`, Claude Code in `~/.claude/skills`, Trae in `~/.trae/skills`, OpenCode in `~/.config/opencode/skills`, plus Windsurf, Qoder, Hermes, and more. The community is pushing for standards like `.agents/skills`, which helps but isn't enough.\n\nSkills also naturally have different scopes:\n- Some are only relevant to a few specific projects\n- Some should be global but only active in certain agents\n- When you edit a skill in a project, you need to sync it back to the global library\n\npks solves this with a centralized repository at `~/.local/share/pks/skills/`, then distributes skills to wherever they're needed.\n\n---\n\n## When to Use pks\n\npks is best suited for **non-generic** instruction sets such as:\n\n- **Personal habits**: your coding style preferences, common toolchain setup, commit conventions\n- **Company standards**: team code review guidelines, CI/CD workflows, internal library usage\n- **Project conventions**: Architecture Decision Records (ADRs), database conventions, API design constraints\n\n\u003e **Note**: `weread-skills` (WeChat Reading assistant) is included as a demonstration of pks's installation and workflow. General-purpose tools like WeChat Reading are better configured directly in your agent's global settings — they don't need per-project management via pks.\n\n**When should you use pks?** When an instruction set is only relevant to **specific projects** or **specific teams**, and you don't want your global agent loading it on every conversation.\n\n---\n\n## Installation\n\n### Option 1: install.sh\n\n```bash\ngit clone git@github.com:lcy362/personal-skills-manager.git ~/.local/share/pks\n~/.local/share/pks/install.sh\nsource ~/.zshrc\n```\n\n### Option 2: pks install-self\n\n```bash\ngit clone git@github.com:lcy362/personal-skills-manager.git /any/path/pks-repo\n/any/path/pks-repo/bin/pks install-self\n```\n\nBoth methods do the same thing:\n1. Copy files to `~/.local/share/pks/`\n2. Create a symlink at `~/.local/bin/pks`\n3. Add `~/.local/bin` to `PATH` in `~/.zshrc`\n\nYou can customize paths via environment variables:\n\n```bash\nPKS_HOME=/custom/path PKS_BIN_DIR=/custom/bin pks install-self\n```\n\nAfter installation, restart your terminal or run `source ~/.zshrc` to start using `pks`.\n\n---\n\n## Command Reference\n\n### Global Commands\n\n| Command | Description |\n|---------|-------------|\n| `pks list` | List all global skills |\n| `pks new \u003cname\u003e` | Create a new skill from `_template` |\n| `pks delete \u003cname\u003e` | Permanently delete a global skill |\n| `pks install-self` | Install pks to system |\n| `pks doctor` | Show diagnostic info (paths, version, skill status) |\n| `pks help` | Show help |\n| `pks version` | Show version |\n\n### Project Commands (after `pks init`)\n\n| Command | Description |\n|---------|-------------|\n| `pks init` | Initialize `.skills/` in current project |\n| `pks status` | Show installed skills with versions |\n| `pks available` | List installable global skills with project status |\n| `pks install \u003cname\u003e` | Install a skill into current project |\n| `pks uninstall \u003cname\u003e` | Uninstall a skill from current project |\n| `pks update \u003cname\u003e` | Reinstall skill from global (overwrites project copy) |\n| `pks push \u003cname\u003e` | Push project skill edits back to global skills |\n\n### Agent-Level Commands\n\n| Command | Description |\n|---------|-------------|\n| `pks agents` | List detected global agent skill directories |\n| `pks project-agents` | List detected project-level agent skill directories |\n| `pks list-agents` | List all supported project-level agent skill dirs |\n| `pks install-to \u003cagent\u003e \u003cskill\u003e` | Install a skill to an agent's global directory |\n| `pks uninstall-from \u003cagent\u003e \u003cskill\u003e` | Remove a skill from an agent's global directory |\n| `pks update-to \u003cagent\u003e \u003cskill\u003e` | Update a skill in an agent directory from global |\n\n### Project-Level Linking\n\n| Command | Description |\n|---------|-------------|\n| `pks link [agent]` | Symlink agent's project skill dir → `.skills/` |\n| `pks unlink [agent]` | Remove symlink from agent's project skill dir |\n\nWhen no `agent` is specified, `link`/`unlink` applies to all supported agents.\n\nSupported agents: opencode, .agents, claude, cursor, windsurf, trae, trae-cn, codex, qoder, qoderwork, qoderworkcn, workbuddy, openclaw, hermes, teamwork.\n\n### Delete vs Uninstall\n\n| Action | Command | Scope | Details |\n|--------|---------|-------|---------|\n| Uninstall | `pks uninstall \u003cname\u003e` | Project `.skills/` | Removes directory + updates INDEX.md |\n| Delete | `pks delete \u003cname\u003e` | Global `skills/` | Permanently removes from repository |\n| Manual delete | `rm -rf .skills/\u003cname\u003e` | Project | Leaves broken links in INDEX.md, not recommended |\n\n---\n\n## Workflow\n\n### Using Skills in a Project\n\n```bash\ncd your-project\n\n# 1. Initialize (once per project)\npks init\n\n# 2. See what's available\npks available\n\n# 3. Install a skill\npks install my-custom-skill\n\n# 4. Check installation status\npks status\n\n# 5. Uninstall when done\npks uninstall my-custom-skill\n```\n\n### Installing Skills to a Specific Agent\n\nSome skills have a narrow scope — for example, a \"news collector\" skill you only want in one agent:\n\n```bash\n# See which agents are on this machine\npks agents\n\n# Install a skill to a specific agent\npks install-to cursor news-collector\n\n# Update it later\npks update-to cursor news-collector\n\n# Remove it\npks uninstall-from cursor news-collector\n```\n\n### Editing in Project and Pushing Back\n\nSkills evolve as you use them. When you need to tweak a skill:\n\n```bash\n# Edit the skill in your project\nvim .skills/my-skill/SKILL.md\n\n# Push your changes back to the global library\npks push my-skill\n```\n\n### Sharing Skills Across Multiple Agents\n\nFor agents that support project-level skill directories, use `link` to share a single `.skills/` directory:\n\n```bash\ncd your-project\n\n# See which agent skill dirs exist in this project\npks project-agents\n\n# View all supported agent dirs\npks list-agents\n\n# Link a single agent's dir to .skills\npks link opencode\n\n# Link all supported agents at once\npks link\n```\n\nAfter linking, when these agents read their project skill directory, they are actually reading from `.skills/`.\n\n### Creating and Deleting Skills\n\n```bash\n# Create a new skill from template\npks new my-custom-skill\n\n# Edit the skill's instructions\nvim skills/my-custom-skill/SKILL.md\n\n# Permanently delete a global skill\npks delete my-custom-skill\n```\n\nCreated structure:\n\n```\nskills/my-custom-skill/\n├── SKILL.md       # Edit this file with your instructions\n└── files/         # Additional files bundled with the skill\n```\n\nFill in `description` and `version`:\n\n```yaml\n---\nname: my-custom-skill\ndescription: Instruction set for triggering specific workflows\nversion: 1.0.0\n---\n```\n\n---\n\n## Skill Format\n\nEach skill is a directory containing `SKILL.md` and optional additional files. `SKILL.md` uses YAML front matter + Markdown body:\n\n```yaml\n---\nname: skill-name         # Globally unique identifier\ndescription: One-liner   # Shown in pks list/available\nversion: 1.0.0          # Semantic versioning\n---\n```\n\nThe body can include capability tables, API documentation, workflows, and constraint rules. The agent reads this file to understand how to operate.\n\n---\n\n## Agent Auto-Discovery\n\nAfter installing a skill, the project looks like this:\n\n```\nyour-project/\n├── .skills/\n│   ├── INDEX.md         # → Agent reads this first: lists all installed skills\n│   └── my-custom-skill/\n│       └── SKILL.md     # → Specific skill instructions\n└── ...（project files）\n```\n\nNo dependency on `AGENTS.md`, `CLAUDE.md`, or any agent-specific config file. Any AI coding agent exploring the project will naturally discover the `.skills/` directory and read the Markdown files. The INDEX.md prompt guides the agent to load skills on demand.\n\n---\n\n## Repository Structure\n\n```\npersonal-skills-manager/\n├── bin/pks              # CLI tool (pure bash, zero dependencies)\n├── install.sh           # One-click installer\n├── pks.json             # Manifest\n├── skills/\n│   ├── _template/       # Template for pks new\n│   ├── weread-skills/   # WeChat Reading assistant skill (example)\n│   └── ...              # More skills\n├── LICENSE\n├── README.md\n└── README.en.md\n```\n\n---\n\n## Design Principles\n\n- **Zero dependencies**: Pure bash CLI, no Python/Node.js required\n- **Path-independent**: pks works from any location (symlink resolution + relative pathing)\n- **Agent-agnostic**: Skills are plain Markdown — any agent can read them\n- **Central management, multi-level distribution**: All skills in one repo; distribute to projects, agent global dirs, or agent project dirs as needed\n- **Two-way sync**: `push` writes project edits back to the global library\n- **Semantic versioning**: Each skill has a version field for change tracking\n- **Token efficient**: Skills only load when needed, avoiding unnecessary token consumption on every agent conversation\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flcy362%2Fpersonal-skills-manager","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Flcy362%2Fpersonal-skills-manager","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flcy362%2Fpersonal-skills-manager/lists"}