SkillNote boundary

Type: agentic-system-analyses/types/agentic-system-boundary.md

Boundary and evidence

SkillNote is in scope as a memory/knowledge/context-engineering system: it retains reusable procedural instructions and serves them to model-driven agents. Its intended use is a self-hosted skill registry, not an enclosing agent runtime. The target includes the registry and its shipped consumers, not just its REST or MCP interface. SRC-1, README.md, declares:

Self-host your team's SKILL.md library. Version it, scope it, and ship it to Claude Code and OpenClaw from one CLI. --- README.md

The whole-system boundary includes the web authoring interface and browser-local state, backend admission and version storage, imports and upstream refresh/publishing, collection scoping, CLI installation and update, Claude Code/Codex hooks, OpenClaw skill instructions and watcher, MCP delivery, claude.ai browser connector, analytics, ratings and comments. These are shipped parts of the same state loop, even where the final skill is consumed in an external agent. The boundary includes model-facing maintenance instructions as system behavior contracts, not instructions for this analysis.

Initial tracing establishes the major loop surfaces:

• Produce and persist: the web store calls skill creation/update APIs; backend creation and edits write skill content and content versions. The import service also admits retained content, while ZIP publishing and bundle storage provide another admission path. SRC-1, src/lib/skills-store.ts, backend/app/api/skills.py, backend/app/services/imports/importer.py, backend/app/api/publish.py, backend/app/services/storage_service.py.
• Agent-assisted maintenance: skill-push instructs an agent to draft, review and POST/PATCH reusable procedures, with a confirmation gate. It is not merely documentation of a library API. SRC-1, plugin/skills/skill-push/SKILL.md:

Stop and wait for an explicit yes. Do NOT draft the name/description/content, fetch collections, or present a preview until the user confirms. Unsolicited drafts feel pushy and waste attention. --- plugin/skills/skill-push/SKILL.md

• Reload and consume: the Claude Code plugin fetches collection-filtered content and writes project skills and a manifest. The Codex plugin has its own hook-driven sync path. CLI add installs bundles through agent adapters and records a manifest; it is included alongside plugin sync rather than treated as an external caller. SRC-1, plugin/hooks-handlers/sync.sh, plugin/hooks/hooks.json, plugin-codex/hooks/hooks.json, plugin-codex/hooks/handlers/sync.sh, cli/src/commands/add.ts. The Claude Code sync implementation includes:

with open(filepath, 'w') as f: f.write(content) --- plugin/hooks-handlers/sync.sh

• Model-facing retrieval: MCP builds tools from retained skill rows and returns their instruction text. The enclosing model's choice to apply those instructions is outside the implementation boundary. SRC-1, backend/mcp_server.py:

content = f"# {self.skill_name}\n\n{self.content_md}" --- backend/mcp_server.py

• Later use and feedback: OpenClaw's shipped skill and generated sidecar instruct sync, selection, use, usage logging and conditional ratings. Claude Code hooks and complete-skill instructions report usage or ratings. The claude.ai connector polls operations, uploads groups, retires deselected groups, and imports remote-authored skills. SRC-1, plugin-openclaw/skillnote/SKILL.md, plugin-openclaw/skillnote/sync.sh, plugin-openclaw/skillnote/log-watcher.py, plugin/skills/complete-skill/SKILL.md, backend/app/api/hooks.py, extensions/claude-ai/src/background.ts, backend/app/services/claude_ai_sync.py. These surfaces permit investigation of feedback collection; they do not by themselves establish improved task performance.

The immutable evidence boundary is SRC-1 at 7ea2fc7a8435af64d1c080d8765c0eabba1121ea. HEAD was checked against the acquired pin. The applicability cutoff is 2026-10-14, the supplied run date; this is not a claim about the date of the last successful deployment. The overall tier is code-grounded, with source-native documentation as doctrine/design evidence. No target code, tests or examples were executed, and no services were contacted.

Repository coverage

Every top-level tracked entry is classified below. “Included” sets the functional boundary, not a claim that every file has been audited. Initial inspection combines tree inventory, targeted symbol searches and source reads. Unread files in included directories remain available at the registered commit; they are not access gaps. Tests were inventoried and representative test source inspected, not run.

External dependencies and limits

The shipped stack depends on Postgres, Python/FastAPI/FastMCP, Node/Next.js, browser extension APIs and local shell/Python/curl tooling. Their implementations are not separate registered sources. Source wiring is visible in SRC-1, docker-compose.yml, backend/app/main.py, backend/mcp_server.py, cli/package.json, extensions/claude-ai/src/background.ts.

Claude Code, Codex, OpenClaw and claude.ai itself are excluded external hosts. Their model calls, skill discovery semantics, context limits and compliance with returned instructions are not established by this checkout. The shipped adapters, hooks, prompts and connector are included; responsibilities of the external hosts are not attributed to SkillNote. Remote Git repositories used as skill origins, npm/Homebrew archives, GHCR images and third-party dependencies are not captured. This prevents claims about their contents or compatibility beyond the source-declared interfaces. No deployed database, actual user skill corpus, host transcript or measured intervention is supplied. This prevents claims of successful end-to-end operation, reliable rating behavior, learning effectiveness or causal task improvement. These are evidence limits, not inaccessible material shipped code paths, and do not require a partial-loop boundary.

Source register