{"id":50682277,"url":"https://github.com/DBvc/agent-skill-control-theory","last_synced_at":"2026-06-25T18:00:57.050Z","repository":{"id":356335494,"uuid":"1231131947","full_name":"DBvc/agent-skill-control-theory","owner":"DBvc","description":"A First-Principles Framework for LLM Agent Skills","archived":false,"fork":false,"pushed_at":"2026-05-31T08:33:02.000Z","size":127,"stargazers_count":2,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-05-31T10:13:26.122Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/DBvc.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-05-06T16:56:37.000Z","updated_at":"2026-05-31T08:31:58.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/DBvc/agent-skill-control-theory","commit_stats":null,"previous_names":["dbvc/agent-skill-control-theory"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/DBvc/agent-skill-control-theory","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/DBvc%2Fagent-skill-control-theory","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/DBvc%2Fagent-skill-control-theory/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/DBvc%2Fagent-skill-control-theory/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/DBvc%2Fagent-skill-control-theory/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/DBvc","download_url":"https://codeload.github.com/DBvc/agent-skill-control-theory/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/DBvc%2Fagent-skill-control-theory/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34786231,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-25T02:00:05.521Z","response_time":101,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-06-08T20:00:23.310Z","updated_at":"2026-06-25T18:00:57.042Z","avatar_url":"https://github.com/DBvc.png","language":"Python","funding_links":[],"categories":["Python"],"sub_categories":[],"readme":"# Agent Skill Control Theory\n\n**Agent Skill Control Theory** (ASCT) is a first-principles framework for designing, reviewing, evaluating, and evolving LLM agent skills.\n\nThe practical slogan is **Skill Mechanics**: a skill is not a longer prompt, a personality, or a knowledge dump. A skill is a selectively loaded control layer that changes how an LLM agent behaves on a recurring class of tasks.\n\n```text\nSkill = a selectively loaded policy controller for an LLM agent.\n```\n\nMore explicitly:\n\n```text\nA skill is a packaged control layer that activates for a task distribution.\nIt changes an agent's action distribution by adding instructions, external context,\ndeterministic executors, reusable materials, and validation rules.\n```\n\nASCT is an engineering framework for designing reliable, testable, and maintainable LLM agent skills.\n\nChinese version: [README.zh-CN.md](README.zh-CN.md).\n\n## Status\n\nThis is a working engineering theory, not an official standard.\n\nASCT is built on the public Agent Skills format and the progressive disclosure model described by:\n\n- [Agent Skills specification](https://agentskills.io/specification)\n- [OpenAI Codex skills documentation](https://developers.openai.com/codex/skills)\n- [Anthropic Agent Skills overview](https://www.anthropic.com/engineering/equipping-agents-for-the-real-world-with-agent-skills)\n\nThe theory is deliberately narrower than general LLM application architecture. It focuses on filesystem-like skills built around `SKILL.md`, metadata, references, scripts, assets, and skill-specific evaluation.\n\nMany ASCT principles also apply to agents, prompt routers, workflow engines, and tool-using LLM systems. However, ASCT treats skills as a specific design object: a portable, selectively loaded behavior package.\n\n## Why this theory exists\n\nSkill repositories often begin as useful prompt collections. That works for a while. Then the collection tends to drift into recurring failure modes:\n\n1. **Anecdote accumulation**: every new failure adds one more rule.\n2. **Context inflation**: `SKILL.md` becomes a suitcase full of every possible concern.\n3. **Wrong activation**: a good skill becomes harmful when loaded for the wrong task.\n4. **Unverified completion**: the agent says the task is done because the answer sounds complete.\n5. **Placement mistakes**: rules that should be scripts, hooks, references, or global instructions are written as skill prose.\n6. **Unmeasured confidence**: the author believes the skill improved because it feels more complete.\n\nASCT starts from the agent, not from examples. It asks:\n\n```text\nWhat failure modes does the base agent have on this task distribution?\nWhich control surfaces can a skill influence?\nWhat is the cheapest safe controller that reduces those failures?\nHow do we know it actually helped?\n```\n\n## Core mapping\n\nASCT maps common skill artifacts to control functions:\n\n| Skill artifact | ASCT role | Main question |\n|---|---|---|\n| `description` | Activation classifier | Should this skill be used? |\n| `SKILL.md` | Runtime controller | What should the agent do after activation? |\n| `references/` | External semantic memory | What long or conditional knowledge should be loaded only when needed? |\n| `scripts/` | Deterministic executors | What should not be done by free-form generation? |\n| `assets/` | Reusable material priors | What templates, examples, schemas, or static resources should the agent reuse? |\n| `evals/` | Controller regression tests | How do we know the skill improved behavior and did not regress? |\n\nHost-specific artifacts such as commands, hooks, status lines, `AGENTS.md`, `CLAUDE.md`, `llms.txt`, marketplace metadata, generated indexes, planning files, and project memory files are also useful. ASCT treats them as implementation mechanisms that map back to the same control surfaces. They are not new primitives.\n\n## Five postulates\n\nASCT uses five foundational assumptions.\n\n1. **Conditional Policy**: Agent behavior changes with context, instructions, tools, observations, and resources.\n2. **Bounded Resources**: Context, attention, tool calls, time, user patience, and safety budget are finite.\n3. **Non-zero Fallibility**: Agents have non-zero error rates in activation, intent inference, state grounding, trajectory selection, execution, and completion claims.\n4. **External Groundability**: Many task-relevant facts and deterministic operations can be handled more reliably by external evidence and tools than by model generation alone.\n5. **Drift**: Models, tools, APIs, repositories, organizations, and task distributions change over time.\n\nThese are not philosophical decorations. They explain why skill design needs activation boundaries, progressive disclosure, evidence policies, deterministic scripts, completion proof, and regression tests.\n\n## Seven control surfaces\n\nA skill may influence seven parts of agent behavior:\n\n| Control surface | Question it controls |\n|---|---|\n| Activation Control | Should this skill be used? |\n| Intent Control | What task is the user actually asking for? |\n| State Control | What is true right now? |\n| Trajectory Control | What path should the agent follow? |\n| Execution Control | Which operations require deterministic tools? |\n| Completion Control | When may the agent claim done? |\n| Evolution Control | How does the skill avoid drift and regression? |\n\nA skill does not need every control surface. A small writing skill may need activation and style control. A release skill may need activation, state, trajectory, execution, completion, safety, and evolution control.\n\n## Nine design laws\n\nASCT derives nine engineering design laws from the postulates.\n\n1. **Trigger Boundary Law**: A skill's first quality is correct activation.\n2. **Task Compilation Law**: A skill compiles user utterances into task frames and modes.\n3. **Context Economy Law**: Every token in `SKILL.md` should buy behavior change.\n4. **Evidence Externalization Law**: Current facts should come from external evidence, not latent memory.\n5. **Trajectory Constraint Law**: Workflow exists to make bad paths harder to take.\n6. **Freedom-Risk Law**: Higher-risk tasks require lower agent freedom.\n7. **Deterministic Delegation Law**: Models judge; tools execute deterministically.\n8. **Completion Proof Law**: Done means output plus evidence, validation, and limitations.\n9. **Drift Regression Law**: Skills are drifting controllers and need evals, versions, and regression tests.\n\n## Value function\n\nASCT evaluates skills by net reliability gain, not instruction length, elegance, or author confidence.\n\n```text\nSkillValue(s, D) =\n  E_t~D[Success(agent_with_skill, t) - Success(base_agent, t)]\n  - Cost(s, D)\n  - Risk(s, D)\n```\n\nA skill is admissible only if:\n\n```text\nSafetyRisk(s, D) \u003c= SafetyBudget\n```\n\nA skill is worth keeping only if:\n\n```text\nSkillValue(s, D) \u003e 0\n```\n\nThe equation is not a physical law. It is an evaluation frame. Its purpose is to prevent a common mistake: mistaking more instruction for more reliability.\n\n## Repository contents\n\n```text\ndocs/\n  theory.md                 Full ASCT theory\n  foundations.md            Definitions, postulates, laws, and formulas\n  control-surfaces.md       The seven control surfaces\n  design-laws.md            The nine design laws\n  placement.md              Deciding where a control should live\n  host-artifacts.md         Commands, hooks, status lines, AGENTS.md, llms.txt, and related mechanisms\n  collection-design.md      Designing skill collections and skill graphs\n  value-function.md         Success, cost, risk, and measurement\n  evaluation.md             Trigger, output, process, safety, and regression evals\n  safety.md                 Safety constraints for skills and skill collections\n  glossary.md               Core terms\n  influences.md             Public sources and design influences\n  zh-CN/                    Chinese versions\n\ntemplates/\n  skill-ir.yaml             Internal representation for designing a skill\n  collection-ir.yaml        Internal representation for designing a skill collection\n  placement-decision.md     Template for deciding where a control belongs\n  skill-design-brief.md     Scenario and failure-map template\n  skill-review-rubric.md    Review rubric for existing skills\n  eval-plan.md              Evaluation planning template\n  patch-hypothesis.md       Skill change proposal template\n  trigger-evals.json        Trigger eval fixture template\n  output-eval-rubric.yaml   Output eval rubric template\n  zh-CN/                    Chinese template versions\n\nexamples/\n  frontend-debug/           A synthetic skill designed with ASCT\n\nscripts/\n  check_repo.py             Lightweight repository checks\n```\n\n## How to use ASCT\n\nWhen designing a new skill:\n\n1. Define the task distribution.\n2. Identify likely base-agent failure modes.\n3. Decide whether the control should be a skill, command, hook, script, reference, repo memory, or global instruction.\n4. Choose the relevant control surfaces.\n5. Write the activation classifier in `description`.\n6. Write the runtime controller in `SKILL.md`.\n7. Move long and conditional knowledge to `references/`.\n8. Move deterministic checks to `scripts/`.\n9. Define completion proof.\n10. Add trigger, output, process, safety, and regression evals.\n11. Evolve through patch hypotheses, not author confidence.\n\nWhen reviewing an existing skill:\n\n1. Ask which task distribution it claims to serve.\n2. Ask which failure modes it reduces.\n3. Map its artifacts to control surfaces.\n4. Estimate context cost, friction cost, runtime cost, and safety risk.\n5. Check whether final claims are tied to evidence.\n6. Look for near-miss trigger cases.\n7. Decide whether some content belongs outside `SKILL.md`.\n8. Require evals before calling the change an improvement.\n\n## Design stance\n\nASCT is intentionally disciplined about theory growth.\n\nNew repositories, platforms, or host artifacts should not automatically add new primitives. First map them to the five postulates, seven control surfaces, and nine design laws. Change the core only if the new case exposes a failure mode that cannot be explained by the current theory.\n\n## Quick start\n\nRun repository checks:\n\n```bash\npython3 scripts/check_repo.py\n```\n\nStart designing a skill from:\n\n```text\ntemplates/skill-ir.yaml\ntemplates/skill-design-brief.md\ntemplates/skill-review-rubric.md\ntemplates/eval-plan.md\n```\n\nFor collection-level design, start from:\n\n```text\ntemplates/collection-ir.yaml\n```\n\nFor placement decisions, start from:\n\n```text\ntemplates/placement-decision.md\n```\n\n## License\n\nMIT. See [LICENSE](LICENSE).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FDBvc%2Fagent-skill-control-theory","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FDBvc%2Fagent-skill-control-theory","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FDBvc%2Fagent-skill-control-theory/lists"}