{
  "markdown": "# villagesql-skills\n\nAgent skills for working with [VillageSQL](https://villagesql.com). Skills run\nin Claude Code, agy, Codex, Cursor, Amp, Kiro, OpenCode, and OpenClaw.\n\n## Skills\n\n| Skill | What it does |\n|---|---|\n| [`vsql-install-server`](skills/vsql-install-server/) | Gets a working VillageSQL server on your machine — install, start, connect, load an extension, verify. Start here if you do not have a server yet. |\n| [`vsql-extension-builder`](skills/vsql-extension-builder/) | Builds a VillageSQL extension end-to-end through a 7-phase persona-driven workflow. Discovers the current VEF API from live SDK headers — no hardcoded API names. |\n\nMore skills will be added here over time.\n\n## Prerequisites\n\nThe skills drive a live VillageSQL server on your machine. Install one as a\nprebuilt binary or a source build via the server installer:\n\n```bash\ncurl -fsSL https://install.villagesql.com | bash\n```\n\nThe `villagesql/server` Docker image carries the extension SDK, a C++\ntoolchain, and a `vsql-build-extension.sh` helper, so you can build and\ninstall an extension inside a container. What it does not carry is\n`mysql-test-run.pl`, the MTR orchestrator, so `vsql-extension-builder` cannot\ncomplete its test phase there — that phase needs an installer or source build\non the host. See each skill's README for its full requirements.\n\n## Installing\n\n### Quick install\n\n```bash\ncurl -sSL https://villagesql.com/skills | bash\n```\n\nDetects which agents are installed and configures each one. Supports Claude\nCode, agy, Codex, Cursor, Amp, Kiro, OpenCode, and OpenClaw.\nRe-running updates in place.\n\nOverride locations with env vars:\n\n```bash\nVILLAGESQL_SKILLS_SRC=~/code/villagesql-skills \\\nCLAUDE_SKILLS_DIR=~/.claude/skills \\\n  curl -sSL https://villagesql.com/skills | bash\n```\n\n### Manual install (recommended for contributors)\n\n#### Claude Code\n\n```bash\ngit clone https://github.com/villagesql/villagesql-skills.git ~/code/villagesql-skills\nmkdir -p ~/.claude/skills\nln -s ~/code/villagesql-skills/skills/vsql-extension-builder ~/.claude/skills/vsql-extension-builder\n```\n\nVerify the skill is loaded by typing `/` in Claude Code — the skill name\nshould appear in the slash command list.\n\n#### agy\n\n```bash\ngit clone https://github.com/villagesql/villagesql-skills.git ~/code/villagesql-skills\nmkdir -p ~/.gemini/antigravity-cli/plugins\nln -s ~/code/villagesql-skills ~/.gemini/antigravity-cli/plugins/villagesql\n```\n\nagy reads `plugin.json` and discovers skills from the `skills/` subdirectory.\n\n#### OpenCode\n\n```bash\ngit clone https://github.com/villagesql/villagesql-skills.git ~/code/villagesql-skills\nmkdir -p ~/.config/opencode/skills\nln -s ~/code/villagesql-skills/skills/vsql-extension-builder ~/.config/opencode/skills/vsql-extension-builder\n```\n\n#### OpenClaw\n\n```bash\ngit clone https://github.com/villagesql/villagesql-skills.git ~/code/villagesql-skills\nmkdir -p ~/.openclaw/workspace/skills\nln -s ~/code/villagesql-skills/skills/vsql-extension-builder ~/.openclaw/workspace/skills/vsql-extension-builder\n```\n\nTo update later (all agents share the same clone):\n\n```bash\ngit -C ~/code/villagesql-skills pull\n```\n\n## Skill layout\n\nEach skill follows the standard Agent Skills directory layout:\n\n```\nskills/\n└── <skill-name>/\n    ├── SKILL.md           # entry point — frontmatter, workflow, gates\n    └── references/        # detailed material loaded on demand\n        └── *.md\n```\n\n`SKILL.md` is loaded eagerly when the skill triggers and stays thin and\nprocedural. Detail-heavy material (standards, checklists, environment\ncommands) lives in `references/` and is read by the agent only when the\nrelevant phase needs it.\n\n## Contributing\n\nIssues and pull requests welcome. For substantive changes — new skills,\nworkflow restructuring, new references — open an issue first to discuss the\nshape before writing the skill.\n\nA few conventions:\n\n- Keep `SKILL.md` thin. If a section exceeds a screen, ask whether it\n  belongs in `references/` instead.\n- Reference files describe **process and principles**, not specific API\n  names — names should be discovered from live sources during the\n  workflow, not hardcoded in the skill.\n- Match the voice of existing skills: terse, imperative, no marketing\n  language.\n\n### Testing changes locally\n\nThe quick installer clones the repo to `~/.local/share/villagesql-skills/` and\nsymlinks skills from there into your agent directories — not from your working\nclone. If you used the quick installer, your agent reads that managed copy, not\nyour working branch.\n\nTo test local changes, re-point the Claude Code symlink directly to your clone:\n\n```bash\nrm ~/.claude/skills/vsql-extension-builder\nln -s ~/code/villagesql-skills/skills/vsql-extension-builder ~/.claude/skills/vsql-extension-builder\n```\n\nBranch switches are then live immediately. When you're done, re-running the\nquick installer restores the managed copy.\n\nIf you add a new file to `references/`, call it out in your PR description —\na maintainer will update the quick-install script to include it.\n\n## License\n\nApache-2.0 — see [`LICENSE`](LICENSE).\n\n## Links\n\n- VillageSQL: <https://villagesql.com>\n- Documentation: <https://villagesql.com/docs>\n- Discord: <https://discord.gg/KSr6whd3Fr>\n",
  "bytes": 5208,
  "sha": "24bf300487591348ea77c635fe9524349c03acc4f052d82915acfd09d55665fe",
  "repo_slug": "villagesql/villagesql-skills",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/plg_villagesql_villagesql_skills_vsql_extens_96680bb3/readme"
}