# dotagents

Shared configuration for my agentic tools. One source of truth for skills, helper
scripts, and instructions used across Claude Code, OpenCode, Codex, Cursor, and
friends.

Clone the repo wherever you like, then link the parts you want into each tool's
config. A change in the repo is picked up everywhere.

## Layout

```
dotagents/
├── skills/          # Agent Skills, one directory per skill (each with a SKILL.md)
├── helpers/         # Small scripts and utilities shared by agents
├── INSTRUCTIONS.md  # Shared agent instructions, symlinked as AGENTS.md
├── AGENTS.md        # Repo guide for agents
└── README.md        # Repo docs for people
```

## Using it

Set the path to your checkout, then link the repo into `~/.agents`. Point each
tool at the hub.

```sh
DOTAGENTS=~/dev/personal/dotagents

# Link the repo into the shared hub.
ln -s "$DOTAGENTS/skills" ~/.agents/skills
ln -s "$DOTAGENTS/INSTRUCTIONS.md" ~/.agents/AGENTS.md

# Then link the hub into each tool.
ln -s ~/.agents/skills ~/.claude/skills
ln -s ~/.agents/AGENTS.md ~/.config/opencode/AGENTS.md
```

Tools that support the Agent Skills layout can consume `skills/` directly; others
can reference individual files.

## Adding a skill

1. Create `skills/<skill-name>/SKILL.md`.
2. Add frontmatter with a `name` and a short `description` that tells the agent
   when to use it.
3. Put supporting scripts or references next to it, or under a `files/`
   subdirectory when there are several.

Skills should be small, self-contained, and safe to share between tools. Avoid
tool-specific assumptions where a generic approach will do.

For a broad topic, prefer one skill whose `SKILL.md` acts as a router. The router
maps the request to a playbook under `files/`, and the agent loads only that part.
`seo` and `marketing` follow this shape.

## Attributions

Most skills are adapted from open-source collections. Where a skill was renamed,
the upstream name is in parentheses.

| Source | License | Skills |
| --- | --- | --- |
| [mattpocock/skills](https://github.com/mattpocock/skills) | MIT | `code-review`, `tdd`, `codebase-design`, `create-tickets` (`to-tickets`), `create-spec` (`to-spec`), `implement`, `research`, `triage` |
| [obra/superpowers](https://github.com/obra/superpowers) | MIT | `brainstorming`, `finish-branch` (`finishing-a-development-branch`), `parallel-work` (`dispatching-parallel-agents`) |
| [pbakaus/impeccable](https://github.com/pbakaus/impeccable) | Apache-2.0 | `impeccable` |
| [Leonxlnx/taste-skill](https://github.com/Leonxlnx/taste-skill) | MIT | `taste` (`design-taste-frontend`) |
| [getsentry/skills](https://github.com/getsentry/skills) | Apache-2.0 | `blog-writing` (`blog-writing-guide`) |
| [juliusbrussee/caveman](https://github.com/juliusbrussee/caveman) | Apache-2.0 | `caveman` |
| [miqdadbadjuber/anti-slop](https://github.com/miqdadbadjuber/anti-slop) | MIT | `antislop`, `antislop-ui`, `antislop-copywriting`, `antislop-human`, `antislop-layoutmobile`, `antislop-code` |
| [ChromeDevTools/chrome-devtools-mcp](https://github.com/ChromeDevTools/chrome-devtools-mcp) | Apache-2.0 | `chrome-devtools`, `chrome-devtools-cli`, `chrome-a11y-debugging`, `chrome-cookie-debugging`, `chrome-debug-optimize-lcp`, `chrome-memory-leak-debugging` |
| [DietrichGebert/ponytail](https://github.com/DietrichGebert/ponytail) | MIT | `ponytail`, `ponytail-audit`, `ponytail-debt`, `ponytail-gain`, `ponytail-help`, `ponytail-review` |

The Ponytail skills were imported unchanged from upstream commit
`09c434ab73ca43761c5d8b0c5d341926c2fba710`, with a license copy in each skill
directory. Plugin features described in `ponytail-help`, such as automatic
activation and the status band, require the upstream plugin. The benchmark
sources named in `ponytail-gain` are in the upstream repository.

Each skill's text is upstream apart from local adaptation: renamed frontmatter,
reference docs moved under `files/`, path fixes, and dropped tool-specific
metadata (`agents/openai.yaml`, authoring-only `evals/`). Skills not listed here
were added before this section existed.

The `seo` and `marketing` skills are written for this repo, not imported.