Agent Skills Setup
herocwhsu/agent-skills-setup
Setup one-command de skills multi-agent com OpenSpec e governança de specs
Ver no GitHubInstalador unificado de skills para múltiplos agentes de IA (Claude Code, Kiro, Gemini CLI). Integra OpenSpec para governança de specs, superpowers para debug e TDD, e skills customizados organizados em grupos (intake, jira, review, infra, utils). Suporta macOS, Linux e Windows com gerenciamento seguro de credenciais via keychain.
Instalação
npx convez-ai herocwhsu/agent-skills-setup1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.
Métricas
Casos de uso
- Integrar skills personalizados em múltiplos agentes de IA simultaneamente
- Implementar workflow spec-gated com governança de propostas e arquivamento
- Centralizar credenciais de serviços (Jira, Confluence, Gemini) com segurança
Veredito

Ferramenta sólida para quem trabalha com múltiplos agentes de IA e precisa de workflow estruturado com governança de specs. A instalação é bem documentada e funciona cross-platform, mas exige familiaridade com shell/PowerShell e conhecimento do ecossistema OpenSpec.
README
A tradução para o português deste README ainda está na fila.
agent-skills-setup
One-command setup for Agent Skills across multiple AI agents and platforms.
Installs:
- OpenSpec — spec governance via
/opsx:propose,/opsx:apply,/opsx:archive(npm package, auto-installed) - superpowers — brainstorming, TDD, systematic debugging, code review, and more
- Custom group skills — five groups (
intake,jira,review,infra,utils) wrapping the previous flat skills, organized for the Spec-Gated Workflow
Supports: Kiro, Claude Code, GitHub Copilot, Codex, Gemini CLI · macOS, Linux, Windows
Quick Start
macOS / Linux / Git Bash:
git clone https://github.com/herocwhsu/agent-skills-setup
cd agent-skills-setup
bash scripts/install.sh
bash scripts/setup-credentials.sh
Windows 11 (native PowerShell):
git clone https://github.com/herocwhsu/agent-skills-setup
cd agent-skills-setup
.\scripts\install.ps1
.\scripts\setup-credentials.ps1
Restart your shell after setup.
Post-install: OpenSpec setup
install.sh installs the openspec CLI globally. Two additional steps are required before /opsx:propose and other OpenSpec slash commands will work.
Step 1 — Initialize OpenSpec in each project:
cd <your-project>
openspec init
Creates a .openspec/ directory and installs /opsx:* slash-command skills into .claude/ (or equivalent for other agents). Run once per project.
Step 2 — Keep skills up to date:
openspec update
Re-run after upgrading openspec to refresh the installed skills.
Note: Skills are installed per-project into
.claude/skills/— not globally. Runopenspec initin every project where you want/opsx:*commands. Restart your IDE after running either command.
Scripts
| Script | Platform | What it does |
|---|---|---|
scripts/install.sh | macOS / Linux / Git Bash | Install superpowers + custom skills |
scripts/install.ps1 | Windows PowerShell | Same, native Windows |
scripts/uninstall.sh | macOS / Linux / Git Bash | Remove installed skills |
scripts/update.sh | macOS / Linux / Git Bash | git pull + re-install |
scripts/run-tests.sh | macOS / Linux / Git Bash | Run all skill + script tests (--fast skips integration tests) |
scripts/setup-credentials.sh | macOS / Linux / Git Bash | Store service credentials in keychain |
scripts/setup-credentials.ps1 | Windows PowerShell | Same, via Windows Credential Manager |
Supported Agents
When prompted, choose one or more:
| # | Agent | Skills directory | Custom skills | Notes |
|---|---|---|---|---|
| 1 | Kiro | ~/.kiro/skills/ | ✓ | Also installs prompts to ~/.kiro/prompts/ |
| 2 | Claude Code | ~/.claude/skills/ | ✓ | |
| 3 | Gemini CLI | ~/.gemini/skills/ | ✓ | |
| 4 | All | all of the above | — |
Credential Setup
setup-credentials.sh (bash) and setup-credentials.ps1 (PowerShell) manage credentials for multiple services. Passwords are stored in the platform keychain only — never exported to env vars.
Required Credentials by Skill:
| Group / Subcommand | Service | Required Key/Auth |
|---|---|---|
utils/polish-input | Gemini / Anthropic | GEMINI_API_KEY (or Google ADC) / ANTHROPIC_API_KEY |
intake/web-page | Confluence | REST API Token + User |
intake/jira-story | Jira | REST API Token + User |
jira/subtasks | Jira | (Uses same Jira credentials as above) |
utils/confluence-tree | Confluence | (Uses same Confluence credentials as above) |
Actions: add · update · delete · list · verify
Example: Add Gemini key for polish-input:
bash scripts/setup-credentials.sh gemini add
Example: Add Anthropic key (alternative):
bash scripts/setup-credentials.sh anthropic add
Verify a credential is stored (safe — value never printed):
bash scripts/setup-credentials.sh confluence verify
Platform storage:
| Platform | Storage | Script |
|---|---|---|
| macOS | Keychain (security) | setup-credentials.sh |
| Linux (GUI) | GNOME Keyring (secret-tool) | setup-credentials.sh |
| Linux (headless/CI) | Inject via pipeline secret at use-time | — |
| Windows 11 | Credential Manager (CredentialManager PS module) | setup-credentials.ps1 |
All entries are namespaced agent-skills-setup:<service> to avoid collisions with system or browser keychain entries.
Windows note: setup-credentials.ps1 auto-installs the CredentialManager module from PSGallery on first run.
Adding a New Skill
The repo follows a group-skill layout: each group is one entry in
registry.txt and one folder under skills/. Subcommands live as peer
folders inside the group, each with its own IMPL.md (the long-form recipe)
plus any lib/ and tests/.
skills/<group>/
SKILL.md # router: subcommand table, slash-command list
<subcommand-a>/
IMPL.md # full bash recipe for /<group>-<subcommand-a>
lib/...
tests/...
<subcommand-b>/
IMPL.md
lib/...
tests/...
Add a subcommand to an existing group
- Create
skills/<group>/<new-subcommand>/IMPL.mdwith the recipe. - Add a row to the subcommand table in
skills/<group>/SKILL.md. - Run
bash scripts/install.shto redeploy. No registry change needed.
Add a brand-new group
- Create
skills/<group>/SKILL.md(frontmattername: <group>+ subcommand table) plus at least one<subcommand>/IMPL.md. - Add
local <group>toregistry.txt. - Run
bash scripts/install.sh.
The install script only manages skills listed in registry.txt — all other
skills in your agent's skills directory are left untouched.
For a full migration map between the previous flat layout and these groups,
see docs/migration.md.
Always-On Engineering Rules (AGENTS.md style)
For cross-cutting rules that should be loaded on every session (not invoked on demand like a skill), use agents/engineering-rules.md and the install-agents-md.sh deploy script. The script writes the rules into a marked block inside each host file:
| Tool | Host file |
|---|---|
| Claude Code | ~/.claude/CLAUDE.md |
| Gemini CLI | ~/.gemini/GEMINI.md |
| Kiro | ~/.kiro/steering/engineering-rules.md |
bash scripts/install-agents-md.sh # Claude + Gemini + Kiro
bash scripts/install-agents-md.sh --claude # Claude only
bash scripts/install-agents-md.sh --gemini # Gemini only
bash scripts/install-agents-md.sh --kiro # Kiro only
bash scripts/install-agents-md.sh --uninstall # strip from all
Or chain it onto the main installer with --with-agents-md:
bash scripts/install.sh --with-hook polish-input --with-agents-md
bash scripts/uninstall.sh --with-hook polish-input --with-agents-md
The --with-agents-md flag deploys to Claude, Gemini, and Kiro simultaneously. The script is idempotent: re-running replaces the block in place, leaving other content in the host file untouched. Edit agents/engineering-rules.md, re-run, and all three tools pick up the change on next session.
Custom Skills
The five group skills (intake, jira, review, infra, utils) cover
intake, planning, code review, infrastructure, and miscellaneous utilities.
Each group's skills/<group>/SKILL.md is the entry point; per-subcommand
recipes live in skills/<group>/<subcommand>/IMPL.md.
For example:
intake/web-page— fetch any URL (Confluence-aware) as a dated markdown referenceintake/jira-story— fetch a Jira issue + every embedded link into./docs/stories/<JIRA-ID>-<slug>/review/pr— review one PR using a mined.code-review/playbook.mdutils/polish-input— install a UserPromptSubmit hook for English prompt polishing
See docs/migration.md for the full mapping from the
previous flat-skill layout.
Claude Code users: Sub-skill invocations use the
Skilltool (e.g.Skill("superpowers:brainstorming")). Thehtml2md.pyconverter is auto-detected from whichever agent skills directory is present (~/.kiro/skills/intake/web-page/,~/.claude/skills/intake/web-page/, etc.), with a fallback to the legacyfetch-page-to-markdown/path for previously installed agents.
Requirements
Python 3 is required at install time (used by install-agents-md.sh for block rewriting and by install_kiro_agent_config for JSON validation). It is also required at runtime for fetch/confluence/polish skills.
The install script needs bash + one of curl/wget for downloading GitHub-sourced skills.
pip is used to install superpowers if available; otherwise the script falls back to downloading directly from GitHub — no pip required.
Windows limitations: update.sh, run-tests.sh, and install-agents-md.sh are bash-only. Windows users should use Git Bash for these scripts or run them manually after git pull.