# agent-plugins A personal, portable collection of agent skills, packaged as an [Agent Plugin](https://agent-plugins.org/). The plugin format is client-agnostic: any coding agent that supports the spec (or the underlying [Agent Skills](https://agentskills.io/) format) can use these skills, which makes them easy to sync across machines and share with others. ## Layout ``` agent-plugins/ ├── plugin.json # Plugin manifest (agent-plugins.org spec) ├── README.md └── skills/ ├── ai-commit/ │ └── SKILL.md ├── code-walkthrough/ │ └── SKILL.md ├── eli5/ │ └── SKILL.md └── plan-build/ ├── SKILL.md └── agents/ └── openai.yaml # Codex-specific interface metadata ``` Each directory under `skills/` is one skill. A skill is just a `SKILL.md` file: YAML frontmatter (`name`, `description`, optional `allowed-tools` and `metadata`) followed by the instructions the agent loads when the skill is activated. ## The skills | Skill | What it does | |-------|--------------| | **ai-commit** | Generates a single conventional commit message (`feat:`, `fix:`, `chore:`, …) from staged git changes. Built to be called non-interactively via `claude -p` from a shell alias. | | **code-walkthrough** | Produces a guided, step-by-step walkthrough of how a piece of code works, tracing execution from the entry point with real file paths and line numbers. | | **eli5** | Explains a PR, feature, or code change in plain English — big picture first, then a concept-by-concept breakdown a smart non-expert could follow. | | **plan-build** | Inspects a ticket and the codebase, then walks through the planned implementation (mental model, components, concrete changes, ordered steps) before any code is written. | ## Using the skills ### Claude Code Claude Code discovers personal skills in `~/.claude/skills/`. Symlink the ones you want so they stay in sync with this repo: ```bash for skill in ai-commit code-walkthrough eli5 plan-build ln -s ~/projects/agent-plugins/skills/$skill ~/.claude/skills/$skill end ``` (That's fish syntax; in bash/zsh use `for skill in ...; do ln -s ...; done`.) Then invoke a skill by name in a session (`/eli5 7450`, `/code-walkthrough how does X work`), or let Claude activate it automatically when the request matches the skill's description. `ai-commit` is designed for headless use in a shell alias: ```bash git commit -m "$(claude -p 'Use the ai-commit skill to write a commit message for the staged changes')" ``` ### Codex Codex discovers skills in `~/.codex/skills/`. Symlink them the same way: ```bash for skill in ai-commit code-walkthrough eli5 plan-build ln -s ~/projects/agent-plugins/skills/$skill ~/.codex/skills/$skill end ``` `plan-build` ships an `agents/openai.yaml` with Codex interface metadata (display name, default prompt), which Codex picks up automatically. ### Other clients Any client that implements the agent-plugins spec can install this directory as a plugin directly — `plugin.json` at the root identifies it, and skills are discovered from `skills/*/SKILL.md`. For clients that only understand the Agent Skills format, copy or symlink the individual skill directories into wherever that client looks for skills. ### New machines Clone the repo and re-run the symlink loop: ```bash git clone ~/projects/agent-plugins ``` ## Adding a new skill 1. Create `skills//SKILL.md` with frontmatter: ```yaml --- name: skill-name # must match the directory name; lowercase + hyphens description: What it does and when to use it. This is what agents match against. allowed-tools: Read Grep # optional, space-separated string metadata: version: "1.0.0" # optional, free-form string map --- ``` 2. Write the instructions in the Markdown body. Keep it under ~500 lines; move bulky material into `references/` or `scripts/` inside the skill directory. 3. Optionally validate with the reference tool: `skills-ref validate skills/` (from [agentskills/agentskills](https://github.com/agentskills/agentskills)). ## Notes on the migration These skills were migrated from `~/.claude/skills` and `~/.codex/skills`. Two frontmatter changes were needed for spec compliance: - `allowed-tools` is a **space-separated string** in the Agent Skills spec, not a YAML list. - `version` is not a top-level frontmatter field; it lives under `metadata:`. Skill bodies are unchanged from the originals. ## License [MIT](LICENSE) — use, copy, and adapt freely.