Working agreements for our 1-3 person AI-assisted team. Six docs (vibe coding, Claude Code, git workflow, skills/planning, code style, handoff) plus four templates (CLAUDE.md, README, PR description, handoff checklist). Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
3.8 KiB
3.8 KiB
04 — Skills and planning
How we manage the skill catalog and how we plan work as a small team.
Skill catalog
A "skill" is a reusable, named workflow Claude Code can invoke. We keep three catalogs:
- Personal (
~/.claude/skills/) — private, per developer. - Team (
<repo>/.claude/skills/) — committed, shared via the project. - Bundled / plugin — installed from a marketplace.
When to make a skill
Promote a workflow to a skill when all three are true:
- You've done it the same way three times.
- The steps are stable enough to write down.
- Someone else on the team would do it the same way if shown.
If only two are true, leave it as a prompt snippet in your notes.
Skill design rules
- One skill, one job. Skills that branch on "what does the user want?" are two skills.
- Name the skill as a verb phrase:
review-pr,cut-release,rebuild-fixtures. Notpr-helper. - Description (the one-liner the model sees) must say when to invoke, not what the skill does. The model decides on the when.
- Keep
SKILL.mdunder 200 lines. Long skills get broken into stages. - Examples beat instructions. Show one good run.
Reviewing skills
Treat a new skill like a PR: read it, run it once on a real task, then
merge. Skills that nobody runs after a month get archived (move to
.claude/skills/_archive/).
Active skills (this team)
Maintain this list as we go. Drop a one-line description and the path.
# Personal recommendations (install with marketplace or copy):
# anthropic-skills:consolidate-memory — periodic memory cleanup
# simplify — review changed code for reuse/quality
# fewer-permission-prompts — propose allowlist from transcripts
# review — review a pull request
# security-review — security pass on pending changes
# Team skills (in this repo):
# (none yet — add as we promote workflows)
Planning cadence
We're 1–3 people. Process should be the lightest thing that keeps us aligned. Right now that's:
Weekly
- One short async written sync (Mon morning). Each person posts:
- What I shipped last week (one line per item).
- What I'm picking up this week (one line per item).
- What's blocked or unclear (the only section worth reading carefully).
- 30-minute live call mid-week. Agenda comes from the "blocked or unclear" lines.
Per-task
Before starting work that will take more than ~half a day:
- Write a 5-line spec: Goal / Why / Done when / Out of scope / Risks.
- Drop it in the PR description (draft PR is fine) before writing code.
- If Claude is going to do most of the typing, the spec is also the prompt — paste it in.
After finishing:
- PR description updated to match what actually shipped.
- Anything you learned that future-you would want goes into Claude
memory (feedback / project type) — see
docs/02-claude-code.md.
Per-quarter
One half-day to:
- Re-read this
team-guiderepo. Open PRs for what's stale. - Review the skill catalog. Archive what we don't use.
- Run
consolidate-memoryagainst personal memory files.
Project structure
When starting a new project under this workspace:
- Copy
templates/README.md.templateandtemplates/CLAUDE.md.template. git initimmediately, even if the project is throwaway. Throwaway projects survive longer than you expect.- First commit: scaffolding only, no real code. Makes future
git logreadable. - Add the project to the workspace
README(when we have one) so it's discoverable.
What planning is not
- It's not Jira tickets. We don't need a board for two people.
- It's not Gantt charts. If we need one, we're building the wrong thing.
- It's not status theater. The Monday post is for spotting blocks, not for proving you worked.