dev-skills

A collection of reusable Agent Skills for software development workflows. Built for Claude Code as a plugin; the individual SKILL.md files are also usable by any agent that reads the Agent Skills format.

Skills

Grouped by workflow:

• Spec authoring — turn requirements into a structured spec before coding.
• Dev flow — discuss → implement → wrap up a feature.
• Notion integration — bridge between local code/reports/meeting notes and Notion's Roadmap + Meetings databases.
• Utilities — standalone helpers.

Spec authoring

Skill	Purpose
spec	Generate a multi-file engineering specification (architecture, data models, APIs, features) from a system description.
spec-review	Evaluate a specification.md for clarity, completeness, and consistency — focused on data model correctness and Given-When-Then behavior coverage.

Dev flow

Four phases — start-of-day sync, planning, wrap-up, and session housekeeping — plus one orchestrator that ties wrap-up together.

   SYNC          PLANNING                IMPLEMENTATION              WRAP-UP
 ┌────────┐   ┌────────────┐                                  ┌──────────────────┐
 │  sync  │──►│  discuss   │ ───►  (you write the code)  ───► │     wrap-up      │
 └────────┘   └────────────┘                                  └────────┬─────────┘
                                                                       │ orchestrates
                                                  ┌────────────────────┼──────────────┐
                                                  ▼                    ▼              ▼
                                               verify            update-docs     code-review
                                                  │                    │              │
                                                  └─────────────►   report   ◄────────┘
                                                                       │
                                                                       ▼
                                                                rename-session
                                                                       │
                                                                       ▼
                                                                sync-report (if Notion-configured)
                                                                       │
                                                                       ▼
                                                              git commit (optional)
                                                                       │
                                                                       ▼
                                                                deploy (optional)

Skill	Phase	Purpose
sync	start-of-day	Safety net for git-illiterate collaborators. Fetches, auto-merges upstream (current branch + origin/main + teammate branches updated in last 24h), pushes. Dirty tree → defers to /wrap-up Quick. Any merge conflict aborts cleanly.
discuss	planning	Senior design/architecture advisor that drives a collaborative back-and-forth before any plan is written. Auto-invoked during plan mode.
verify	wrap-up	Executes the implementation plan's Test plan / Verification section. Runner, not author — does not write new tests.
update-docs	wrap-up	Detection-driven docs updater. Scans the project's doc layout, classifies the diff, and proposes per-file edits.
code-review	wrap-up	Multi-agent review of the local git diff. Writes a single REVIEW.md with findings tiered Critical/Warning/Suggestion/Nit (drops only auto-zeroed false positives).
report	wrap-up	Distills the conversation, file changes, and decisions into docs/reports/YYYY-MM-DD-[title].md. /report transcript exports the raw conversation instead, listing the files read/modified.
rename-session	housekeeping	Renames the current Claude Code or Codex session with a short title. Auto-invoked after runs.

How to use:

• Opening Claude Code on a shared repo? Run /sync first. It pulls the latest from origin/main + teammates' recent branches into your current branch so you start from the freshest state. If your tree is dirty, /sync will offer to run /wrap-up Quick to save first.
• Starting a non-trivial task? Begin with /discuss (or just enter plan mode — discuss auto-invokes) to surface design alternatives before writing code.
• Done implementing? Run /wrap-up. Picks Full or Quick mode. Full chains the full wrap-up steps; Quick ships report + safe commit + push only (for collaborators with low git literacy or anyone short on time).
• Need just one step? Each skill is invocable on its own — /verify, /update-docs, /code-review, /report, /rename-session — and wrap-up will skip steps you've already run earlier in the session if nothing relevant changed.
• Manual flow without wrap-up: /verify → /update-docs → /code-review → fix Critical/Warning findings (Suggestion/Nit are advisory) → /report → /rename-session → /sync-report → commit → deploy.

Notion integration

These skills bridge between local code/docs and a shared Notion workspace (Roadmap DB + Meetings DB). Notion is master for task and meeting state; local files are working copies.

                ┌────────────────┐
                │  setup-notion  │  (one-time, writes config to AGENTS.md)
                └────────────────┘

 MEETING FLOW                                    TASK FLOW
 ────────────                                    ─────────
 transcript / Plaud URL                     ┌──► Notion task
       │                                    │          │
       ▼ /meeting-notes                     │          ▼ /fetch-task
 docs/meetings/YYYY-MM-DD-*.md              │    docs/tasks/<slug>.md
       │                                    │          │
       ▼ /upload-meeting                    │      (you work)
 Notion Meetings DB page                    │          │
       │                                    │          ▼ /report
       ▼ /create-tasks                      │    docs/reports/YYYY-MM-DD-*.md
 extracts commitments → Notion tasks ───────┘          │
 (links back to meeting)                               ▼ /sync-report
                                                 appends to linked Notion task

Skill	Direction	Purpose
setup-notion	config	One-time wizard. Records Roadmap DB URL, Meetings DB URL, and optional team roster in AGENTS.md; adds docs/tasks/ to .gitignore. Idempotent.
fetch-task	Notion → local	Pulls a Notion task into docs/tasks/<slug>.md. Read-only against Notion. Refreshes only the managed # Context section on re-run. With no args, picks from your active tasks.
sync-report	local → Notion	Pushes docs/reports/*.md to a Notion task — appends body, suggests Status, fills Github Link from HEAD. Linked reports fast-path; unlinked reports prompt a candidate picker.
meeting-notes	transcript → local	Turns a transcript (Plaud.ai share URL, local file, or pasted text) into a structured Traditional-Chinese meeting note at docs/meetings/YYYY-MM-DD-<title>.md.
upload-meeting	local → Notion	Uploads a meeting markdown to the configured Notion Meetings DB. Auto-chained after /meeting-notes.
create-tasks	local → Notion	Extracts commitments from a meeting note, classifies LINK / DRAFT / SKIP, pre-matches against the Roadmap's Current view, then creates new tasks + wires up the meeting's Tasks relation on approval.

Authority model: Only /sync-report and /create-tasks write to Notion. /fetch-task, /setup-notion, /meeting-notes are read-only against Notion (setup writes to local config only). /upload-meeting writes one Meetings DB page.

How to use:

• First time in this repo? Run /setup-notion once. It writes Roadmap + Meetings DB URLs into AGENTS.md and gitignores docs/tasks/. Skipped silently on re-run.
• Starting work on a Notion task? Run /fetch-task <url> to pull it into docs/tasks/<slug>.md. With no args, you get a picker of your active tasks. Re-run any time to refresh the # Context section without touching your notes.
• Done with a task? /wrap-up automatically chains /sync-report at step 6 — appends your report to the linked Notion task and suggests a Status. To run it standalone: /sync-report after /report.
• After a meeting? /meeting-notes <plaud-url | file | paste> synthesizes a structured note. It then auto-chains /upload-meeting (push to Meetings DB) and offers /create-tasks (extract commitments → Notion tasks, linked back to the meeting).

Utilities

Skill	Purpose
find-session	Search Claude Code or Codex sessions by topic or file-change evidence; --open refreshes/opens the log. Searches both by default; --host filters the source.
headless-shots	Screenshot or drive a locally running web app via headless Chrome + CDP with a minted login cookie — fallback when the Playwright MCP browser is locked; write-path checks verified against the DB.

Folder Structure

dev-skills/
├── .claude-plugin/
│   ├── plugin.json
│   └── marketplace.json
├── skills/
│   └── <skill-name>/
│       ├── SKILL.md
│       └── agents/ (optional)
│           └── <agent-name>.md 
├── AGENTS.md
├── CLAUDE.md  →  AGENTS.md (symlink)
└── README.md

Install

Claude Code (as a plugin)

From GitHub:

/plugin marketplace add dropout-tech/dev-skills
/plugin install dev-skills

The first command registers this repo's marketplace.json as a plugin source; the second installs the dev-skills plugin from that marketplace. After install, restart Claude Code to load the skills.

For local development against a clone:

/plugin marketplace add ~/dev-skills
/plugin install dev-skills@dev-skills

Session operations use one cross-host entry point: bin/session-adapter.py provides show, rename, export, and Codex log, then delegates to the Claude Code or Codex backend. bin/codex-session.py remains as a compatibility shim.

Codex working logs

bin/session-adapter.py log --open refreshes and opens a derived .log.md for this Codex session. --watch refreshes while running; configured lifecycle hooks refresh automatically after /hooks trust review. See Codex session log hooks. skills/find-session/scripts/search.py --host codex searches persisted App Server history and --open-id current opens the current log. session-log.py also routes show/note/writes/export to Codex when its thread ID is exposed. Write evidence covers completed fileChange events only, not shell or MCP writes; the compatibility export applies credential-pattern redaction. Claude history remains available through --host claude.

In shared skill instructions, Claude Code's AskUserQuestion maps to Codex's request_user_input whenever that tool is exposed by the current host. Use the host's approval mechanism for shell permissions; fall back to a concise chat question only when the structured input tool is unavailable.

Codex (local clone)

Link each skill from the clone (<clone>/skills/<name>) into ~/.codex/skills/; edits are available through those links without copying or reinstalling. Invoke a skill with $wrap-up, $verify, or its name in your request.

Keep the entire clone for skills that use bin/ helpers. Session operations use bin/session-adapter.py to resolve the host, identity, and backend in code. Skills describe their own task-specific commands; they do not load a mandatory compatibility preamble. The runtime reference is optional maintainer documentation for troubleshooting host differences.

The shared workflow supports both Claude Code and Codex. Codex uses its own available tools, approval UI, inherited review-agent model, and session identity. Claude-specific argument-hint frontmatter has been moved into the skill body as Arguments so both hosts can parse the same metadata.

Capability	Codex behavior
Planning, verification, reports, reviews	Shared workflow with host tool mappings
Notion operations	Require an available, authenticated connection; use its actual schemas
Session search	Searches Claude + Codex by default; --host codex or --host claude restricts the source
Session rename	bin/session-adapter.py rename selects the host and verifies the saved title
Raw transcript export	bin/session-adapter.py export selects the host exporter; Codex pages persisted turns
Working log	session-adapter.py log --open refreshes and opens a persistent .log.md; --watch polls while running; local notes survive refresh
Write attribution	Completed fileChange events only; shell writes and Claude hunk snapshots are not inferred
Session-log hooks	Four user hooks configured locally; /hooks trust review is required before they run. See hook setup

Gemini CLI

Install all skills from this repo (user-level / global):

gemini skills install https://github.com/dropout-tech/dev-skills.git --path skills

Project-level install:

gemini skills install https://github.com/dropout-tech/dev-skills.git --path skills --scope workspace

Or, if you've cloned the repo locally, link it for live updates:

gemini skills link ~/dev-skills/skills

Verify with gemini skills list, or /skills reload inside an active session.

GitHub CLI (multi-agent)

The gh skill command can install individual skills from this repo into any supported agent:

gh skill install dropout-tech/dev-skills <skill-name> --agent claude-code --scope user
gh skill install dropout-tech/dev-skills <skill-name> --agent gemini-cli --scope user
gh skill install dropout-tech/dev-skills <skill-name>                         # defaults to github-copilot, project scope

<skill-name> is one of: code-review, create-tasks, discuss, fetch-task, find-session, meeting-notes, rename-session, report, setup-notion, spec, spec-review, sync, sync-report, update-docs, upload-meeting, verify, wrap-up. See gh skill install for the full list of supported agents and flags.

Manual

Each skills/<name>/ folder follows the standard Agent Skills layout (a SKILL.md with YAML frontmatter). Drop a skill folder into whichever directory your agent reads from:

• Claude Code: ~/.claude/skills/ (user) or .claude/skills/ (project)
• Gemini CLI (user): ~/.gemini/skills/ or ~/.agents/skills/
• Gemini CLI (project): .gemini/skills/ or .agents/skills/
• GitHub Copilot (user): ~/.copilot/skills/ or ~/.agents/skills/ or ~/.claude/skills/
• GitHub Copilot (project): .github/skills/ or .agents/skills/ or .claude/skills/