coding

Files (22)

• LICENSE.txt
• SKILL.md
• openai.yaml · agents/
• README.md · examples/
• comments.md · examples/
• control-flow.md · examples/
• functions.md · examples/
• variables-magic-values.md · examples/
• assertions.md · references/
• debugging.md · references/
• design.md · references/
• file-organization.md · references/
• foundations.md · references/
• go.md · references/
• implementation.md · references/
• no-comments.md · references/
• principles.md · references/
• refactoring.md · references/
• review.md · references/
• standards.md · references/
• type-system-discipline.md · references/
• verification.md · references/

SKILL.md (first lines)

# Coding

Use this skill as the entrypoint for software work. Keep this file in context,
then load the smallest relevant reference set for the task.

## Routing

- For any implementation, refactor, review, debug, or design task, read
  `./references/principles.md`. It owns the shared decision rules. The other
  references add task steps and point back there.
- For writing new code or extending behavior, read
  `./references/implementation.md`.
- For refactoring, cleanup, simplification, extraction, restructuring, or
  rewrite work, read `./references/refactoring.md`.
- For code review, PR review, diff critique, or risk assessment, read
  `./references/review.md`.
- For debugging, failing tests, regressions, runtime errors, CI failures, or
  bug fixes, read `./references/debugging.md`.
- For architecture, API design, module boundaries, dependency direction, or
  design-only discussion, read `./references/design.md`.
- For a consequential new data model, shared scaffold, or concurrent state,
  also read `./references/foundations.md`.
- For a new application or subsystem, source file placement, package or module
  placement, file moves, file splits, or layout discussion, read
  `./references/file-organization.md`.
- For Go code, application layout, package placement, or Go file organization,
  also read `./references/go.md`.
- For choosing the kind of check, especially for persistence, framework,
  service, CLI, or UI behavior, read `./references/verification.md`.
- Before calling a change done, prove the observable outcome in
  `./references/principles.md`. When a person can see or operate the result,
  also load the `eyes-on` skill and finish its loop.
- When the task is to create a project verification skill from the codebase,
  load `create-verification-skill`. When the task is to audit or update an
  existing one, load `maintain-verification-skill`.
- Whether to add, keep, or remove a test is the `test-audit` skill, including
  a test this task is about to write. It runs with this skill. The Tests
  section of `./references/principles.md` owns what a test protects and how it
  proves that.
- For shared code-quality rules, read `./references/standards.md` whenever
  writing or changing code, and as needed during review/design.
- For auditing a diff or files for comments, or deciding whether a comment
  should stay, read `./references/no-comments.md`.
- For designing types, reviewing a function signature, or writing code in a
  statically-typed language, read `./references/type-system-discipline.md`.
- For assertion strategy (invariant checks, debug-vs-production assert
  decisions, and fail-fast contracts), read `./references/assertions.md` when
  writing or reviewing code that validates internal assumptions.

If a loaded reference describes ordered phases, run every remaining phase until
its completion check. Load the next reference when that phase starts. Do not
stop after the first phase, including subtraction.

Do not commit between phases unless the user asked to land the work as
separate commits. When they did, commit each coherent unit with
the `git` skill ([commit reference](../git/references/commit.md)), then continue. Otherwise finish the remaining phases in
the working tree.

## Preserve The User's Mental Model

When code supports a user-facing workflow, model the implementation around the
user's intent rather than mirroring every field, option, or state in the backing
data model. Prefer one cohesive operation that expresses the user's decision
over several controls or helpers that expose internal structure. Keep advanced
state available behind the interaction that needs it, and make visible state
reversible and consistent with the user's expectations.

Before adding a control, state variable, or abstraction, identify the user
decision it owns. If an existing operation can express that decision directly,
extend it instead of creating a parallel path. Verify the resulting workflow at
its public boundary, including realistic content and the states that change the
user's next action.

## Comments Become Structure

Write no comments by default. Turn a would-be comment into a type, test or
lint rule. To audit existing comments, follow
[no-comments](./references/no-comments.md). Use the `encode-lessons` skill to choose the guard, and see
[standards](./references/standards.md#comments-and-docs).

## Custom Lint Rules

After fixing a bug or receiving a correction, ask whether a lint rule could
have caught it. If yes, follow the `lint-rules` skill to add it (or set up
lint if the repo has none). Stock linters are the baseline; recurring bad
patterns become custom rules with a failing example and a catalog entry.

End-of-task summary must include one of:
`lint rule: added <name>` or `lint rule: skipped: <why>`.

## Example Lookup

Use examples only when a rule decision is unclear.

- `./examples/README.md` indexes focused examples.
- Open one matching example file at a time.

From AnthonyPoschen/agent-skills, MIT.

More from AnthonyPoschen/agent-skills