Guide · Agent skill
How to use the Domain Context and Decision Handoff agent skill
Updated · written with AI from the project's own documentation and checked against our catalogue data
The context-and-decisions skill is an agent skill for projects where business terms keep being re-explained or one word means different things to different people. It tells the agent to record confirmed domain definitions in one domain-language document, CONTEXT.md, and to send hard-to-reverse choices to the separate architecture-decision-records skill. This guide explains what the skill makes the agent do, how to install it, how to trigger it, and what to watch for.
Domain Context and Decision Handoffaffaan-m/ECC · MIT Download the skill Quick start
- 1Confirm the ECC skill set is installed. Make sure the architecture-decision-records skill is available, since this skill depends on it for all ADR work.
- 2Download and unzip the skill. Download the ZIP from this page and unzip it into ~/.claude/skills/ for personal use, or into the project's .claude/skills/ folder for one repository.
- 3Or upload it in the Claude apps. Open Settings → Capabilities → Skills and upload the skill there if you use the Claude apps.
- 4Ask about a confusing term. Describe the term that keeps being misunderstood, and mention that its meaning should be recorded.
- 5Review the context document. Check each definition against its cited code, contract or business rule, and confirm the items marked 'needs confirmation' with the right owner.
- 6Route hard decisions to ADRs. For a decision that is hard to reverse, let the agent hand it to architecture-decision-records and check that CONTEXT.md links to the ADR rather than copying it.
What is an agent skill, and what does this one do?
An agent skill is a folder containing a SKILL.md file with instructions that an AI coding agent loads when a request matches the skill's description. The agent then follows those instructions for that task.
This skill separates two kinds of knowledge. Domain context answers what the business terms mean. Decision records answer why a particular option was chosen. The skill keeps the first in CONTEXT.md and routes the second to the architecture-decision-records skill.
- Records domain terms with precise definitions, relationships between core concepts, and confirmed interpretations of ambiguous words.
- Marks anything unconfirmed as 'needs confirmation' instead of guessing.
- Reuses an existing glossary or domain-model document if the project already has one, or the context role in .governance/docs-map.json if mapped.
- Hands durable, hard-to-reverse decisions to architecture-decision-records and links to the resulting ADR instead of copying it.
- Keeps tasks, schedules, status and blockers out of the context document.
Install the context-and-decisions skill
You can install the skill in one of two ways. Download the ZIP from this page and unzip it into your personal skills folder, ~/.claude/skills/, or into a project's .claude/skills/ folder if you want it to apply only to that project.
Alternatively, upload the skill in the Claude apps under Settings → Capabilities → Skills.
- Personal install: unzip into ~/.claude/skills/ so it is available across your projects.
- Project install: unzip into the project's .claude/skills/ folder so it is available to that repository.
- App install: upload the skill under Settings → Capabilities → Skills.
Check the requirements before you start
The skill depends on the ECC skill set. The architecture-decision-records skill must be available, because this skill hands all ADR work to it and does not define its own ADR process.
The .governance/docs-map.json file is optional. If your project has one, the skill uses its context role to find the existing domain document. Without it, the skill looks for an equivalent glossary or domain-model document in the repository.
- Required: the ECC skill set, with architecture-decision-records available.
- Optional: .governance/docs-map.json with a context role mapping.
- Runs scripts: no.
- Uses network: no.
How to trigger the skill with natural requests
You do not need a special command. Describe the situation in plain language, and the agent should match it to the skill's description. The skill is meant for cases where domain language causes repeated confusion, so mention that directly.
Requests that match the skill's trigger conditions include cases where terms need repeated explanation, one term has several meanings, unclear language causes module-boundary mistakes, or you want domain meaning kept separate from architecture decisions.
- 'Our team keeps re-explaining what an order means. Can you record one agreed definition for it?'
- 'Customer and account are used interchangeably in this codebase. Pin down what each term means.'
- 'We just decided to store events in a separate service and it's hard to reverse. Record that as a decision.'
- 'Check whether there is already a glossary in this repo before creating anything new.'
What the agent produces
The domain document follows the template in templates/context.example.md. It has four parts: core terms with precise definitions and evidence, concept relationships, resolved ambiguities, and items that need confirmation. Each term should be traceable to code, a contract, or business evidence.
For an ambiguity that is not yet settled, the agent writes 'needs confirmation' next to the item, names the owner or domain role who should confirm it, and does not change the implementation based on it. For a hard-to-reverse decision, the agent runs the architecture-decision-records skill and links the ADR from CONTEXT.md, the project map, or the relevant spec or issue.
- Core terms table: term, precise definition, evidence or source.
- Concept relationships: one-to-many, state transition, containment or constraint.
- Resolved ambiguities: the adopted meaning and the expression to stop using.
- Needs confirmation: the open item and who must confirm it.
## Core Terms
| Term | Precise definition | Evidence/source |
|---|---|---|
| `{term}` | `{what it means and how it differs from adjacent terms}` | `{business rule, contract, or code location}` |Safety notes and limits
The skill does not run scripts and does not use the network, according to its listing. It works by reading and writing files in your repository.
The skill is deliberately narrow. It will not create an empty CONTEXT.md for completeness, and it will not define a second ADR system. Routine implementation details, easily reversible changes and short-lived experiments are not meant to produce ADRs.
- No scripts are run and no network use is declared.
- Unconfirmed domain meanings are marked, not treated as fact.
- Schedules and task status belong in your existing tracker, such as GitHub Issues or Linear.
What people use it for
- Pinning down what a business term such as 'order' or 'account' means across a codebase.
- Recording relationships between core concepts, such as one-to-many links or state transitions.
- Flagging an unsettled domain rule as 'needs confirmation' until a domain owner answers.
- Linking a storage or module-boundary decision from the context document to its ADR.
Frequently asked questions
Do I need to install anything else to use this skill?
Yes. The skill requires the ECC skill set with the architecture-decision-records skill available, because it hands all ADR work to that skill. The .governance/docs-map.json file is optional.
Where do I put the skill files?
Unzip the downloaded ZIP into ~/.claude/skills/ for personal use or into a project's .claude/skills/ folder for one repository. You can also upload it in the Claude apps under Settings → Capabilities → Skills.
Is the context-and-decisions skill free to use?
The skill is listed under the MIT licence, which is stated on this page. Check the licence file in the source repository for the full terms before redistributing it.
Why won't the agent create a CONTEXT.md file for my project?
The skill is designed not to create empty context files. It only creates CONTEXT.md when there is stable domain language to record and no existing glossary or domain-model document already covers it.
Does this skill replace my issue tracker or architecture decision records?
No. Tasks, schedules and status stay in your existing tracker, and ADRs are handled by architecture-decision-records. This skill keeps domain definitions separate and links to those other records.
Does the skill run scripts or access the internet?
According to its listing, it runs no scripts and uses no network. It reads and writes files in your repository.
New agent skills, repos and AI tools — every week
The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.
Our verdict
This skill suits developers and teams on projects where domain terms are repeatedly misunderstood, and maintainers who already use the ECC skill set and want consistent ADR handling. It is a poor fit for small projects without ambiguous language, and for non-technical users who want a general writing or document tool, since it is a narrow governance workflow.
Download the skill