Personal Agent Skills collection. Distributed as a Claude Code plugin, but each skill under plugins/aoshimash-skills/skills/ is a plain Agent Skills directory usable by any compliant agent.

1. Add the marketplace:

/plugin marketplace add aoshimash/skills

2. Install the plugin:

/plugin install aoshimash-skills@aoshimash-skills

The plugin is only one distribution channel. Each skill under plugins/aoshimash-skills/skills/ is a plain Agent Skills directory (a SKILL.md plus optional references/, scripts/, assets/), so any agent implementing the Agent Skills spec can use one directly — point your agent at, or copy, the skill directory.

create-issue and implement-issue cover the full issue lifecycle. Each adapts to scale: create-issue goes from a quick single issue to a researched, user-annotated design decomposed into an issue hierarchy; implement-issue goes from one interactive implementation to a dependency-ordered parallel batch. The issue tracker is the interface between them — either skill also works standalone, since a hand-written issue works with implement-issue and a create-issue issue can be implemented manually.

create-issue                               implement-issue
┌─────────────────────────────┐            ┌──────────────────────────────┐
│ Lightweight Flow (default)  │            │ Single Mode (default)        │
│  Gather → Analyze → Draft   │            │  Plan → Approve → Implement  │
│  → Self-eval → Create       │            │  → PR → Review gates         │
│                             │            │                              │
│ Design Flow (escalated)     │  Issues    │ Batch Mode (parent/milestone │
│  Research → Design          │ ────────→  │  /label/list)                │
│  → Annotation cycle         │  (tracker) │  Dependency graph            │
│  → Split Proposal (asks)    │            │  → Parallel worktrees        │
│  → Issue hierarchy          │            │  → Review gates + pattern    │
│                             │            │    propagation → Summary     │
└─────────────────────────────┘            └──────────────────────────────┘

Typical usage:

> /create-issue
# Simple request → gather info → analyze codebase → draft → self-eval → create
# Complex request → research → design → annotate plan → propose a split → create issue(s)

> /implement-issue
# Single issue → plan → approve → implement → PR → two-stage review
# Parent issue / milestone / label / list → confirm batch → dependency graph
#   → parallel worktrees → review gates → summary

Key properties:

• Issue tracker is the interface — Both skills connect only through the issue tracker (GitHub, GitLab, Backlog). No skill-specific files persist after completion.
• Works with humans and AI — Issues created by create-issue are readable and implementable by anyone. Issues written by hand work with implement-issue. A good issue is the same for both readers: it explains why and what — never how.
• Splitting is always proposed, never automatic — create-issue defaults to a single issue; a parent + sub-issue (or nested grandchild) hierarchy is only created after the user confirms a Split Proposal.
• Annotation cycle — in the Design Flow, plans are refined through inline notes in a local markdown file. The file is deleted after issues are created.
• Parallel execution — in Batch mode, implement-issue resolves issue dependencies as a DAG and dispatches independent issues in parallel using git worktrees.
• Two-stage review, always — every PR (single or batch) is reviewed for spec compliance (does it match the issue?) then code quality (is it well-written?). Pattern propagation across in-flight PRs only applies in Batch mode.

The issue workflow draws from two sources, combines them with an issue-centric approach, and has since been revised for an autonomy-first workflow built on 2026-era models:

From superpowers:

• Brainstorming quality — deep clarifying questions, multiple approaches with trade-offs
• Subagent-driven parallel execution with git worktree isolation
• Two-stage review — spec compliance before code quality, because they catch different classes of problems

From Boris Tane's workflow:

• Dedicated research phase before design — prevents implementations that ignore existing patterns, caching layers, or conventions
• Plan as shared mutable state — a local markdown file the user annotates inline, not chat-based steering. Document-based iteration is more precise than conversational back-and-forth
• Annotation cycle — the user adds <!-- NOTE: ... --> comments directly in the plan file, Claude addresses each one, repeat until clean. This is where the highest-value human input happens

superpowers also contributed a staged workflow with hard approval gates, and both sources shared a "boring implementation" ideal — every creative decision settled during planning so that implementing is mechanical. Both ideas have been deliberately retired; see the autonomy-first revision below.

Issue-centric design (original):

• superpowers stores specs and plans in docs/superpowers/ files. This works for solo use but creates friction in team settings — not everyone uses the same tools, and tool-specific files clutter the repo
• Instead, the issue tracker is the single shared artifact. create-issue's Design Flow uses local files only temporarily during the annotation cycle, then converts everything to issues and deletes the files
• This means a team member who doesn't use these skills can still read the issues, pick one up, and implement it — the workflow degrades gracefully

Reader-agnostic issues (original):

• An issue is read by humans and AI agents alike, and a good issue is the same for both: motivation (why), desired end state with binary acceptance criteria (what), and the structural design decisions and constraints behind them — never implementation steps, file-edit lists, or code examples (how)
• Time passes between issue creation and implementation. Implementation detail rots in that gap — other changes land, files move, approaches get invalidated; design decisions and constraints do not. Issues record decisions, never steps
• The quality bar for an issue is tight scope, recorded structural decisions and constraints, and binary acceptance criteria. The implementer (human or implement-issue) plans the how at implementation time, against the codebase as it exists then
• Findings from research that will help at implementation time (current state, gotchas, related code) still belong in the issue as supplementary background — they help humans and AI alike

Autonomy-first revision (2026, original):

• Earlier versions gated implementation behind plan approvals and required every design decision to be settled at issue-creation time. Current models plan natively and follow intent-level instructions reliably, while user round trips became the scarce resource — so pre-approval gates are replaced by autonomous execution reviewed post-hoc at the PR
• Two-layer decision timing — structural decisions (shape of a split, cross-issue consistency, high reversal cost) are recorded in issues at creation time; local, reversible decisions are delegated to implementation time, guided by the decision principles in the shared rules corpus, and logged in the PR. When in doubt, a decision belongs on the issue side
• Never ask twice — before asking, check the decision stores (issue body, repository agent instructions, user-level configuration); every answer is written back to the store matching its scope
• Review-first PRs — removing mid-run gates concentrates human judgment at the PR, so the PR body is ordered for the reviewer: decisions and risk areas first, acceptance criteria mapped to verification evidence, mechanical changes last. Machines finish before humans start: PRs stay draft until CI, the internal review gates, and repository-configured automated reviewers are done; human review comments are never auto-addressed
• This revision is the design contract the skills are being rewritten against; the workflow diagram and typical-usage examples above describe the skills as they are today and will be updated as the rewrites (tracked under #91) land
• Informed by Anthropic's published guidance at the time of this revision — Prompting Claude Fable 5, Claude Code best practices, and harness design for long-running apps — and the Claude Code team's published workflow (How Boris uses Claude Code). Full rationale and decision log: #91

plugins/aoshimash-skills/
├── .claude-plugin/plugin.json    # Plugin manifest
├── rules/
│   └── agent-rules.md            # Shared conventions corpus (read by sync-agent-rules,
│                                 #   appended to by collect-agent-rules)
└── skills/
    └── <skill-name>/
        ├── SKILL.md              # Skill definition (required)
        ├── scripts/              # Helper scripts (optional)
        └── references/           # Reference docs (optional)

rules/agent-rules.md sits outside every skill on purpose: a running skill resolves to a version-pinned copy rather than the git checkout, so the corpus is addressed as a repository path and fetched over the GitHub API at runtime. That also means a rule added there is distributable immediately, without waiting for an installed plugin to update.

MIT