{"id":45767196,"url":"https://github.com/leonardotrapani/better-skills","last_synced_at":"2026-03-09T11:06:51.311Z","repository":{"id":339770297,"uuid":"1163296515","full_name":"LeonardoTrapani/better-skills","owner":"LeonardoTrapani","description":"Your agents second brain through skill graphs","archived":false,"fork":false,"pushed_at":"2026-02-26T17:49:57.000Z","size":12610,"stargazers_count":3,"open_issues_count":16,"forks_count":1,"subscribers_count":0,"default_branch":"master","last_synced_at":"2026-02-26T19:43:21.375Z","etag":null,"topics":["cli","context","skill-graph","skills"],"latest_commit_sha":null,"homepage":"https://better-skills.dev","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/LeonardoTrapani.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"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":"AGENTS.md","dco":null,"cla":null}},"created_at":"2026-02-21T12:08:33.000Z","updated_at":"2026-02-26T17:50:01.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/LeonardoTrapani/better-skills","commit_stats":null,"previous_names":["leonardotrapani/omniscient","leonardotrapani/omniskill","leonardotrapani/better-skills"],"tags_count":14,"template":false,"template_full_name":null,"purl":"pkg:github/LeonardoTrapani/better-skills","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/LeonardoTrapani%2Fbetter-skills","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/LeonardoTrapani%2Fbetter-skills/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/LeonardoTrapani%2Fbetter-skills/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/LeonardoTrapani%2Fbetter-skills/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/LeonardoTrapani","download_url":"https://codeload.github.com/LeonardoTrapani/better-skills/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/LeonardoTrapani%2Fbetter-skills/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":29883111,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-02-26T23:51:21.483Z","status":"online","status_checked_at":"2026-02-27T02:00:06.759Z","response_time":57,"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":["cli","context","skill-graph","skills"],"created_at":"2026-02-26T02:25:39.663Z","updated_at":"2026-03-09T11:06:51.300Z","avatar_url":"https://github.com/LeonardoTrapani.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# better-skills\n\n\u003cp align=\"center\"\u003e\n  \u003cpicture\u003e\n    \u003csource media=\"(prefers-color-scheme: dark)\" srcset=\"apps/web/public/brand/logo-dark.svg\"\u003e\n    \u003cimg alt=\"better-skills logo\" src=\"apps/web/public/brand/logo-light.svg\" width=\"96\"\u003e\n  \u003c/picture\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003cstrong\u003eyour agent's second brain\u003c/strong\u003e\u003cbr /\u003e\n  build, share, and manage a graph of reusable skills for your ai agents.\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://better-skills.dev\"\u003ewebsite\u003c/a\u003e •\n  \u003ca href=\"https://github.com/LeonardoTrapani/better-skills/releases\"\u003ereleases\u003c/a\u003e •\n  \u003ca href=\"#quickstart-cli\"\u003equickstart\u003c/a\u003e •\n  \u003ca href=\"#local-development\"\u003elocal development\u003c/a\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003cimg alt=\"status prototype\" src=\"https://img.shields.io/badge/status-prototype-fe9a00\"\u003e\n  \u003cimg alt=\"bun version\" src=\"https://img.shields.io/badge/bun-1.3.5-black\"\u003e\n  \u003cimg alt=\"stack\" src=\"https://img.shields.io/badge/stack-next.js%2016%20%2B%20hono%20%2B%20trpc-0ea5e9\"\u003e\n  \u003cimg alt=\"license mit\" src=\"https://img.shields.io/badge/license-MIT-22c55e\"\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"apps/web/public/readme/landing-hero.png\" alt=\"better-skills hero\" width=\"100%\"\u003e\n\u003c/p\u003e\n\n\u003e better-skills is in active development, focused on understanding and nailing product and market needs.\n\u003e for now we prioritize fast iteration and real-world feedback, intentionally leaving code quality temporarly behind\n\n## Table Of Contents\n\n- [What Is better-skills?](#what-is-better-skills)\n- [Core Concepts](#core-concepts)\n- [What You Can Do Today](#what-you-can-do-today)\n- [Architecture At A Glance](#architecture-at-a-glance)\n- [Quickstart (CLI)](#quickstart-cli)\n- [CLI Commands](#cli-commands)\n- [CLI Versions And Releases](#cli-versions-and-releases)\n- [Skill Package Format](#skill-package-format)\n- [Agent Compatibility](#agent-compatibility)\n- [Local Development](#local-development)\n- [Workspace Structure](#workspace-structure)\n- [Useful Docs](#useful-docs)\n- [Contributing](#contributing)\n- [Security](#security)\n- [License](#license)\n\n## What Is better-skills?\n\nbetter-skills is an open, graph-native skills system for coding agents.\n\nit gives you a shared \"skills layer\" that works across terminal agents and a web dashboard:\n\n- author and update skills from the cli\n- sync those skills locally for your agents\n- visualize relationships between skills/resources in a graph ui\n- manage ownership and permissions with personal, enterprise, and system-default vaults\n- share skill bundles and import them into your workspace\n\n## Core Concepts\n\n| Term     | Meaning                                                                             |\n| -------- | ----------------------------------------------------------------------------------- |\n| Skill    | A reusable capability packaged as `SKILL.md` plus resource files                    |\n| Resource | A file attached to a skill (for example `references/*.md`, `scripts/*`, `assets/*`) |\n| Vault    | Ownership boundary for skills (`personal`, `enterprise`, `system_default`)          |\n| Link     | Directed graph edge between skills/resources (`mention`, `depends_on`, etc.)        |\n\n## What You Can Do Today\n\n- **cli-first workflows**: create, validate, update, search, clone, and sync skills from your terminal\n- **web console**: browse your vault, inspect skills, edit markdown resources, and view graph connections\n- **multi-vault model**: personal defaults, enterprise collaboration, and shared system defaults\n- **share + import**: publish skill bundles and install/import them in other environments\n- **mention-aware graph sync**: `[[skill:\u003cuuid\u003e]]`, `[[resource:\u003cuuid\u003e]]`, and `[[resource:new:\u003cpath\u003e]]` are parsed and linked automatically\n- **agent installs**: sync the same skill set to multiple coding agents with one command\n\n## Architecture At A Glance\n\n```text\ncli (apps/cli)         web (apps/web)\n      \\                  /\n       \\                /\n        ---- hono server (apps/server) ----\n                  |  better-auth\n                  |  trpc\n                  v\n         postgres / neon (drizzle)\n               packages/db\n\nshared domain logic: packages/api\nshared mention tooling: packages/markdown\n```\n\n## Quickstart CLI\n\ninstall the latest cli on macos or linux:\n\n```bash\ncurl -fsSL https://better-skills.dev/install | bash\n```\n\nverify install:\n\n```bash\nbetter-skills --version\nbetter-skills health\n```\n\nlogin and sync:\n\n```bash\nbetter-skills login\nbetter-skills sync\nbetter-skills list --limit 10\n```\n\npin to a specific release if needed:\n\n```bash\ncurl -fsSL https://better-skills.dev/install | bash -s -- --version v0.1.0\n```\n\nnotes:\n\n- installer default server is `https://server.better-skills.dev`\n- override at install time with `--server-url`, or at runtime with `SERVER_URL`\n- installer source is `apps/web/public/install`\n- windows users should download the matching `.exe` from github releases\n\n## CLI Commands\n\nrun `better-skills --help` for full usage. most-used commands:\n\n```bash\n# auth and status\nbetter-skills health\nbetter-skills login\nbetter-skills whoami\nbetter-skills logout\n\n# vaults\nbetter-skills vaults\nbetter-skills enable \u003cvault-slug|vault-id\u003e\nbetter-skills disable \u003cvault-slug|vault-id\u003e\n\n# discover and inspect\nbetter-skills list [search] [--all] [--limit N]\nbetter-skills search \"\u003cquery\u003e\" [--limit N]\nbetter-skills get \u003cvault-slug\u003e/\u003cskill-slug\u003e|\u003cslug\u003e|\u003cuuid\u003e\nbetter-skills clone \u003cvault-slug\u003e/\u003cskill-slug\u003e|\u003cslug\u003e|\u003cuuid\u003e [--to \u003cdir\u003e] [--force]\n\n# authoring\nbetter-skills validate \u003cdir\u003e\nbetter-skills rewrite-links \u003cdir\u003e [--dry-run]\nbetter-skills create --from \u003cdir\u003e [--slug \u003cslug\u003e] [--vault \u003cvault-slug|vault-id\u003e]\nbetter-skills update \u003cvault-slug\u003e/\u003cskill-slug\u003e|\u003cslug\u003e|\u003cuuid\u003e --from \u003cdir\u003e\nbetter-skills references \u003cvault-slug\u003e/\u003cskill-slug\u003e|\u003cslug\u003e|\u003cuuid\u003e\nbetter-skills delete \u003cvault-slug\u003e/\u003cskill-slug\u003e|\u003cslug\u003e|\u003cuuid\u003e [--yes]\n\n# install/share and setup\nbetter-skills install-share \u003cshare-url|share-uuid\u003e\nbetter-skills get-unmanaged-skills\nbetter-skills config\nbetter-skills backup [--source \u003cdir\u003e] [--out \u003ctmp-dir\u003e] [--agent \u003cagent\u003e]...\nbetter-skills sync\n```\n\nnon-interactive mode is auto-enabled for no-tty/ci contexts (`CI=true`, `AGENT=1`, `OPENCODE=1`).\n\n## CLI Versions And Releases\n\n- releases are published from git tags matching `v*`\n- installer defaults to `latest` github release\n- `better-skills --version` reads `BETTER_SKILLS_VERSION` (falls back to `dev`)\n- binaries are currently published for:\n  - `darwin-x64`\n  - `darwin-arm64`\n  - `linux-x64`\n  - `linux-arm64`\n  - `windows-x64`\n- release workflow: `.github/workflows/release-cli.yml`\n\n## Skill Package Format\n\nminimum shape:\n\n```text\nmy-skill/\n  SKILL.md\n  references/\n    notes.md\n```\n\n`SKILL.md` needs yaml frontmatter with at least:\n\n```yaml\n---\nname: my-skill\ndescription: short summary of what this skill does\n---\n```\n\nmention tokens used by better-skills:\n\n- `[[skill:\u003cuuid\u003e]]`\n- `[[resource:\u003cuuid\u003e]]`\n- `[[resource:new:path/to/file.md]]` (draft-local before persistence)\n\nrecommended authoring flow:\n\n```bash\nbetter-skills validate ./my-skill\nbetter-skills rewrite-links ./my-skill --dry-run\nbetter-skills create --from ./my-skill\n```\n\n## Agent Compatibility\n\nthe cli can sync skills to these agent skill directories:\n\n- OpenCode: `~/.config/opencode/skills`\n- Claude Code: `~/.claude/skills`\n- Codex: `~/.codex/skills`\n- Cursor: `~/.cursor/skills`\n- GitHub Copilot: `~/.copilot/skills`\n- Gemini CLI: `~/.gemini/skills`\n- Amp: `~/.config/agents/skills`\n- Goose: `~/.config/goose/skills`\n- Continue.dev: `~/.continue/skills`\n\ncanonical skill storage used by better-skills:\n\n- `~/.better-skills/skills`\n\n## Local Development\n\n### Prerequisites\n\n- bun `1.3.5`\n- postgres (or neon postgres)\n- oauth app credentials for github/google login flows\n\n### 1) Install Dependencies\n\n```bash\nbun install\n```\n\n### 2) Configure Environment\n\n`apps/server/.env`:\n\n```env\nDATABASE_URL=postgres://postgres:postgres@localhost:5432/better_skills\nBETTER_AUTH_SECRET=replace-with-at-least-32-characters\nBETTER_AUTH_URL=http://localhost:3000\nCORS_ORIGIN=http://localhost:3001\nGOOGLE_CLIENT_ID=your-google-client-id\nGOOGLE_CLIENT_SECRET=your-google-client-secret\nGITHUB_CLIENT_ID=your-github-client-id\nGITHUB_CLIENT_SECRET=your-github-client-secret\nNODE_ENV=development\n```\n\n`apps/web/.env`:\n\n```env\nNEXT_PUBLIC_SERVER_URL=http://localhost:3000\n```\n\noptional for cli (when targeting local server):\n\n```bash\nexport SERVER_URL=http://localhost:3000\n```\n\n### 3) Push Database Schema\n\n```bash\nbun run db:push\n```\n\n### 4) Start The Stack\n\n```bash\nbun run dev\n```\n\nthis starts:\n\n- web: `http://localhost:3001`\n- api/auth server: `http://localhost:3000`\n\nrun cli directly from repo root:\n\n```bash\nbun cli --help\n```\n\n### 5) Validate Changes\n\n```bash\nbun run check-types\nbun run check\n```\n\nthere is no single shared monorepo test runner yet; add/run package-local tests when you introduce new behavior.\n\n## Workspace Structure\n\n```text\napps/\n  cli/       # terminal cli built with @clack/prompts + trpc client\n  server/    # hono runtime hosting better-auth + trpc routes\n  web/       # next.js dashboard + graph + share/import ui\n\npackages/\n  api/       # shared trpc router + domain behavior\n  auth/      # better-auth setup and vault bootstrap hooks\n  config/    # shared tsconfig presets\n  db/        # drizzle schema + migrations + db client\n  env/       # typed env contracts (server/web/cli)\n  markdown/  # mention parsing/rendering and markdown helpers\n\nresources/\n  default-skills/  # seeded default skill templates\n\ndocs/\n  mention-link-sync-flow.md\n  skills-schema.md\n```\n\n## Useful Docs\n\n- data model and vault semantics: `docs/skills-schema.md`\n- mention parsing and graph link sync flow: `docs/mention-link-sync-flow.md`\n- default seeded skill: `resources/default-skills/better-skills/SKILL.md`\n\n## Contributing\n\nissues and prs are welcome.\n\nplease keep contributions aligned with these repo conventions:\n\n1. use bun workspaces (`bun`, not npm/pnpm/yarn)\n2. keep transport concerns in `apps/server` and domain logic in `packages/api`\n3. keep db schema + migration changes together\n4. run `bun run check-types` and `bun run check` before opening a pr\n5. never commit secrets or `.env` files\n\nfor larger feature ideas, open an issue first so we can align on product direction (prototype moves fast).\n\n## Security\n\n- do not commit credentials or live tokens\n- use local `.env` files for secrets\n- if you discover a security issue, please report it privately to the maintainers before public disclosure\n\n## License\n\nlicensed under the [MIT License](LICENSE).\n\n## Acknowledgements\n\n- bootstrapped from [Better-T-Stack](https://github.com/AmanVarshney01/create-better-t-stack)\n- built with Next.js, Hono, tRPC, Better Auth, Drizzle, Turborepo, and Bun\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fleonardotrapani%2Fbetter-skills","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fleonardotrapani%2Fbetter-skills","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fleonardotrapani%2Fbetter-skills/lists"}