{"owner":"muratcankoylan","repo":"Agent-Skills-for-Context-Engineering","hasSkills":true,"hasMcp":false,"mcpConfig":null,"found":["AGENTS.md","CLAUDE.md"],"files":{"AGENTS.md":"# AGENTS.md\n\nWorkspace memory for agents collaborating on this repository. Keep entries durable and broadly applicable; one-off task state belongs in chat or in a run thread, not here.\n\n## Learned User Preferences\n\n- For autonomous research and repo-improvement work in this workspace, prefer proceeding through concrete research loops, subagents, validation, and edits when the scope is clear rather than asking broad process questions.\n- Avoid stale regex or keyword-list heuristics in skills and scripts; prefer mechanism-level criteria, rubrics, and evidence-backed validation.\n- Never push to GitHub or merge a PR without explicit user approval. Preparing branches, commits, and PRs is permitted only when the user has approved that specific action.\n- Tone is technical CTO: direct, no marketing language, no exclamation marks, no emojis, no em dashes. State trade-offs and complexity upfront.\n- When the scope spans multiple architectural decisions or irreversible changes, propose a plan first instead of executing.\n- For benchmarks and evaluation work, hold to research-paper-grade methodology (statistical discipline, bias mitigation, ablations, reproducibility) over speed. Don't rush.\n\n## Learned Workspace Facts\n\n- This repo is an autonomous research-to-skill organization. External AI research is curated through rubrics and distilled into context-engineering and harness-engineering skill updates.\n- `researcher/` is repo-native and file-based so agents can resume, audit, validate, and prepare PR-ready skill changes without a hosted scheduler.\n- Per-run state lives in `researcher/runs/<run-id>/run-state.json` with explicit transitions (`initialized -> retrieved -> evaluated -> proposed -> novelty_checked -> validated -> pr_ready -> closed`). Use `research_loop.py` subcommands to advance state, never hand-edit `run-state.json`.\n- Repo health (`validate_repo.py`) and per-run readiness (`validate_run.py`) are different questions. CI runs `validate_platform_compat.py --require-reference-validator`, `validate_repo.py --strict`, `skill_health.py --strict --no-history`, `run_benchmarks.py`, and `check_activation_cases.py` on every PR via `.github/workflows/validate.yml`.\n- The mechanism registry (`researcher/mechanisms/registry.jsonl`) is the encyclopedia backbone. Promotion is gated by `research_loop.py promote-mechanisms` with a recorded reviewer; ledgers live under `researcher/mechanisms/ledgers/`.\n- Claim provenance for numeric or volatile claims lives in `researcher/claims/index.jsonl`. Add an entry for any new benchmark or volatility-sensitive claim.\n- The corpus index (`researcher/corpus/index.json`) is the machine-readable map of skills, activation scenarios, mechanisms, and claims. Update it when adding or restructuring skills.\n- The continuous loop (`researcher/scripts/loop_*.py`) runs from launchd via `researcher/orchestration/launchd/`. It never invokes paid LLMs; HTTP retrieval is stdlib-only with a 1.5 MB cap and a 30-second timeout.\n- Runtime state is not committed: `researcher/queue/*.jsonl`, `researcher/queue/.locks/`, `researcher/reports/{logs,snapshots,loop-events.jsonl,loop-failures.jsonl,status.md,parked-review.md}`, and `researcher/runs/*/` are gitignored. The seed run `20260515-035228-executable-autonomous-research-frameworks` is the only committed run; it is closed as `reference-only` and serves as a worked example.\n- The current prepared release version is 2.5.0 across `.claude-plugin/marketplace.json`, `.plugin/plugin.json`, and root `SKILL.md`. There are 17 skills (latent-briefing covers KV cache sharing between agents; self-improvement-loops covers RSI, meta-harness search, and evolutionary scaffold optimization; long-horizon-prompting covers pseudo-formal task briefs for long-running and parallel agent runs).\n- Detailed lessons from building the researcher OS live in `researcher/insights/auto-research-experiment.md` (engineering rationale) and `researcher/insights/how-we-built-this.md` (project narrative and sharing templates); read both before extending the harness or writing release-facing prose.\n- Benchmarks are staged in `researcher/benchmarks/`: Stage 0 deterministic harness (shipped), Stage 1 per-skill health via `researcher/scripts/skill_health.py` (shipped; output `researcher/reports/skill-health.json` is gitignored), Stage 2 router (shipped; results in `researcher/benchmarks/router/results-published/`), Stage 3 effectiveness (scaffolded, one task built), Stage 4 composition (future). `researcher/benchmarks/PLAN.md` is the methodology source of truth.\n- Current corpus counts and compatibility status are generated in `researcher/generated/corpus-summary.md`; do not copy live totals into workspace memory. Published benchmark reports remain dated snapshots. Do not describe a skill improvement as complete unless the prose, mechanism registry, claim index, corpus index, activation fixtures, generated inventory, and validators all agree.\n- Public export uses `validate_export.py plan|render|check` and registered transforms from `governance/export-policy.yaml`. Private plans and receipts are ignored; public manifests contain projection and output digests, never private source paths or input digests.\n- Durable cross-runtime records resolve through `researcher/schemas/registry.json`. JSON digests use the integer-only `jcs-rfc8785-integer-v1` profile; blobs hash exact bytes. `ArtifactRef` never contains a private locator or grants authority, and reads must validate its private `StorageBinding`. Candidate evaluation must use a SPEC-003 freeze receipt created under an explicit editable-surface policy, not a mutable worktree.\n- Benchmark execution uses the Cursor SDK runner at `researcher/benchmarks/sdk-runner/` (TypeScript, `@cursor/sdk` 1.0.13). The runner supports `--concurrency N`, `--no-resume`, per-run progress logging, format-failure retry, and worst-case retry-aware cost forecasting; default behavior is to resume by skipping plan items that already have result files. Result artifacts under `researcher/benchmarks/{router,effectiveness}/results/` and history JSONLs (`router-history.jsonl`, `effectiveness-history.jsonl`) are gitignored.\n- Published Stage 2 router-benchmark results: `researcher/benchmarks/router/results-published/2026-05-15.md` (baseline), `researcher/benchmarks/router/results-published/2026-05-15-v2.md` (post-rewrite with delta-vs-baseline table), and `researcher/benchmarks/router/results-published/2026-05-19.md` (post-corpus-hardening validation: 600/600 usable records, 0 format failures, top-1 Gemini 0.920 / Composer 0.913 / GPT-5.5 0.913 / Claude Opus 4.7 0.840). Headline finding: targeted description rewrites moved `context-fundamentals` top-1 by +23.4pp and `project-development` top-1 to 1.000; corpus-wide hardening did not cause broad routing collapse.\n\n## Repository Operating Defaults\n\n- Deterministic checks before model judges. Always run `validate_platform_compat.py --require-reference-validator` and `validate_repo.py --strict` before claiming a skill-format or packaging change is complete.\n- Adversarial benchmarks before declaring the harness safe. Add a scenario when a new failure mode is discovered.\n- Append-only ledgers for accepted and rejected mechanisms so future agents do not rediscover failed paths.\n- Atomic writes (`tempfile` + `os.replace`) and `fcntl` locks for any shared file the loop touches.\n- Live execution is the highest-signal validation for orchestration code; smoke-test changes against the actual loop before declaring them safe.\n- Cursor SDK is the only paid-API surface allowed for benchmarks. Privacy Mode required, `apiKey` passed explicitly per call, never `settingSources: \"all\"` in benchmarks (use `[]` for control, `[\"project\"]` with a curated `.cursor/skills/` for ablation). Cost gates (`--max-runs`, `--max-budget-usd`, or `--dry-run`) must be set before any SDK call.\n- Description quality is measurable. When changing skill activation descriptions, re-run the router benchmark with the same seed and fixture and publish the delta. Aggregate accuracy is a misleading unit; per-skill effect sizes and the confusion matrix are the right view.\n- A skill is a multi-surface artifact. Changing the frontmatter `description` is not enough; the SKILL.md body `When to Activate` and `Integration` sections must be audited the same day so the body does not contradict the description that routed the agent to it. The router benchmark only sees descriptions (`settingSources: []`) and cannot catch body inconsistencies; only Stage 3 effectiveness benchmarks (which actually load skill bodies) measure body-alignment impact.\n- Any runner that calls a paid API in a loop must have three features before execution: bounded parallelism via `--concurrency`, resume capability via results-folder scan, and per-run progress logging that surfaces stalls inside one call's duration.\n- API keys provided in chat should be considered exposed; rotate immediately after use. Runner enforces this via `apiKeyFingerprint()` which only logs the last 4 characters.\n","CLAUDE.md":"# CLAUDE.md\n\nThis file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.\n\n## Project Overview\n\nAgent Skills for Context Engineering is an open collection of Agent Skills teaching context engineering and harness engineering principles for production AI agent systems. Skills are platform-agnostic (Claude Code, Cursor, Codex/OpenAI Agent Skills, GitHub Copilot, any Open Plugins-conformant tool). v2.5.0 adds the long-horizon-prompting skill (pseudo-formal task briefs for long-running autonomous agents and parallel orchestrations) on top of the self-improvement-loops skill (v2.4.0) and the file-based researcher operating system with deterministic gates, cross-platform Agent Skills validation, and a continuous loop. Use the [generated live inventory](researcher/generated/corpus-summary.md) for current corpus counts.\n\nContext engineering is the discipline of curating everything that enters a model's context window (system prompts, tool definitions, retrieved documents, message history, tool outputs) to maximize signal within limited attention budget.\n\n## Repository Structure\n\n- `skills/` - published skill directories, each containing a `SKILL.md` with YAML frontmatter (`name`, `description`) and optional `references/` and `scripts/` subdirectories\n- `examples/` - complete demonstration projects; the generated inventory is the count authority\n- `docs/` - Research materials and reference documentation\n- `researcher/` - File-based research-to-skill operating system: rubrics, mechanism registry, claim provenance, corpus index, run state machine, adversarial benchmarks, continuous loop, launchd service definitions\n- `template/SKILL.md` - Canonical skill template (use when creating new skills)\n- `SKILL.md` (root) - Collection-level metadata and skill map\n- `.claude-plugin/marketplace.json` - Claude Code marketplace manifest (single bundled plugin, v2.5.0)\n- `.plugin/plugin.json` - Open Plugins format manifest (v2.5.0)\n\n## Build & Test Commands\n\nNo top-level build system. Repo-level gates and per-project tooling below.\n\n### Top-level deterministic gates (run on every PR via CI)\n\n```\npython3 -m unittest researcher.scripts.tests.test_skill_frontmatter # parser and strict-YAML regression tests\npython3 researcher/scripts/validate_governance.py --check # authority model and generated view\npython3 researcher/scripts/build_inventory.py --check    # corpus references and generated inventory\npython3 researcher/scripts/validate_platform_compat.py --require-reference-validator # Agent Skills reference validator + Cursor/Claude/Codex install-layout simulation\npython3 researcher/scripts/validate_repo.py --strict       # corpus structure, manifests, rubric math, mechanism registry, claims, corpus index, activation cases, benchmark scenarios, run artifacts\npython3 researcher/scripts/skill_health.py --strict --no-history  # deterministic skill-body quality gate\npython3 researcher/scripts/run_benchmarks.py               # adversarial benchmark harness + repo + activation gates\npython3 researcher/scripts/check_activation_cases.py       # skill-boundary regression fixtures\n```\n\n### Per-run readiness (active runs only)\n\n```\npython3 researcher/scripts/validate_run.py --run-dir researcher/runs/<run-id>\n```\n\n### Continuous loop (manual or launchd)\n\n```\npython3 researcher/scripts/loop_discover.py\npython3 researcher/scripts/loop_step.py --allow-fetch\npython3 researcher/scripts/loop_daily.py\npython3 researcher/scripts/loop_status.py\n\nresearcher/orchestration/launchd/install.sh    # macOS daemon\nresearcher/orchestration/launchd/uninstall.sh\n```\n\n### Example projects\n\n#### examples/llm-as-judge-skills (TypeScript, Node >= 18)\n```\ncd examples/llm-as-judge-skills\nnpm install\nnpm run build        # tsc\nnpm test             # vitest (19 tests)\nnpm run lint         # eslint\nnpm run format       # prettier\nnpm run typecheck    # tsc --noEmit\n```\n\n#### examples/interleaved-thinking (Python >= 3.10)\n```\ncd examples/interleaved-thinking\npip install -e \".[dev]\"\npytest               # pytest + pytest-asyncio\nruff check .         # linting (100 char line length)\n```\n\n#### examples/digital-brain-skill (Node.js)\n```\ncd examples/digital-brain-skill\nnpm run setup\nnpm run weekly-review\nnpm run content-ideas\nnpm run stale-contacts\n```\n\n## Skill Authoring Rules\n\nWhen creating or editing skills:\n\n1. **SKILL.md must stay under 500 lines**: move detailed content to `references/` directory\n2. **YAML frontmatter is required**: must include `name` and `description` fields\n3. **Folder naming**: lowercase with hyphens (e.g., `context-fundamentals`)\n4. **Write in third person**: descriptions are injected into system prompts; inconsistent POV causes discovery issues\n5. **Platform-agnostic**: no vendor-locked examples or platform-specific tool names without abstraction\n6. **Token-conscious**: challenge each paragraph and assume an advanced audience\n7. **Body standard**: include `When to Activate`, `Core Concepts`, `Practical Guidance`, `Examples`, `Guidelines`, `Gotchas`, `Integration`, and `References`\n8. **Explicit boundaries**: every `When to Activate` section needs positive triggers plus a `Do not activate` block routing adjacent work to the right skill\n9. **Include a Gotchas section**: experience-derived failure modes are the highest-signal content in any skill\n10. **Update root README.md** when adding new skills\n11. **Update marketplace/plugin manifests** when adding skills (`.claude-plugin/marketplace.json`, `.plugin/plugin.json`)\n12. **Update the corpus index** (`researcher/corpus/index.json`) to map the new skill to activation scenarios, mechanism IDs, and claim IDs\n13. **Update mechanisms and claims**: add registry entries for reusable behavior changes and `claim-*` provenance for numeric, benchmark, volatile, or vendor-performance claims\n14. **Run `validate_platform_compat.py --require-reference-validator`, `validate_repo.py --strict`, `skill_health.py --strict --no-history`, `check_activation_cases.py`, and `run_benchmarks.py`** before committing skill changes\n\n## Researcher OS Rules\n\nWhen working through the researcher operating system:\n\n1. **Initialize runs via `research_loop.py init`**: it creates `run-state.json`, queue entry, thread log, source evaluation scaffold, and mechanism proposal template\n2. **Advance state explicitly**: use `retrieve`, `evaluate`, `propose`, `novelty`, `validate-run`, `pr-ready`, `close` subcommands; do not edit `run-state.json` by hand\n3. **Promote mechanisms only after run readiness**: `research_loop.py promote-mechanisms` requires `--reviewed-by` and a passing run-readiness check\n4. **Add claim provenance** to `researcher/claims/index.jsonl` for any numeric, benchmark, or volatile claim added to a skill\n5. **Never invoke paid LLMs from the continuous loop**: HTTP retrieval is stdlib-only, judge adapters are explicitly out of scope until budget-gated\n6. **Never commit runtime queue/report files**: `.gitignore` covers `researcher/queue/*.jsonl`, `researcher/reports/{logs,snapshots,loop-events.jsonl,loop-failures.jsonl,status.md,parked-review.md}`, and `researcher/runs/*/` except the seed run\n\n## Plugin Architecture\n\nAll published skills are distributed as a single plugin (`context-engineering`) in the marketplace manifest. This avoids cache duplication: Claude Code caches each plugin's `source` directory separately, so multiple plugins pointing to `source: \"./\"` would each cache a full copy of the repo.\n\nProgressive disclosure pattern: only skill names/descriptions load at startup; full content loads on activation.\n\n## Key Design Principles\n\n- **Context quality over quantity**: attention scarcity and lost-in-middle behavior mean more context is not always better\n- **Sub-agents isolate context**: they exist to manage attention budget, not simulate org roles\n- **Skills reference each other**: use plain text skill names (not links) in Integration sections to avoid cross-directory reference issues\n- **Examples use Python pseudocode**: conceptual demonstrations that work across environments, not production-ready implementations\n- **Deterministic first, model-judged second**: structure, schema, rubric math, manifest sync, retrieval status, and registry shape must pass before any LLM judge is invoked\n- **Human-controlled merge**: agents may prepare PRs and pass gates, but push and merge always require explicit human approval\n"}}