Normalize every SKILL.md description to double-quoted YAML so the corpus,
templates, and examples have one visible convention. Harden frontmatter
parsing against partial fence matches and non-string name/description values,
and extend tests to cover those regressions.
Fix stale or misleading developer-facing docs: remove phantom book-sft plugin
install instructions, document directory-copy installs, add .agents/skills
manual install guidance, fix the digital-brain setup script target, and mark
historical 13-skill analysis as historical. Cut the prepared release metadata
to 2.3.1 across manifests and root SKILL.md.
Tighten production gates by sharing dev dependencies, making orchestrators use
strict repo validation, aligning skill-health required sections with repo
validation, and linting documented plugin install commands against the actual
marketplace manifest.
Co-authored-by: Muratcan Koylan <muratcankoylan@users.noreply.github.com>
Addresses bugs and content issues found during code review of
commit c847b20 (the textbook-to-instructional rewrite).
Critical fixes:
- evaluator.py: Remove free +0.2 completeness bonus (inflated scores)
- evaluator.py: Replace bracket-based citation check with regex
pattern matching to avoid false positives from code/JSON
- coordination.py: Fix run_workflow to simulate worker responses
instead of silently returning empty results
- degradation_detector.py: Replace numpy dependency with stdlib
random module (was the only third-party dep across all scripts)
Important fixes:
- compaction.py: summarize_conversation now retains actual decision
text instead of discarding content and keeping only counts
- memory_store.py: Use np.random.default_rng() instead of
np.random.seed() to avoid corrupting global numpy state
- memory_store.py: Replace late 'import time' with datetime (already
imported) for consistency
- description_generator.py: ToolSchemaBuilder.build() now returns a
ToolSpec-compatible object; add add_trigger/add_example methods;
demo now connects builder -> generator -> evaluator
- sandbox_manager.py: Fix demo to look up actual session_id from
active_sessions instead of constructing a mismatched key
- context_manager.py: Fix validate_context_structure false positive
on empty lists (e.g., documents: [])
- evaluator.py: Move random import to __init__ with local RNG instance
Content fixes:
- context-degradation SKILL.md: Replace fabricated model benchmark
table (GPT-5.2, Gemini 3) with general guidance
- multi-agent-patterns SKILL.md: Remove specific model name claims;
deduplicate gotcha 1 vs Practical Guidance section
- context-optimization SKILL.md: Standardize compaction threshold to
70% (was inconsistently 70% and 70-80%)
- advanced-evaluation SKILL.md: Fix created date 2024 -> 2025
- memory-systems SKILL.md: Fix missing space in description
- filesystem-context SKILL.md: Add "Read when:" to external resources
- bdi-mental-states SKILL.md: Add missing Skill Metadata section and
"Read when:" triggers on primary sources
- skills-improvement-analysis.md: Mark gotchas gap as resolved
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Based on Anthropic's "Lessons from Building Claude Code" article,
this is a comprehensive upgrade of all skills to be actionable
toolboxes rather than conceptual textbooks.
Changes across all 13 skills:
- Rewrite prose from descriptive ("X is Y") to hybrid instructional
voice ("Do X because Y") — leads with actions, weaves in reasoning
- Add standardized ## Gotchas sections (5-9 per skill) with
experience-derived, specific, actionable failure modes
- Update scripts for composability: __all__ exports, type hints,
"Use when:" docstrings, __main__ demo blocks
- Add progressive disclosure triggers to all References sections
("Read when: [specific condition]")
- Update template/SKILL.md with canonical Gotchas section
Key metrics:
- Total SKILL.md lines: 3,559 → 3,421 (compressed despite adding content)
- Skills with Gotchas: 4 → 13 (100% coverage, standardized format)
- Scripts with __all__: 0 → 12 (all except bdi-mental-states)
- References with triggers: 0 → 13 (100% coverage)
- All skills remain under 500-line limit (range: 195-402)
Also adds docs/skills-improvement-analysis.md with the full gap
analysis against Anthropic's best practices.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Database:
- PostgreSQL + pgvector for semantic search over skills and documents
- OpenAI embeddings for semantic similarity
- CLI tools: index, search, reindex
- Supabase production deployment ready
- Docker Compose for local development
Docs:
- Added frontmatter to all documents (name, description, doc_type, source_url)
- Reorganized doc structure
.gitignore:
- Added Private/ and .cursor/ to prevent accidental commits
When to Activate: Added "Codebases exceed context windows (5M+ token systems)"
Three-Phase Compression Workflow (new section):
Research Phase: produce structured research document
Planning Phase: compress to specification (5M tokens → 2,000 words)
Implementation Phase: execute against spec
Using Example Artifacts as Seeds (new section):
When given a reference PR or manual migration, use it as a template
The example encodes the distinction between essential and accidental complexity
References: Added Netflix Engineering source
New Development Methodology category with project-development skill covering:
- Task-model fit analysis for identifying LLM-suitable tasks
- Staged pipeline architecture (acquire, prepare, process, parse, render)
- File system as state machine pattern
- Structured output design for reliable parsing
- Agent-assisted development workflow
- Cost estimation and architectural reduction principles
Includes case studies from Karpathy HN Time Capsule, Vercel d0, Manus, and Anthropic multi-agent research.
References:
- references/case-studies.md: Production case study analysis
- references/pipeline-patterns.md: Detailed code patterns
- scripts/pipeline_template.py: Working pipeline template
Also adds docs/karpathy/hncapsule source material.
New skill based on Factory Research (Dec 2025) on context compression:
- Anchored iterative summarization preserves more information
- Tokens-per-task is the right metric, not tokens-per-request
- Probe-based evaluation measures functional compression quality
- Six evaluation dimensions: accuracy, context, artifact, completeness, continuity, instruction
- Artifact trail is universally weak (2.2-2.5) and needs specialized handling
Includes:
- SKILL.md with compression strategies and evaluation framework
- references/evaluation-framework.md with probe types and scoring rubrics
- scripts/compression_evaluator.py with evaluation utilities
muratcankoylan