Agent-Skills.md

Agent Skills: Octocode Awareness

Use when shared repo work needs awareness before planning, during edits, or after verification: attend/workboard, memory/wiki hygiene, locks/signals, hooks, handoffs, reflection, role-dialogue self-review, or repo context

UncategorizedID: bgauryy/octocode-mcp/octocode-awareness

Repository

bgauryy/octocode-mcp
bgauryyLicense: MIT
88173

Install this agent skill to your local

pnpm dlx add-skill https://github.com/bgauryy/octocode/tree/HEAD/packages/octocode-awareness/skills/octocode-awareness

Skill Files

Browse the full folder contents for octocode-awareness.

Download Skill

Loading file tree…

packages/octocode-awareness/skills/octocode-awareness/SKILL.md

Skill Metadata

Name
octocode-awareness
Description
"Use when shared repo work needs awareness before planning, during edits, or after verification: attend/workboard, memory/wiki hygiene, locks/signals, hooks, handoffs, reflection, role-dialogue self-review, or repo context"

Octocode Awareness

Use for shared-repo awareness (memory, locks, signals, hooks, handoffs, reflection, wiki). Canonical CLI: node scripts/awareness.mjs inside an installed skill, or node packages/octocode-awareness/dist/bin/awareness.js in this monorepo. Use npx @octocodeai/octocode-awareness only when neither local path exists. Below, <cli> means that chosen binary. Canonical store: global ~/.octocode/memory/awareness.sqlite3, scoped by workspace/artifact/repo/ref. <repo>/.octocode/ is generated by repo inject; it is not the DB. First command: <cli> attend --workspace "$PWD" --query "<current task>" --compact; then schema commands --compact and docs list --compact. When you need copy-runnable recipes, read references/agent-cheatsheet.md.

Before / During / After

  • Before: <cli> attend --workspace "$PWD" --query "<task>" --compact; then follow references/agent-cheatsheet.md (status, recall, refinements, signals). For code evidence, load references/octocode.md before running npx octocode search.
  • During: <cli> lock acquire --agent-id "$OCTOCODE_AGENT_ID" --workspace "$PWD" --target-file <path> --rationale "<why>" --test-plan "<verify>" --compact; then lock wait|release, signal publish|reply|ack|resolve, memory record, and agent register|list when coordinating or storing facts.
  • After: <cli> verify audit|mark ...; reflect record|mine-weakness|export-harness ...; session capture ...; repo inject ... when projections should refresh (then root AGENTS.md pointer — Must-Know).
  • Ongoing: <cli> maintenance digest --dry-run ...; lock prune / memory forget --dry-run / signal prune; <cli> docs list --compact then docs show <name>; docs staleness ...; for skill install/update/lint load sibling octocode-skills (bundled next to this skill) or npx octocode skill ....

Must-Know

  • Agents load root AGENTS.md by default. After repo inject, append a short pointer there to .octocode/AGENTS.md if missing — never rewrite the whole file or dump the wiki into root.
  • Recall is lexical FTS + salience by default. --semantic ranks only when OCTOCODE_EMBED_CMD is set; otherwise it warns and stays lexical.
  • Code/GitHub/package search uses npx octocode search ... --no-color (or Octocode MCP) — not a vendored binary in this skill.
  • Prefer operational commands over organ metaphors. Read references/homeostatic-loop.md only when explaining attend/workboard/digest or memory/wiki bloat.
  • Read references/self-reflection-dialogue.md when a hard idea needs role dialogue or multi-agent self-review.
  • Before relying on hooks, read references/hooks.md; Claude may run frontmatter hooks, while Codex/Cursor/Pi need host wiring. Hooks: pre-edit|post-edit|harness-guard|stop-verify|notify-deliver|session-end.

References

  • references/agent-cheatsheet.md — when you need copy-runnable attend → claim → verify → reflect recipes (includes agent/docs commands).
  • references/homeostatic-loop.md — when explaining the awareness organ model, attend, workboards, memory hygiene, or sleep/digest.
  • references/self-reflection-dialogue.md — when using role dialogue to improve ideas without persona or memory bloat.
  • references/full-flow.md — when onboarding or checking the whole CLI/skill/hooks/wiki/reflection loop.
  • references/memory-recall.md — before planning/editing with memories, recall flags, semantic limits, or stale facts.
  • references/coordination-protocol.md — before locking, waiting, releasing, signaling, verifying, or managing refinements.
  • references/files-awareness.md — before editing dirty/concurrent workspaces, reading status, handling collisions, or session capture.
  • references/hooks.md — before installing, checking, tuning, removing, or auditing hooks for Claude/Codex/Cursor/Pi.
  • references/repo-context-management.md — before generating or trusting .octocode/ wiki projections.
  • references/data-model.md — when checking SQLite schema, scoped rows, tasks, locks, signals, or memory refs.
  • references/octocode.md — when code/GitHub/package research is needed via npx octocode search.

Installation / Init Flow

  1. Install: npx octocode skill --add --path "{{path_to_skills_location}}/octocode-awareness" --platform common and the sibling .../octocode-skills (or --name for each). Prefer --platform claude|cursor|codex|pi|all; common → ~/.agents/skills. Update with --force.
  2. Init: <cli> maintenance init --compact; then workspace status, schema commands, and docs list with --compact.
  3. Hooks: preview <cli> hooks install --host codex --project-dir <repo> --dry-run --compact; after approval install + hooks check --host codex --strict --compact (same for cursor/claude).
  4. Agent smoke: <cli> attend --workspace "$PWD" --query "smoke" --compact then workspace status --workspace "$PWD" --compact.
  5. Lint/update skills: load sibling octocode-skills then run its skill-lint script on this folder. Package scripts: scripts/schema.mjs (schemas), scripts/install.mjs --check-only (install check), scripts/smoke-multi-agent.mjs (smoke), scripts/hook-runner.mjs (hook dispatch), scripts/extract-hook-files.mjs (hook file paths), scripts/install-hooks.mjs (legacy hook installer).