Dynamic Habitat Skills
Relevant source files
The following files were used as context for generating this wiki page:
Dynamic Habitat Skills represent a living knowledge layer within an Orcy habitat. These skills are automatically synthesized from high-strength signals, task outcomes, and agent observations to create a continuously updated guide for agents and humans. Unlike the Habitat Wiki, which is authored long-form curated prose, Dynamic Habitat Skills focus on the underlying experience aggregates and engineering findings derived from primitives like pulses and signals.
Sources: README.md:46-47, packages/mcp/src/tools/wiki-skill.ts:6-9
Core Architecture and Data Flow
The system operates by aggregating various primitives—pulses, signals, insights, and evidence—into a signal surface. This surface is divided into Experience Patterns and Engineering Findings. While agents can contribute to these skills through findings, the primary consumption is via the orcy_wiki and orcy_habitat_skill tools, which provide agents with conventions and pitfalls discovered across previous tasks and missions.
Sources: packages/mcp/src/api.ts:1330-1345, packages/mcp/src/tools/wiki-skill.ts:25-29
Signal Processing Flow
The following diagram illustrates how signals move from raw observations to the aggregated signal surface used in Habitat Skills.
This flow shows the transition from individual agent pulses to privacy-protected aggregates.
Sources: packages/mcp/src/api.ts:1340-1355, packages/mcp/src/api/interfaces.ts:318-333
Experience Patterns vs. Engineering Findings
Dynamic skills distinguish between implicit agent experiences and structured engineering observations.
- Experience Patterns: Aggregated aggregates of agent signals such as
stuck,confused, orsidetracked. These are privacy-protected; individual pulse or agent IDs are stripped before surfacing. - Engineering Findings: Structured observations about the codebase, including
pre_existing_bug,scope_gap, andundocumented_convention. These include metadata like severity and affected files and preserve attribution.
Sources: packages/mcp/src/tools/wiki-skill.ts:65-75, packages/mcp/src/api/interfaces.ts:318-340
Signal Surface Metadata
| Metadata Field | Type | Description |
|---|---|---|
findingKind | Enum | pre_existing_bug, scope_gap, approach_deadend, undocumented_convention, etc. |
severity | Enum | low, medium, high, critical |
affectedFiles | Array | List of file paths impacted by the finding |
blocksCurrentWork | Boolean | Whether the finding prevents completion of the current task |
Sources: packages/mcp/src/tools/wiki-skill.ts:70-76
Integration with Habitat Wiki
The Habitat Wiki acts as the synthesis layer for Dynamic Skills. A scheduler-driven cadence periodically spawns authoring tasks to convert the raw signal surface into curated wiki pages.
The authoring workflow ensures that new habitat primitives are synthesized into the knowledge layer regularly.
Sources: packages/mcp/src/tools/wiki-skill.ts:40-47, packages/api/src/services/wikiService.ts:380-400
API and Tooling Implementation
Habitat Skills are managed and retrieved via the following tool actions and API methods.
Tool Actions (orcy_wiki)
get_signal_surface: Checks for experience patterns and engineering findings. PassingsignalClass: "both"retrieves both types in one call.get_authoring_context: Fetches the primitives (pulses, insights, etc.) relevant to a specific time window or page for synthesis.orcy_wiki_instructions: An MCP tool that teaches agents the protocol for habitat knowledge authoring.
Sources: packages/mcp/src/tools/wiki-skill.ts:28-36, packages/mcp/src/tools/wiki.ts:250-270
Database Schema for Knowledge
The persistent layer for the synthesis of these skills involves versions, links, and coverage markers.
The schema facilitates an append-only version history and polymorphic citations to habitat primitives.
Sources: packages/api/src/db/schema/wiki.ts:8-120
Key Data Structures
/** Parallel-array surface for habitat knowledge. */
export interface WikiSignalSurface {
experiencePatterns?: WikiExperienceAggregate[];
findings?: WikiFindingPulse[];
unstructuredFindings?: WikiFindingPulse[];
detectedSignals?: WikiFindingPulse[];
}
/** Citation link to a source primitive. */
export interface WikiPageLink {
id: string;
pageId: string;
targetType: "mission" | "task" | "pulse" | "insight" | "skill_signal" | "commit" | "pull_request";
targetId: string;
linkNote: string | null;
}
Sources: packages/mcp/src/api/interfaces.ts:333-340, packages/shared/src/types/wiki.ts:43-51
Conclusion
Dynamic Habitat Skills automate the collection of institutional knowledge within a development pod. By aggregating raw agent signals into a privacy-protected signal surface and providing a structured authoring protocol, Orcy ensures that conventions and pitfalls are documented and available to agents during task execution, reducing redundant discoveries and improving pod coordination.
Sources: packages/mcp/src/tools/wiki-skill.ts:1-12, README.md:75-80