Write AI agent skills once, use everywhere — portable skill library for Claude Code, Kiro, Codex, Gemini, OpenClaw, Cursor & more.
Every AI coding agent has its own way of consuming instructions — CLAUDE.md, AGENTS.md, .kiro/specs/, .cursor/rules.md. Writing skills for one means rewriting for another. That's unsustainable when you're switching agents across machines, teams, or tasks.
polyagent-skills is a spec-driven, agent-agnostic skill library. Skills are written once in portable Markdown and consumed by any agent through thin adapter files.
┌──────────────────────────────────────────────────┐
│ Layer 3: Adapters (thin, per-agent) │
│ CLAUDE.md / AGENTS.md / .kiro/ / .gemini/ │
├──────────────────────────────────────────────────┤
│ Layer 2: Skill Library (portable, markdown) │
│ skills/requirement-study/ skills/deck-creator/ │
├──────────────────────────────────────────────────┤
│ Layer 1: Common Foundation (shared patterns) │
│ common-skills/ templates/ conventions │
└──────────────────────────────────────────────────┘
| Agent | Adapter File | Status | Notes |
|---|---|---|---|
| Claude Code | ~/.claude/CLAUDE.md |
✅ Supported | Reads filesystem directly; no extra step needed |
| OpenAI Codex | ~/.codex/AGENTS.md |
✅ Supported | |
| AWS Kiro | ~/.kiro/specs/polyagent-skills.md |
✅ Supported | |
| Google Gemini Code Assist | .gemini/instructions.md |
✅ Supported | IDE integration; may need project-local install |
| Google Gemini CLI | ~/.gemini/instructions.md + native registry |
✅ Supported | Requires gemini skills link — handled automatically by install-global |
| OpenClaw | ~/.openclaw/skills/ |
✅ Supported | |
| Cursor | .cursor/rules.md |
✅ Supported | |
| Windsurf | .windsurfrules |
🟡 Planned |
# Clone the repo
git clone https://github.com/gyanranjan/polyagent-skills.git
cd polyagent-skills
# Check prerequisites (and optionally install missing tools)
python3 scripts/polyagentctl.py doctor --fix
# One-time global install (Claude Code + Codex + Kiro + Gemini + OpenClaw)
# This also installs polyagentctl and md-to-pdf to ~/.local/bin/
python3 scripts/polyagentctl.py install-global copy
# Ensure ~/.local/bin is in your PATH
export PATH="$HOME/.local/bin:$PATH" # Add to your .bashrc or .zshrc
# polyagentctl and md-to-pdf are now available globally
polyagentctl doctor
md-to-pdf --help
# (Optional) explicit reinstall to PATH
python3 scripts/polyagentctl.py self-installpolyagentctl install-project /path/to/my-project all polyagentctl install-project /path/to/my-project claude-code
Use global install when you want "set once, reuse everywhere." Use project install when you want repo-local agent config files.
## Spec-Driven Delivery Flow
```mermaid
flowchart LR
A[English Notes] --> B[Requirement Study]
B --> C{Design Readiness Gate}
C -->|Pass/Deferred| D[Implementation Sketch]
C -->|Open Items| T[agent.todo.md Blocked + Decision Needed]
D --> E[Repo Bootstrap]
E --> F[Code + Tests]
F --> G[GitHub Issues/PRs]
F --> H[RCA if incidents/defects]
H --> B
Key controls before coding:
- Requirements traced as
REQ-*/NFR-* - Architecture pattern, language/runtime, DB strategy, and logging baseline decided
- Open design items explicitly blocked in
agent.todo.md
polyagentctl install-global copyThis installs:
- Shared global library:
~/.polyagent-skills/skillsand~/.polyagent-skills/common-skills - Global Claude Code instructions:
~/.claude/CLAUDE.md - Global Codex instructions:
~/.codex/AGENTS.md - Global Kiro instructions:
~/.kiro/specs/polyagent-skills.md - Global Gemini instructions:
~/.gemini/instructions.md - OpenClaw managed skills:
~/.openclaw/skillsand~/.openclaw/common-skills
Optional dev mode (symlinks shared library for live edits):
polyagentctl install-global link# Preview what would be removed
polyagentctl uninstall-global --dry-run
# Remove only installer-managed paths
polyagentctl uninstall-globalUninstall removes only paths recorded in installer manifest files and only when ownership markers match.
polyagentctl install-project /path/to/my-project allThis copies adapters plus skills/ and common-skills/ into that specific project.
| Skill | Purpose | Status |
|---|---|---|
| idea-to-mvp | Turn a rough idea into a validated MVP plan | ✅ Active |
| requirement-study | Analyze, write, and validate requirements | ✅ Active |
| implementation-sketch | Create implementation plans from specs | ✅ Active |
| mail-summarizer | Summarize and draft replies to emails | ✅ Active |
| document-analyzer | Understand and extract insights from documents | ✅ Active |
| deck-creator | Create presentations from content | ✅ Active |
| repo-bootstrap | Scaffold new repositories with best practices | ✅ Active |
| agent-writer | Write new agent definitions | ✅ Active |
| desensitizer | Data desensitization and anonymization | ✅ Active |
| remote-ops | Remote operations and infra management | ✅ Active |
| expert-research | Deep expert analysis and recommendation support | ✅ Active |
| context-orchestrator | Build reusable project context packs and session handoffs | ✅ Active |
| automation-architect | Design automation pipelines, CI/CD systems, and workflow automation | ✅ Active |
| business-strategist | Market positioning, business model design, and competitive strategy | ✅ Active |
| customer-advocate | Deep user empathy and voice-of-customer for product decisions | ✅ Active |
| devils-advocate | Stress-test decisions and plans by arguing the opposing case | ✅ Active |
| engineering-team | Translate specs into engineering tasks, plans, and code scaffolds | ✅ Active |
| entrepreneur | Opportunity-first thinking, value propositions, and business outcomes | ✅ Active |
| growth-engineer | Acquisition, activation, retention, and referral growth systems | ✅ Active |
| historian-knowledge-curator | Organizational memory, decisions, and learnings capture | ✅ Active |
| ideator | Divergent idea generation and creative lateral thinking | ✅ Active |
| operations-commander | Production readiness, deployment, runbooks, and incident response | ✅ Active |
| poc-spike | Proof-of-concept spikes to de-risk technical unknowns | ✅ Active |
| product-manager | Product spec, feature prioritization, and outcome-driven decisions | ✅ Active |
| qa-validator | Test strategies, acceptance criteria, and pre-delivery validation | ✅ Active |
| research-analyst | Deep research, evidence synthesis, and confidence-aware findings | ✅ Active |
| role-orchestrator | Classify tasks, select roles, manage handoffs across multi-agent workflows | ✅ Active |
| security-guardian | Threat modeling, vulnerability review, and secure design validation | ✅ Active |
| subject-matter-expert | Parameterizable deep domain expert (e.g. SME Kubernetes, SME Finance) | ✅ Active |
| systems-architect | Scalable system design, architecture decisions, and trade-off analysis | ✅ Active |
| systems-simplifier | Identify and eliminate unnecessary complexity and over-engineering | ✅ Active |
| visionary-futurist | Long-horizon technology trajectories and second-order consequences | ✅ Active |
polyagent-skills/
├── README.md
├── LICENSE
├── CONTRIBUTING.md
├── KNOWN_ISSUES.md
├── agent.todo.md # Canonical cross-session, multi-agent TODO ledger
│
├── docs/
│ ├── specs/ # Spec-driven development
│ │ ├── SPEC_TEMPLATE.md
│ │ ├── skill-format-spec.md
│ │ └── adapter-contract-spec.md
│ ├── adrs/ # Architecture Decision Records
│ │ ├── ADR_TEMPLATE.md
│ │ ├── 001-markdown-as-skill-format.md
│ │ ├── 002-three-layer-architecture.md
│ │ ├── 003-adapter-pattern.md
│ │ ├── 004-mcp-for-tool-skills.md
│ │ ├── 005-workflow-orchestration-and-session-todo.md
│ │ └── 006-gated-development-lifecycle.md
│ ├── rca/ # Root Cause Analysis templates and docs
│ │ └── RCA_TEMPLATE.md
│ └── rfcs/ # Proposals for significant changes
│ └── RFC_TEMPLATE.md
│
├── common-skills/ # Shared building blocks
│ ├── README.md
│ ├── agent-todo-ledger.md
│ ├── design-readiness-gate.md
│ ├── document-tail-sections.md
│ ├── output-formatting.md
│ ├── quality-checklist.md
│ └── mermaid-to-pdf.md
│
├── skills/ # Portable skill library
│ ├── idea-to-mvp/
│ ├── requirement-study/
│ ├── implementation-sketch/
│ ├── poc-spike/
│ ├── mail-summarizer/
│ ├── document-analyzer/
│ ├── deck-creator/
│ ├── repo-bootstrap/
│ ├── agent-writer/
│ ├── desensitizer/
│ ├── remote-ops/
│ ├── expert-research/
│ ├── context-orchestrator/
│ ├── automation-architect/
│ ├── business-strategist/
│ ├── customer-advocate/
│ ├── devils-advocate/
│ ├── engineering-team/
│ ├── entrepreneur/
│ ├── growth-engineer/
│ ├── historian-knowledge-curator/
│ ├── ideator/
│ ├── operations-commander/
│ ├── product-manager/
│ ├── qa-validator/
│ ├── research-analyst/
│ ├── role-orchestrator/
│ ├── security-guardian/
│ ├── subject-matter-expert/
│ ├── systems-architect/
│ ├── systems-simplifier/
│ └── visionary-futurist/
│
├── adapters/ # Thin agent-specific wrappers
│ ├── claude-code/
│ ├── codex/
│ ├── kiro/
│ ├── gemini/
│ └── cursor/
│
├── mcp-servers/ # MCP servers for tool-based skills
│
├── templates/ # Reusable document templates
│ ├── decision-record.md
│ ├── handoff-note.md
│ ├── research-request.md
│ └── role-status.md
│
├── tests/ # Test suite
│ └── test_polyagentctl.py
│
├── projects/ # Example and reference projects
│ └── example-project/
│
├── scripts/ # Automation (single entry point)
│ └── polyagentctl.py # Unified CLI — all operations, no shell deps
│
├── agent-notes/ # Cross-cutting agent observations
│
└── .github/
├── ISSUE_TEMPLATE/
└── workflows/
- Skills are knowledge, not code — Written in Markdown, readable by any LLM
- Adapters are thin — Never put skill logic in an adapter; only pointers
- Spec-driven — Every skill follows the Skill Format Spec
- Decisions are recorded — All architecture choices have an ADR
- Common patterns are shared — DRY via
common-skills/ - MCP for tools — When skills need capabilities (not just instructions), use MCP
- Skill Format Spec — How to write a portable skill
- Adapter Contract Spec — How adapters work
- Architecture Decision Records — Why we made the choices we did
- RCA Template — Root cause analysis format for incidents/defects
- Known Issues — Current limitations and workarounds
- Contributing Guide — How to add skills and adapters
All operations are available through a single Python CLI — no shell required.
# Check prerequisites; --fix to install missing optional tools interactively
polyagentctl doctor [--fix]
# Validate design readiness sections (strict: fails on Open)
polyagentctl design-check path/to/requirements.md path/to/spec.md
# Structure-only validation (allows Open)
polyagentctl design-check --allow-open path/to/spec.md
# Check lifecycle gate status
polyagentctl gate-check [agent.todo.md]
# Sync requirement/spec traceability into agent.todo.md
polyagentctl sync-todo agent.todo.md path/to/requirements.md [path/to/spec.md]
# Create GitHub issue stubs from REQ IDs
polyagentctl init-issues path/to/requirements.md org/repo
# Convert Markdown with Mermaid diagrams to PDF (falls back to HTML when no PDF tool available)
md-to-pdf path/to/document.md
# Verify context pack structure and traceability
polyagentctl verify-context-pack context/pack.md
# Regenerate skill lists in all adapter files
polyagentctl sync-adapters
# Pull a skill from skills.sh
polyagentctl pull-skill <skill-name-or-url>
# Pre-PR quality gate
polyagentctl check --strict --project .After installing, use these checks to confirm each agent can see the skill library.
Claude Code reads the filesystem directly using its tools. Ask it:
"What skills do you have available?"
It should read ~/.claude/CLAUDE.md and list the skills directory. No extra step needed.
Gemini CLI has two layers — a system prompt and a native skill registry. Both must be populated:
# Check what's registered in the native skill registry
gemini skills list
# Should show all 32 skills as [Enabled]. If not, re-run install:
polyagentctl install-global linkInside a gemini session, ask:
"What skills do you have available?"
It should list all Active Skills including idea-to-mvp, requirement-study, etc.
If you see only skill-creator [Built-in], the native registry wasn't populated. Re-run polyagentctl install-global.
Check that .gemini/instructions.md exists in your project:
polyagentctl install-project . gemini
cat .gemini/instructions.mdThen in the IDE chat ask: "What skills do you have?". See KI-003 if it doesn't respond to skills.
Check ~/.codex/AGENTS.md exists and lists skills. Inside Codex, ask:
"List your available skills."
Check ~/.kiro/specs/polyagent-skills.md exists. In a Kiro session, ask:
"What skills are available to you?"
See KI-001 if Kiro loses context following multi-file reference chains.
polyagentctl doctor # checks prerequisites
polyagentctl check --strict --project . # validates project setup
gemini skills list # Gemini CLI specificMIT — see LICENSE