Files
praxis/docs/04-skills-and-planning.md
T
阿白叔andClaude Opus 4.7 7f9ca07903 init: scaffold team-guide v0.1
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>
2026-05-20 09:02:21 +08:00

3.8 KiB
Raw Blame History

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:

  1. You've done it the same way three times.
  2. The steps are stable enough to write down.
  3. 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. Not pr-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.md under 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:
    1. What I shipped last week (one line per item).
    2. What I'm picking up this week (one line per item).
    3. 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:

  1. Write a 5-line spec: Goal / Why / Done when / Out of scope / Risks.
  2. Drop it in the PR description (draft PR is fine) before writing code.
  3. If Claude is going to do most of the typing, the spec is also the prompt — paste it in.

After finishing:

  1. PR description updated to match what actually shipped.
  2. 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-guide repo. Open PRs for what's stale.
  • Review the skill catalog. Archive what we don't use.
  • Run consolidate-memory against personal memory files.

Project structure

When starting a new project under this workspace:

  1. Copy templates/README.md.template and templates/CLAUDE.md.template.
  2. git init immediately, even if the project is throwaway. Throwaway projects survive longer than you expect.
  3. First commit: scaffolding only, no real code. Makes future git log readable.
  4. 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.