Coding-agent skill patterns

Coding agents are the sharpest packaging lesson

IDE assistants (Cursor, Claude Code, Copilot Workspace, and open-source clones) forced the industry to get serious about skills, tools, and context budgets in one tight loop. A coding agent must read a repo, plan edits, run linters, execute tests, and stop — all within latency and token limits users tolerate. That makes coding agents the best reference implementation for the skills module: procedures are concrete, failures are reproducible, and quality gates are objective.

The pattern you will mirror:

1. Skill — How we change code in this repo (style, test commands, PR conventions).
2. Tools — File read/write, shell, grep, test runner, linter — often via MCP or built-in host tools.
3. Harness — Validate → execute → verify (you deepen this in agentic workflow lessons).

This lesson closes the skills milestone by shipping one IDE-style skill wired into your host with MCP or local tools, plus lint/test gates.

What belongs in a coding skill

Separate stable repo conventions from session task context:

In the skill (durable):

• Package manager and test command (pnpm test, pytest -q)
• Lint/format commands and CI expectations
• Directory map ("business logic in src/, no edits to generated/")
• Edit discipline ("minimal diff," "match surrounding style," "no drive-by refactors")
• Failure handling ("if tests fail twice, stop and report")

In the prompt (session):

• Current ticket description
• Files user has open
• Branch name and PR link

In tools (executable):

• read_file, write_file, run_terminal_cmd
• run_linter, run_tests (wrappers with fixed cwd and timeout)

Callout — Cursor-style SKILL.md: Real IDE skills often include @ file references and explicit "when to use" triggers like "user asks to fix lint errors." Copy that shape; do not invent a incompatible format unless your host requires it.

Example structure: fix-failing-tests skill

## When to use
User reports test failures or CI red on a known branch.

## Procedure
1. Run `pytest path -q --tb=short` (never full suite unless asked).
2. Read failure output; identify ≤3 root causes.
3. Edit minimal files; do not change public API without approval.
4. Re-run failed tests only, then affected module suite.
5. Summarize: cause, fix, tests run.

## Examples
### Good
…annotated trace with one file changed…

### Bad
Agent refactors unrelated module "while here."

## Failure notes
- Flaky tests: rerun once, note flake in summary.
- Missing deps: run `make install`, do not pip install random packages.
- Snapshot tests: never auto-update snapshots without user confirmation.

Pair with tools that enforce cwd and timeout — unbounded test runs are how coding agents burn GPUs and trust.

Lint and test tools as guardrails

Skills tell the model what to do; tools prove it happened. Minimum viable harness for this lesson:

Return structured tool output:

{"exit_code": 1, "stdout_tail": "...", "failed_tests": ["test_refund"]}

The model reasons better over structured failure than 200 lines of raw log.

Stop conditions from the agent module apply: max edit iterations (e.g. 3), max test reruns, escalate to user on repeated failure.

Do not let the model skip lint "to save time" — encode in skill: "lint gate is mandatory before claiming done."

MCP vs in-process for coding tools

If you already built MCP in lesson 8.4, expose run_command through MCP with an allowlist (pytest, ruff, git diff, not rm -rf). Sandboxing is the point — coding agents are high-risk.

Allowlist pattern:

ALLOWED_PREFIXES=pytest,ruff,pnpm,npm,git diff,git status

Reject everything else at the server; log rejected commands for security review.

Milestone integration: skill pack + MCP + host

Closing this milestone means your portfolio demonstrates:

1. ≥2 skills authored and loadable dynamically (lessons 8.2–8.3).
2. MCP server (or documented equivalent) for at least one tool category (lesson 8.4).
3. Context budget logging on long runs (lesson 8.5).
4. One coding skill with lint/test pairing (this lesson).

Write milestone-8.md summarizing architecture diagram: router → skill load → tool calls → budget log. Include one successful trace and one failure you intentionally fixed.

Anti-patterns in coding skills

• Megaskill — Entire language reference in one skill; split by task (tests, lint, refactor).
• Secret leakage — ".env contains API_KEY=…" in examples; use placeholders.
• Unbounded shell — "run whatever command seems helpful."
• Style without examples — "write clean code" vs. showing a 10-line diff that matches repo conventions.

Engineering problem (staff framing)

Coding agents need repo maps, test oracles, and patch discipline packaged as skills.

Diagram — Coding agent skills

flowchart LR
  Map[Repo map skill] --> Edit[Edit skill]
  Edit --> Test[Test skill]
  Test --> Review[Review skill]

Precise definitions & mental model

Read/search/edit/test toolkits; diff-first workflows.

Tradeoffs — when to use what

Autonomous long runs vs short PR-sized tasks.

Failure modes (interview + on-call)

No tests; huge unrelated diffs; secret exfiltration.

Production & OSS practices

Branch isolation; CI required; skill evals on fixtures repos.

Micro-project: One IDE-style skill

Ship in your portfolio:

1. Author SKILL.md for one coding workflow (fix tests, add endpoint, or lint cleanup).
2. Wire lint + test tools (MCP or local) the skill references by exact command.
3. Run agent on a seeded bug; capture trace through lint/test gates to green.
4. Complete milestone doc tying together skills, MCP, budgets, and this coding skill.
5. Add eval case: same bug fix must pass tests; store prompt + expected test exit code.

Acceptance: README "Milestone 8" section runnable in <15 minutes on a clean clone.

Checklist

• IDE-style coding skill with examples and failure notes
• Lint and test tools integrated with structured output
• Successful end-to-end trace on seeded task
• Milestone 8 summary doc with architecture diagram
• Module README updated; smoke check passes