agent-skills is a repository of reusable skills for coding agents. The repository itself is the main artifact: it contains the skills, their supporting subagents and references, and the docs used to keep the skill format portable across OpenCode and Claude Code.

What is in this repository

skills/ contains 27 first-party skills. Each skill has its own SKILL.md, with subagents/ and references/ added where needed.
prompts/ contains reusable prompt families. Each family is a kebab-case directory that keeps related executable prompts together with any contracts and supporting docs. See prompts/README.md for the catalog and addition rules.
docs/ contains workflow notes, design specs, and project-specific planning documents.
docs/best-practices/ is the best starting point for skill-authoring guidance.
.agents/skills/ contains pinned skill packages for OpenCode discovery. Some come from this repository, and some come from other repositories.
.claude/skills/ mirrors the pinned skill packages for Claude Code discovery.
skills-lock.json records the pinned skill set used for installed skill packages.
opencode.jsonc stores OpenCode configuration. It currently enables the Context7 MCP server.

First-party skills

Most first-party skills belong to the shared work-item workflow or to standalone utilities. Every workflow phase is platform-agnostic: each skill detects Jira or GitHub from its input and loads the matching per-platform playbook just in time.

Work-item workflow

Phases run in order. <KEY> is TICKET_KEY for Jira or ISSUE_SLUG for GitHub; the TICKET_KEY parameter name carries either value.

orchestrating-workflow runs the full Jira or GitHub workflow through the active platform playbook.
Phase 1 — fetching-work-item saves a Jira ticket or GitHub issue snapshot to docs/<KEY>.md.
Phase 2 — planning-work-item-tasks turns the snapshot into a task plan in docs/<KEY>-tasks.md.
Phases 3 and 6 — clarifying-assumptions handles upfront plan questions and task-level critique.
Phase 4 — creating-work-item-children creates or reconciles Jira subtasks or GitHub child issues after approval.
Phase 5 — planning-task-execution writes the brief, execution plan, test spec, and refactoring plan for one task.
Phase 7 — executing-work-item-task carries one planned task through implementation and review.

Utility skills

analyzing-recent-project-state summarizes recent repository changes, risks, validation gaps, and next steps.
committing-scoped-changes creates reviewable commits from explicit file or folder paths.
council-of-advisors runs a nine-seat decision council and writes a full decision handoff file with a compact recommendation summary.
diagnosing-root-causes identifies the root cause of runtime, CI/CD, and user-reported issues from provided resources and explains it with evidence-based, traceable, educational reporting.
generate-flow-diagram creates, refines, repairs, or decomposes Markdown and Mermaid workflow diagrams with approval gates, staged writes, and Mermaid validation.
generate-handoff-document writes a handoff document for work that needs to be resumed later.
improving-skill-definition improves an existing skill package when inspection finds a material issue.
improving-test-suites improves test files with focused, behavior-oriented test coverage.
planning-codebase-restructuring analyzes repository architecture and produces an evidence-backed restructuring plan aligned with Domain-Driven Design and Screaming Architecture.
pr-creator prepares and opens a pull request from the current branch.
prompt-structurer turns prose prompts into structured XML prompts.
recency-guard checks answers that depend on current external facts.
refactoring-code refactors existing code while preserving observable behavior.
refine-task reviews Jira tickets, Jira epics, GitHub issues, and GitHub parent issues for readiness.
responding-to-pr-review-comments assesses received PR review comments and drafts responses.
review-pull-request reviews one pull request through a confirmation-gated workflow.
review-software-engineer-cv reviews and tailors a software engineer CV against job postings.
rewriting-code-strictly rewrites Python, TypeScript, JavaScript, and Go code with stricter types and boundary handling.
validate-implementation-plan audits implementation plans for requirements coverage, avoidable complexity, weak assumptions, and evidence gaps.
workflow-skill-architect turns a repeatable process into a reusable skill package.

Installed skill packages

These skill packages live under .agents/skills/. The lockfile records their source and hash.

For first-party skill changes, pull requests should normally update the source package under skills/ only. The vendored discovery copies under .agents/skills/ and .claude/skills/, plus skills-lock.json, are refreshed after the source PR merges by the managed skills CLI flow. Reviewers and agents should not request same-PR mirror or lockfile updates for ordinary first-party skill edits unless the PR explicitly claims to sync installed packages or already touches those managed artifacts.

Skill	Source
`api-security-best-practices`	`sickn33/antigravity-awesome-skills`
`architecture-patterns`	`wshobson/agents`
`clean-code`	`sickn33/antigravity-awesome-skills`
`code-review-excellence`	`wshobson/agents`
`committing-scoped-changes`	`b-mendoza/agent-skills`
`council-of-advisors`	`b-mendoza/agent-skills`
`diagnosing-root-causes`	`b-mendoza/agent-skills`
`executing-plans`	`obra/superpowers`
`generate-flow-diagram`	`b-mendoza/agent-skills`
`idea-refine`	`addyosmani/agent-skills`
`improving-test-suites`	`b-mendoza/agent-skills`
`interview-me`	`addyosmani/agent-skills`
`planning-codebase-restructuring`	`b-mendoza/agent-skills`
`ponytail`	`DietrichGebert/ponytail`
`pr-creator`	`b-mendoza/agent-skills`
`prompt-structurer`	`b-mendoza/agent-skills`
`receiving-code-review`	`obra/superpowers`
`recency-guard`	`b-mendoza/agent-skills`
`refactoring-code`	`b-mendoza/agent-skills`
`responding-to-pr-review-comments`	`b-mendoza/agent-skills`
`review-pull-request`	`b-mendoza/agent-skills`
`rewriting-code-strictly`	`b-mendoza/agent-skills`
`spec-driven-development`	`addyosmani/agent-skills`
`stop-slop`	`hardikpandya/stop-slop`
`subagent-driven-development`	`obra/superpowers`
`test-driven-development`	`obra/superpowers`
`unslop`	`cursor/plugins`
`validate-implementation-plan`	`b-mendoza/agent-skills`
`vitest`	`antfu/skills`
`workflow-skill-architect`	`b-mendoza/agent-skills`
`writing-plans`	`obra/superpowers`

Notes for editing

Keep skills portable across OpenCode and Claude Code. Use simple frontmatter, plain Markdown links, and the runtime-portability-matrix when changing tool, permission, or subagent behavior.
Before editing a skill, subagent, or reference file, read the relevant guide in docs/best-practices/README.md.
There is no CI pipeline for skill authoring. Run skills-ref validate and the manual checks in docs/agent/skill-verification.md.
Do not hand-edit skills-lock.json or vendored installed packages under .agents/skills/ or .claude/skills/. They are managed by the skills CLI flow after source changes are merged.