convez.ai
SkillAutomaçãoIntermediário
herocwhsu

Agent Skills Setup

herocwhsu/agent-skills-setup

Setup one-command de skills multi-agent com OpenSpec e governança de specs

Ver no GitHub
InicialPluginScore · de 0 a 100

Instalador 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-setup

1 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

Estrelas
0
Forks
0
Acompanhando
0
Saúde
28%
Último commit
há 3 dias
Versão
—
Issues abertas
0
Contribuidores
1

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. Run openspec init in every project where you want /opsx:* commands. Restart your IDE after running either command.


Scripts

ScriptPlatformWhat it does
scripts/install.shmacOS / Linux / Git BashInstall superpowers + custom skills
scripts/install.ps1Windows PowerShellSame, native Windows
scripts/uninstall.shmacOS / Linux / Git BashRemove installed skills
scripts/update.shmacOS / Linux / Git Bashgit pull + re-install
scripts/run-tests.shmacOS / Linux / Git BashRun all skill + script tests (--fast skips integration tests)
scripts/setup-credentials.shmacOS / Linux / Git BashStore service credentials in keychain
scripts/setup-credentials.ps1Windows PowerShellSame, via Windows Credential Manager

Supported Agents

When prompted, choose one or more:

#AgentSkills directoryCustom skillsNotes
1Kiro~/.kiro/skills/✓Also installs prompts to ~/.kiro/prompts/
2Claude Code~/.claude/skills/✓
3Gemini CLI~/.gemini/skills/✓
4Allall 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 / SubcommandServiceRequired Key/Auth
utils/polish-inputGemini / AnthropicGEMINI_API_KEY (or Google ADC) / ANTHROPIC_API_KEY
intake/web-pageConfluenceREST API Token + User
intake/jira-storyJiraREST API Token + User
jira/subtasksJira(Uses same Jira credentials as above)
utils/confluence-treeConfluence(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:

PlatformStorageScript
macOSKeychain (security)setup-credentials.sh
Linux (GUI)GNOME Keyring (secret-tool)setup-credentials.sh
Linux (headless/CI)Inject via pipeline secret at use-time—
Windows 11Credential 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

  1. Create skills/<group>/<new-subcommand>/IMPL.md with the recipe.
  2. Add a row to the subcommand table in skills/<group>/SKILL.md.
  3. Run bash scripts/install.sh to redeploy. No registry change needed.

Add a brand-new group

  1. Create skills/<group>/SKILL.md (frontmatter name: <group> + subcommand table) plus at least one <subcommand>/IMPL.md.
  2. Add local <group> to registry.txt.
  3. 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:

ToolHost 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 reference
  • intake/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.md
  • utils/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 Skill tool (e.g. Skill("superpowers:brainstorming")). The html2md.py converter 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 legacy fetch-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.

Ver o original no GitHub

Bom para

Relacionados