Skill Hub — AI-Assisted Development

AI coding agent task design

Turn vague work into narrow, testable coding-agent tasks with one objective, relevant files, constraints, validation commands, done criteria, and stop conditions.

What this skill is for

This skill prevents agents from drifting. It produces a task brief that an agent can execute, a human can review, and a test suite can validate. The output is a coding-agent task card with objective, scope, constraints, validation, and reporting requirements.

When to use this skill

  • You are delegating implementation work to Claude Code, Codex CLI, Cursor, Copilot, Aider, or a similar agent.
  • A stakeholder asks for a feature but the request is broad or ambiguous.
  • You want to compare agent output against explicit acceptance criteria.
  • You need to review agent work efficiently without reconstructing intent.

Real work situations

Add a new Atlas page

Instead of "add an AI tools page," the task becomes: "Create atlas/ai-tools/repository-context-packaging.md with frontmatter matching existing diagnostics pages, include sections X, Y, Z, and run python scripts/generate_atlas_artifacts.py --check without errors. Do not modify the homepage."

Fix a failing test

The task is: "Make test_dynamic_discovery_returns_22_article_pages pass after adding three new Atlas articles. Update only the count assertions in tests/test_atlas_artifacts.py. Run the test and confirm green."

Refactor a utility module

The task is: "Extract the URL validation logic from src/links.py into src/link_validation.py. Update all imports in src/. Run the test suite. Do not change public API behavior."

Inputs required

  • One-sentence objective — the single outcome the agent must produce.
  • Relevant files — what the agent should read and what it may edit.
  • Constraints — what must not change, break, or be touched.
  • Validation commands — how to prove the change works.
  • Done criteria — conditions that must be true for the task to be considered complete.
  • Stop conditions — when the agent must pause and ask for direction.

Questions to ask

  • Can the objective be verified with a test, diff, or command?
  • Which files must the agent edit, and which must it leave alone?
  • What would prove the change is correct?
  • What could go wrong, and what should trigger a stop?
  • How should the agent report what it did?

Working method

  1. State the objective. One sentence. One outcome.
  2. List relevant files. Use explicit paths and mark each as read-only or editable.
  3. Define constraints. Include homepage, legal pages, verified pages, generated files, and private paths that must not be touched.
  4. Specify validation commands. Examples: pytest tests/test_atlas_artifacts.py, bundle exec jekyll build, python scripts/check_links.py _site.
  5. Write done criteria. Bulleted list of verifiable yes/no conditions.
  6. Write stop conditions. When the agent must pause: failing validation, ambiguous requirement, need for human approval.
  7. Define report format. Require a summary of changes, test results, and any assumptions.
  8. Run and review. Execute the task, inspect the diff, and run validation yourself.

Decision rules

  • If the objective has more than one outcome, split it into separate tasks.
  • If the agent needs to touch a protected file, stop and get human approval.
  • If validation fails, the agent must fix it or stop, not proceed.
  • If the agent introduces a new dependency, it must be justified and reviewed.
  • If the task changes public behavior, it needs a human sign-off before merge.

Deliverables

  • Coding-agent task card — the brief given to the agent.
  • Diff or patch — the changes produced by the agent.
  • Validation report — command outputs proving the change works.
  • Assumption log — anything the agent had to assume because the brief was incomplete.

Templates

Task card

Objective: [one-sentence outcome]

Relevant files:
- READ/EDIT: [path]
- READ-ONLY: [path]
- DO NOT TOUCH: [path]

Constraints:
- [Constraint 1]
- [Constraint 2]

Validation commands:
- [command 1]
- [command 2]

Done criteria:
- [ ] [verifiable condition 1]
- [ ] [verifiable condition 2]

Stop conditions:
- [validation command] fails and cannot be fixed in one iteration.
- The requirement becomes ambiguous.
- Any change to a DO NOT TOUCH file is required.

Report format:
1. Summary of changes (one paragraph).
2. List of files edited.
3. Validation command outputs.
4. Any assumptions or unresolved issues.

Quality checklist

  • The objective is one sentence and one outcome.
  • Every relevant file is labeled read-only or editable.
  • Protected files are explicitly listed as do-not-touch.
  • Validation commands can be run by a human to verify the result.
  • Done criteria are yes/no verifiable.
  • Stop conditions prevent silent drift.

Common mistakes

  • Vague objective. Consequence: the agent produces plausible but wrong work.
  • No constraints. Consequence: the agent modifies files that should stay untouched.
  • Missing validation. Consequence: the change looks correct but breaks tests or links.
  • No stop conditions. Consequence: the agent iterates past the point of diminishing returns.

Agent instructions

When using this skill, first gather the objective, relevant files, constraints, validation commands, done criteria, and stop conditions. Do not start coding until the task card is complete. Separate facts from assumptions: existing file contents are facts; guesses about intent are assumptions. Produce the four deliverables. If a stop condition is reached, pause and report rather than continuing. Avoid generic summaries; cite specific files and command outputs.

Related skills

Related Atlas pages

Verification status and limitations

This skill is a public working interpretation of task-decomposition practice. It is not official vendor documentation. Adapt the template to your team's conventions and tools.