@stephen-lord/docs 1.0.0 → 1.0.1

package/dist-docs/Agent-Skills-for-Context-Engineering/.claude-plugin/marketplace.json

@@ -0,0 +1,68 @@
+{
+  "name": "context-engineering-marketplace",
+  "owner": {
+    "name": "Muratcan Koylan",
+    "email": "muratcan.koylan@outlook.com"
+  },
+  "metadata": {
+    "description": "Context Engineering skills for building production-grade AI agent systems",
+    "version": "1.0.0"
+  },
+  "plugins": [
+    {
+      "name": "context-engineering-fundamentals",
+      "description": "Core context engineering skills covering fundamentals, degradation patterns, compression strategies, and optimization techniques for AI agent systems",
+      "source": "./",
+      "strict": false,
+      "skills": [
+        "./skills/context-fundamentals",
+        "./skills/context-degradation",
+        "./skills/context-compression",
+        "./skills/context-optimization"
+      ]
+    },
+    {
+      "name": "agent-architecture",
+      "description": "Multi-agent patterns, memory systems, tool design, filesystem-based context, and hosted agent infrastructure for building production AI agent architectures",
+      "source": "./",
+      "strict": false,
+      "skills": [
+        "./skills/multi-agent-patterns",
+        "./skills/memory-systems",
+        "./skills/tool-design",
+        "./skills/filesystem-context",
+        "./skills/hosted-agents"
+      ]
+    },
+    {
+      "name": "agent-evaluation",
+      "description": "Evaluation frameworks and LLM-as-judge techniques for testing and validating AI agent systems",
+      "source": "./",
+      "strict": false,
+      "skills": [
+        "./skills/evaluation",
+        "./skills/advanced-evaluation"
+      ]
+    },
+    {
+      "name": "agent-development",
+      "description": "Project development methodology for LLM-powered applications including pipeline architecture and batch processing",
+      "source": "./",
+      "strict": false,
+      "skills": [
+        "./skills/project-development"
+      ]
+    },
+    {
+      "name": "cognitive-architecture",
+      "description": "BDI mental state modeling and cognitive architecture patterns for building rational agents with formal belief-desire-intention representations",
+      "source": "./",
+      "strict": false,
+      "skills": [
+        "./skills/bdi-mental-states"
+      ]
+    }
+  ]
+}
+
+

package/dist-docs/Agent-Skills-for-Context-Engineering/.cursorindexingignore

@@ -0,0 +1,3 @@
+
+# Don't index SpecStory auto-save files, but allow explicit context inclusion via @ references
+.specstory/**

package/dist-docs/Agent-Skills-for-Context-Engineering/CONTRIBUTING.md

@@ -0,0 +1,78 @@
+# Contributing to Agent Skills for Context Engineering
+
+Thank you for your interest in contributing to this collection of Agent Skills for Context Engineering. This document provides guidelines and instructions for contributing.
+
+## How to Contribute
+
+### Reporting Issues
+
+If you find errors, unclear explanations, or missing topics, please open an issue with:
+- A clear description of the problem
+- The skill and section where the issue was found
+- Suggested improvements if you have them
+
+### Submitting Changes
+
+For substantive changes, please:
+
+1. Fork the repository
+2. Create a feature branch for your changes
+3. Make changes following the skill template structure
+4. Ensure SKILL.md files remain under 500 lines
+5. Add references or scripts as appropriate
+6. Submit a pull request with a clear description of changes
+
+### Adding New Skills
+
+When adding new skills:
+
+1. Use the template in `template/SKILL.md`
+2. Follow naming conventions (lowercase with hyphens)
+3. Include both SKILL.md and appropriate references/scripts
+4. Update the root README.md to include the new skill
+5. Ensure content is platform-agnostic (works across Cursor, Claude Code, etc.)
+
+## Skill Structure Requirements
+
+Each skill must include:
+
+- YAML frontmatter with `name` and `description` fields
+- Clear sections with logical organization
+- Practical examples where appropriate
+- Integration notes linking to related skills
+
+Optional additions:
+
+- `references/` directory with additional documentation
+- `scripts/` directory with executable examples
+- Multiple markdown files for complex skills
+
+## Content Guidelines
+
+### Writing Style
+
+- Be direct and precise
+- Use technical terminology appropriately
+- Include specific guidance, not vague recommendations
+- Provide concrete examples
+- Point out complexity and trade-offs
+
+### Avoiding Platform Specificity
+
+Skills should work across agent platforms. Avoid:
+- Platform-specific tool names without abstraction
+- Vendor-locked examples
+- Features specific to one agent product
+
+### Keeping Skills Focused
+
+Each skill should have a single focus. If a topic grows too large, consider splitting into multiple skills with clear dependencies.
+
+## Code of Conduct
+
+This project follows a professional, technical collaboration model. Be respectful of different perspectives and focus on improving the collective knowledge base.
+
+## Questions
+
+For questions about contributing, please open an issue for discussion.
+

package/dist-docs/Agent-Skills-for-Context-Engineering/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2025 Context Engineering Agent Skills Contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+

package/dist-docs/Agent-Skills-for-Context-Engineering/README.md

@@ -0,0 +1,228 @@
+# Agent Skills for Context Engineering
+
+A comprehensive, open collection of Agent Skills focused on context engineering principles for building production-grade AI agent systems. These skills teach the art and science of curating context to maximize agent effectiveness across any agent platform.
+
+## What is Context Engineering?
+
+Context engineering is the discipline of managing the language model's context window. Unlike prompt engineering, which focuses on crafting effective instructions, context engineering addresses the holistic curation of all information that enters the model's limited attention budget: system prompts, tool definitions, retrieved documents, message history, and tool outputs.
+
+The fundamental challenge is that context windows are constrained not by raw token capacity but by attention mechanics. As context length increases, models exhibit predictable degradation patterns: the "lost-in-the-middle" phenomenon, U-shaped attention curves, and attention scarcity. Effective context engineering means finding the smallest possible set of high-signal tokens that maximize the likelihood of desired outcomes.
+
+## Skills Overview
+
+### Foundational Skills
+
+These skills establish the foundational understanding required for all subsequent context engineering work.
+
+| Skill | Description |
+|-------|-------------|
+| [context-fundamentals](skills/context-fundamentals/) | Understand what context is, why it matters, and the anatomy of context in agent systems |
+| [context-degradation](skills/context-degradation/) | Recognize patterns of context failure: lost-in-middle, poisoning, distraction, and clash |
+| [context-compression](skills/context-compression/) | Design and evaluate compression strategies for long-running sessions |
+
+### Architectural Skills
+
+These skills cover the patterns and structures for building effective agent systems.
+
+| Skill | Description |
+|-------|-------------|
+| [multi-agent-patterns](skills/multi-agent-patterns/) | Master orchestrator, peer-to-peer, and hierarchical multi-agent architectures |
+| [memory-systems](skills/memory-systems/) | Design short-term, long-term, and graph-based memory architectures |
+| [tool-design](skills/tool-design/) | Build tools that agents can use effectively |
+| [filesystem-context](skills/filesystem-context/) | Use filesystems for dynamic context discovery, tool output offloading, and plan persistence |
+| [hosted-agents](skills/hosted-agents/) | **NEW** Build background coding agents with sandboxed VMs, pre-built images, multiplayer support, and multi-client interfaces |
+
+### Operational Skills
+
+These skills address the ongoing operation and optimization of agent systems.
+
+| Skill | Description |
+|-------|-------------|
+| [context-optimization](skills/context-optimization/) | Apply compaction, masking, and caching strategies |
+| [evaluation](skills/evaluation/) | Build evaluation frameworks for agent systems |
+| [advanced-evaluation](skills/advanced-evaluation/) | Master LLM-as-a-Judge techniques: direct scoring, pairwise comparison, rubric generation, and bias mitigation |
+
+### Development Methodology
+
+These skills cover the meta-level practices for building LLM-powered projects.
+
+| Skill | Description |
+|-------|-------------|
+| [project-development](skills/project-development/) | Design and build LLM projects from ideation through deployment, including task-model fit analysis, pipeline architecture, and structured output design |
+
+### Cognitive Architecture Skills
+
+These skills cover formal cognitive modeling for rational agent systems.
+
+| Skill | Description |
+|-------|-------------|
+| [bdi-mental-states](skills/bdi-mental-states/) | **NEW** Transform external RDF context into agent mental states (beliefs, desires, intentions) using formal BDI ontology patterns for deliberative reasoning and explainability |
+
+## Design Philosophy
+
+### Progressive Disclosure
+
+Each skill is structured for efficient context use. At startup, agents load only skill names and descriptions. Full content loads only when a skill is activated for relevant tasks.
+
+### Platform Agnosticism
+
+These skills focus on transferable principles rather than vendor-specific implementations. The patterns work across Claude Code, Cursor, and any agent platform that supports skills or allows custom instructions.
+
+### Conceptual Foundation with Practical Examples
+
+Scripts and examples demonstrate concepts using Python pseudocode that works across environments without requiring specific dependency installations.
+
+## Usage
+
+### Usage with Claude Code
+
+This repository is a **Claude Code Plugin Marketplace** containing context engineering skills that Claude automatically discovers and activates based on your task context.
+
+### Installation
+
+**Step 1: Add the Marketplace**
+
+Run this command in Claude Code to register this repository as a plugin source:
+
+```
+/plugin marketplace add muratcankoylan/Agent-Skills-for-Context-Engineering
+```
+
+**Step 2: Browse and Install**
+
+Option A - Browse available plugins:
+1. Select `Browse and install plugins`
+2. Select `context-engineering-marketplace`
+3. Choose a plugin (e.g., `context-engineering-fundamentals`, `agent-architecture`)
+4. Select `Install now`
+
+Option B - Direct install via command:
+
+```
+/plugin install context-engineering-fundamentals@context-engineering-marketplace
+/plugin install agent-architecture@context-engineering-marketplace
+/plugin install agent-evaluation@context-engineering-marketplace
+/plugin install agent-development@context-engineering-marketplace
+/plugin install cognitive-architecture@context-engineering-marketplace
+```
+
+### Available Plugins
+
+| Plugin | Skills Included |
+|--------|-----------------|
+| `context-engineering-fundamentals` | context-fundamentals, context-degradation, context-compression, context-optimization |
+| `agent-architecture` | multi-agent-patterns, memory-systems, tool-design, filesystem-context, hosted-agents |
+| `agent-evaluation` | evaluation, advanced-evaluation |
+| `agent-development` | project-development |
+| `cognitive-architecture` | bdi-mental-states |
+
+### Skill Triggers
+
+| Skill | Triggers On |
+|-------|-------------|
+| `context-fundamentals` | "understand context", "explain context windows", "design agent architecture" |
+| `context-degradation` | "diagnose context problems", "fix lost-in-middle", "debug agent failures" |
+| `context-compression` | "compress context", "summarize conversation", "reduce token usage" |
+| `context-optimization` | "optimize context", "reduce token costs", "implement KV-cache" |
+| `multi-agent-patterns` | "design multi-agent system", "implement supervisor pattern" |
+| `memory-systems` | "implement agent memory", "build knowledge graph", "track entities" |
+| `tool-design` | "design agent tools", "reduce tool complexity", "implement MCP tools" |
+| `filesystem-context` | "offload context to files", "dynamic context discovery", "agent scratch pad", "file-based context" |
+| `hosted-agents` | "build background agent", "create hosted coding agent", "sandboxed execution", "multiplayer agent", "Modal sandboxes" |
+| `evaluation` | "evaluate agent performance", "build test framework", "measure quality" |
+| `advanced-evaluation` | "implement LLM-as-judge", "compare model outputs", "mitigate bias" |
+| `project-development` | "start LLM project", "design batch pipeline", "evaluate task-model fit" |
+| `bdi-mental-states` | "model agent mental states", "implement BDI architecture", "transform RDF to beliefs", "build cognitive agent" |
+
+<img width="1014" height="894" alt="Screenshot 2025-12-26 at 12 34 47 PM" src="https://github.com/user-attachments/assets/f79aaf03-fd2d-4c71-a630-7027adeb9bfe" />
+
+### For Cursor & Codex & IDE
+
+Copy skill content into `.rules` or create project-specific Skills folders. The skills provide the context and guidelines that agent needs for effective context engineering and agent design.
+
+### For Custom Implementations
+
+Extract the principles and patterns from any skill and implement them in your agent framework. The skills are deliberately platform-agnostic.
+
+## Examples
+
+The [examples](examples/) folder contains complete system designs that demonstrate how multiple skills work together in practice.
+
+| Example | Description | Skills Applied |
+|---------|-------------|----------------|
+| [digital-brain-skill](examples/digital-brain-skill/) | **NEW** Personal operating system for founders and creators. Complete Claude Code skill with 6 modules, 4 automation scripts | context-fundamentals, context-optimization, memory-systems, tool-design, multi-agent-patterns, evaluation, project-development |
+| [x-to-book-system](examples/x-to-book-system/) | Multi-agent system that monitors X accounts and generates daily synthesized books | multi-agent-patterns, memory-systems, context-optimization, tool-design, evaluation |
+| [llm-as-judge-skills](examples/llm-as-judge-skills/) | Production-ready LLM evaluation tools with TypeScript implementation, 19 passing tests | advanced-evaluation, tool-design, context-fundamentals, evaluation |
+| [book-sft-pipeline](examples/book-sft-pipeline/) | Train models to write in any author's style. Includes Gertrude Stein case study with 70% human score on Pangram, $2 total cost | project-development, context-compression, multi-agent-patterns, evaluation |
+
+Each example includes:
+- Complete PRD with architecture decisions
+- Skills mapping showing which concepts informed each decision
+- Implementation guidance
+
+### Digital Brain Skill Example
+
+The [digital-brain-skill](examples/digital-brain-skill/) example is a complete personal operating system demonstrating comprehensive skills application:
+
+- **Progressive Disclosure**: 3-level loading (SKILL.md → MODULE.md → data files)
+- **Module Isolation**: 6 independent modules (identity, content, knowledge, network, operations, agents)
+- **Append-Only Memory**: JSONL files with schema-first lines for agent-friendly parsing
+- **Automation Scripts**: 4 consolidated tools (weekly_review, content_ideas, stale_contacts, idea_to_draft)
+
+Includes detailed traceability in [HOW-SKILLS-BUILT-THIS.md](examples/digital-brain-skill/HOW-SKILLS-BUILT-THIS.md) mapping every architectural decision to specific skill principles.
+
+### LLM-as-Judge Skills Example
+
+The [llm-as-judge-skills](examples/llm-as-judge-skills/) example is a complete TypeScript implementation demonstrating:
+
+- **Direct Scoring**: Evaluate responses against weighted criteria with rubric support
+- **Pairwise Comparison**: Compare responses with position bias mitigation
+- **Rubric Generation**: Create domain-specific evaluation standards
+- **EvaluatorAgent**: High-level agent combining all evaluation capabilities
+
+### Book SFT Pipeline Example
+
+The [book-sft-pipeline](examples/book-sft-pipeline/) example demonstrates training small models (8B) to write in any author's style:
+
+- **Intelligent Segmentation**: Two-tier chunking with overlap for maximum training examples
+- **Prompt Diversity**: 15+ templates to prevent memorization and force style learning
+- **Tinker Integration**: Complete LoRA training workflow with $2 total cost
+- **Validation Methodology**: Modern scenario testing proves style transfer vs content memorization
+
+Integrates with context engineering skills: project-development, context-compression, multi-agent-patterns, evaluation.
+
+## Star History
+<img width="3664" height="2648" alt="star-history-2026113" src="https://github.com/user-attachments/assets/c60fd73f-4a6c-4679-b7c6-bb8ebf2f3a48" />
+
+## Structure
+
+Each skill follows the Agent Skills specification:
+
+```
+skill-name/
+├── SKILL.md              # Required: instructions + metadata
+├── scripts/              # Optional: executable code demonstrating concepts
+└── references/           # Optional: additional documentation and resources
+```
+
+See the [template](template/) folder for the canonical skill structure.
+
+## Contributing
+
+This repository follows the Agent Skills open development model. Contributions are welcome from the broader ecosystem. When contributing:
+
+1. Follow the skill template structure
+2. Provide clear, actionable instructions
+3. Include working examples where appropriate
+4. Document trade-offs and potential issues
+5. Keep SKILL.md under 500 lines for optimal performance
+
+Feel free to contact [Muratcan Koylan](https://x.com/koylanai) for collaboration opportunities or any inquiries.
+
+## License
+
+MIT License - see LICENSE file for details.
+
+## References
+
+The principles in these skills are derived from research and production experience at leading AI labs and framework developers. Each skill includes references to the underlying research and case studies that inform its recommendations.

package/dist-docs/Agent-Skills-for-Context-Engineering/SKILL.md

@@ -0,0 +1,104 @@
+---
+name: context-engineering-collection
+description: A comprehensive collection of Agent Skills for context engineering, multi-agent architectures, and production agent systems. Use when building, optimizing, or debugging agent systems that require effective context management.
+---
+
+# Agent Skills for Context Engineering
+
+This collection provides structured guidance for building production-grade AI agent systems through effective context engineering.
+
+## When to Activate
+
+Activate these skills when:
+- Building new agent systems from scratch
+- Optimizing existing agent performance
+- Debugging context-related failures
+- Designing multi-agent architectures
+- Creating or evaluating tools for agents
+- Implementing memory and persistence layers
+
+## Skill Map
+
+### Foundational Context Engineering
+
+**Understanding Context Fundamentals**
+Context is not just prompt text—it is the complete state available to the language model at inference time, including system instructions, tool definitions, retrieved documents, message history, and tool outputs. Effective context engineering means understanding what information truly matters for the task at hand and curating that information for maximum signal-to-noise ratio.
+
+**Recognizing Context Degradation**
+Language models exhibit predictable degradation patterns as context grows: the "lost-in-middle" phenomenon where information in the center of context receives less attention; U-shaped attention curves that prioritize beginning and end; context poisoning when errors compound; and context distraction when irrelevant information overwhelms relevant content.
+
+### Architectural Patterns
+
+**Multi-Agent Coordination**
+Production multi-agent systems converge on three dominant patterns: supervisor/orchestrator architectures with centralized control, peer-to-peer swarm architectures for flexible handoffs, and hierarchical structures for complex task decomposition. The critical insight is that sub-agents exist primarily to isolate context rather than to simulate organizational roles.
+
+**Memory System Design**
+Memory architectures range from simple scratchpads to sophisticated temporal knowledge graphs. Vector RAG provides semantic retrieval but loses relationship information. Knowledge graphs preserve structure but require more engineering investment. The file-system-as-memory pattern enables just-in-time context loading without stuffing context windows.
+
+**Filesystem-Based Context**
+The filesystem provides a single interface for storing, retrieving, and updating effectively unlimited context. Key patterns include scratch pads for tool output offloading, plan persistence for long-horizon tasks, sub-agent communication via shared files, and dynamic skill loading. Agents use `ls`, `glob`, `grep`, and `read_file` for targeted context discovery, often outperforming semantic search for structural queries.
+
+**Hosted Agent Infrastructure**
+Background coding agents run in remote sandboxed environments rather than on local machines. Key patterns include pre-built environment images refreshed on regular cadence, warm sandbox pools for instant session starts, filesystem snapshots for session persistence, and multiplayer support for collaborative agent sessions. Critical optimizations include allowing file reads before git sync completes (blocking only writes), predictive sandbox warming when users start typing, and self-spawning agents for parallel task execution.
+
+**Tool Design Principles**
+Tools are contracts between deterministic systems and non-deterministic agents. Effective tool design follows the consolidation principle (prefer single comprehensive tools over multiple narrow ones), returns contextual information in errors, supports response format options for token efficiency, and uses clear namespacing.
+
+### Operational Excellence
+
+**Context Compression**
+When agent sessions exhaust memory, compression becomes mandatory. The correct optimization target is tokens-per-task, not tokens-per-request. Structured summarization with explicit sections for files, decisions, and next steps preserves more useful information than aggressive compression. Artifact trail integrity remains the weakest dimension across all compression methods.
+
+**Context Optimization**
+Techniques include compaction (summarizing context near limits), observation masking (replacing verbose tool outputs with references), prefix caching (reusing KV blocks across requests), and strategic context partitioning (splitting work across sub-agents with isolated contexts).
+
+**Evaluation Frameworks**
+Production agent evaluation requires multi-dimensional rubrics covering factual accuracy, completeness, tool efficiency, and process quality. Effective patterns include LLM-as-judge for scalability, human evaluation for edge cases, and end-state evaluation for agents that mutate persistent state.
+
+### Development Methodology
+
+**Project Development**
+Effective LLM project development begins with task-model fit analysis: validating through manual prototyping that a task is well-suited for LLM processing before building automation. Production pipelines follow staged, idempotent architectures (acquire, prepare, process, parse, render) with file system state management for debugging and caching. Structured output design with explicit format specifications enables reliable parsing. Start with minimal architecture and add complexity only when proven necessary.
+
+## Core Concepts
+
+The collection is organized around three core themes. First, context fundamentals establish what context is, how attention mechanisms work, and why context quality matters more than quantity. Second, architectural patterns cover the structures and coordination mechanisms that enable effective agent systems. Third, operational excellence addresses the ongoing work of optimizing and evaluating production systems.
+
+## Practical Guidance
+
+Each skill can be used independently or in combination. Start with fundamentals to establish context management mental models. Branch into architectural patterns based on your system requirements. Reference operational skills when optimizing production systems.
+
+The skills are platform-agnostic and work with Claude Code, Cursor, or any agent framework that supports custom instructions or skill-like constructs.
+
+## Integration
+
+This collection integrates with itself—skills reference each other and build on shared concepts. The fundamentals skill provides context for all other skills. Architectural skills (multi-agent, memory, tools) can be combined for complex systems. Operational skills (optimization, evaluation) apply to any system built using the foundational and architectural skills.
+
+## References
+
+Internal skills in this collection:
+- [context-fundamentals](skills/context-fundamentals/SKILL.md)
+- [context-degradation](skills/context-degradation/SKILL.md)
+- [context-compression](skills/context-compression/SKILL.md)
+- [multi-agent-patterns](skills/multi-agent-patterns/SKILL.md)
+- [memory-systems](skills/memory-systems/SKILL.md)
+- [tool-design](skills/tool-design/SKILL.md)
+- [filesystem-context](skills/filesystem-context/SKILL.md)
+- [hosted-agents](skills/hosted-agents/SKILL.md)
+- [context-optimization](skills/context-optimization/SKILL.md)
+- [evaluation](skills/evaluation/SKILL.md)
+- [project-development](skills/project-development/SKILL.md)
+
+External resources on context engineering:
+- Research on attention mechanisms and context window limitations
+- Production experience from leading AI labs on agent system design
+- Framework documentation for LangGraph, AutoGen, and CrewAI
+
+---
+
+## Skill Metadata
+
+**Created**: 2025-12-20
+**Last Updated**: 2025-12-25
+**Author**: Agent Skills for Context Engineering Contributors
+**Version**: 1.2.0