SuperAPI AI Directory
Partner with us中文AI newsFavorites
Skillspocket-init

pocket-init

Writing & research

View repository

Updated 10-16 07:59

About this skill

Pocket Init

Standalone local onboarding. Takes an existing project from zero Pocket context to a useful project guide that the agent can rely on, and optionally enables Pocket Education with a persisted learner profile.

Core principle: Read the project, never guess it. Every claim written to the memory file must come from files actually inspected in this run. User content in an existing memory file is never overwritten.

Use this when: Adopting Pocket in an existing repo, regenerating a stale project guide, or enabling Pocket Education for a learner.

Do NOT use when: The project already has a current memory file and the learner profile it wants. To change learner levels later, use pocket-education (it never needs a re-init). For spec work, go to pocket-grinding.

Invocation

/pocketto:pocket-init [<dir>]

<dir> defaults to the repository root of the current working directory.

Hard Constraints

Step 1: Brownfield scan (read-only)

Inspect the project before writing anything:

  1. Stack & manifests — package.json, pyproject.toml, Cargo.toml, go.mod, pom.xml, or equivalent: language, package manager, declared scripts.
  2. Commands — extract build / test / lint / typecheck commands from manifest scripts, project config, or local CI workflow files. Record each command verbatim with its source. If a command is not declared in the inspected files, write Not configured rather than guessing.
  3. Layout — top-level directories and what lives in each (source, tests, docs, tooling). Keep it to the directories that matter.
  4. Conventions — formatter/linter configs, test file naming, and commit style visible in git log --oneline -10.
  5. Existing memory files — check for CLAUDE.md and AGENTS.md. Note which exist and whether they already contain a pocket-init managed section or a ## Pocket Education heading.

Briefly report the findings, then continue to Step 2 and write the guide. Do not wait for confirmation unless Step 2 cannot determine which memory file to use. The Education Gate in Step 4 controls only whether to create or resume an Education profile; declining it does not cancel the requested project guide.

Step 2: Pick the memory file

Detect the platform and choose the target:

  • Running as a Claude Code plugin/skill → CLAUDE.md.
  • Running under Pi → AGENTS.md.
  • If both files exist, use the file for the active platform and leave the other untouched. Ask the user only when the active platform or authoritative file is genuinely unclear, or when they request a specific target. Never write both.

Record the choice as <memory_file>.

Step 3: Write the managed section

Compose the project guide from Step 1 findings:

<!-- pocket-init:start -->
## Project Guide (generated by pocket-init)

### Stack
…

### Commands
- Build: `<verified command | Not configured>`
- Test: `<verified command | Not configured>`
- Lint: `<verified command | Not configured>`
- Typecheck: `<verified command | Not configured>`

### Layout
…

### Conventions
…
<!-- pocket-init:end -->

Merge rules:

  • File missing → create it with the managed section as its content.
  • File exists with no marker tokens → append the managed section at the end, preceded by one blank line.
  • File exists with exactly one complete marker pair → replace only the managed section, preserving all bytes outside it.
  • Any marker token is present, but there is not exactly one complete, correctly ordered pair → do not write. Report the malformed section and ask how the user wants it repaired; do not guess which content is managed.

Keep the section under ~60 lines — a memory file is an index, not documentation.

The ## Pocket Education block lives outside the managed section and is owned by edu. Regenerating the project guide never touches it and never resets a learner's calibration. Other user-owned configuration blocks also remain untouched.

Step 4: Education Gate (opt-in)

Check current state first:

npx -y pocketto-pi edu --json --contract 3
  • data.education is true → a learner profile exists. Report it and do not recalibrate (only an explicit learner request triggers pocket-education's recalibration). Skip to Step 5.
  • data.source set but data.education is false → a paused profile exists. Ask whether to resume it (edu set --education true); do not recalibrate. Skip to Step 5.
  • An error (EDU_CONFIG_INVALID, EDU_SCHEMA_UNSUPPORTED) → report it; do not overwrite the block. Skip to Step 5.

Otherwise ask the user one question:

"Enable Pocket Education for this repo? It keeps implementation human-owned — the agent explains, reviews, and guides while you write the code — and stores a learner profile so guidance adapts across sessions. (yes/no)"

If no → skip to Step 5. Keep the project guide written in Step 3; do not create or change an Education profile.

If yes:

  1. Run the lightweight calibration in <skills_root>/pocket-education/references/calibration.md, using the Step 1 scan to choose the stack skills. It is onboarding, not an exam.
  2. Show the proposed profile; the learner confirms or edits every level.
  3. Write it to the same memory file: 
    npx -y pocketto-pi edu init --file <memory_file> --level <skill>=<level> [--level ...] [--teaching-mode socratic] [--journal false] --json --contract 3
  4. Re-run edu --json --contract 3 and confirm education=true before continuing.

Education makes no remote call and does not change optional adapter behavior.

Step 5: Completion report

POCKET_INIT_COMPLETE
Memory file : <memory_file> (created | merged)
Education   : enabled (<n> skills, teaching_mode=<mode>, journal=<on|off>) | reused existing profile | disabled
Next        : /pocketto:pocket-grinding "<your first feature>"
              (Education on → /pocketto:pocket-education "<your first task>")

Red Flags

Thought Counter
"The memory file is messy — I'll rewrite it" STOP. Only the managed section is yours. Everything else is user content.
"It's a Node project, tests are probably npm test" Read the manifest. Write only commands that actually exist.
"I'll run a remote setup command while onboarding" STOP. This skill performs local inspection and writes only the managed guide section and, with explicit consent, the local learner profile.
"I'll write both CLAUDE.md and AGENTS.md to be safe" One memory file per project. Two copies drift apart.
"They're a beginner — I'll enable Education for them" STOP. Education is opt-in at the gate.
"A profile exists, but a fresh calibration would be more accurate" Reuse it. Recalibration is the learner's call, not yours.
"Their answers say testing is guided — I'll write that without asking" Show the proposal. The learner confirms every level.