Урок 6.3. Как писать SKILL.md

Как агенту надежно выполнять этот повторяемый тип работы?

Skill = trigger + reusable procedure + context routing + constraints + verification + output contract

skills/
└── create-api-endpoint/
    └── SKILL.md

skills/
└── create-api-endpoint/
    ├── SKILL.md
    ├── references/
    │   ├── api-style.md
    │   └── error-handling.md
    ├── scripts/
    │   └── verify-api-change.sh
    └── assets/
        └── endpoint-test.template.ts

---
name: create-api-endpoint
description: Add or modify REST API endpoints in an existing backend project. Use when Codex needs to implement controller/route changes, request validation, service integration, API tests, or OpenAPI contract updates for a specific endpoint.
---

# Create API Endpoint

## Procedure

1. Read the feature specification and acceptance criteria.
2. Find the closest existing endpoint pattern in the repository.
3. Identify affected layers: route, controller, service, validation, persistence, tests, contract.
4. Add or update tests before implementation when practical.
5. Implement the smallest scoped change that satisfies the specification.
6. Run targeted tests and any contract checks available in the project.
7. Report changed files, verification commands, and acceptance criteria status.

---
name: create-api-endpoint
description: Add or modify REST API endpoints in an existing backend project. Use when Codex needs to implement controller/route changes, request validation, service integration, API tests, or OpenAPI contract updates for a specific endpoint.
---

Если trigger conditions спрятаны внутри body, агент может не открыть skill вообще.

---
name: api
description: Helps with API work.
---

---
name: create-api-endpoint
description: Add or modify REST API endpoints in an existing backend service. Use when a task requires route/controller changes, request validation, service-layer integration, API tests, OpenAPI updates, or endpoint-level acceptance criteria. Do not use for generic API design discussions or external API client troubleshooting.
---

verb-noun
verb-domain-noun
tool-action-object

Если skill нельзя уверенно вызвать одной фразой "Use <name> to ...",
скорее всего имя слишком размытое.

---
name: skill-name
description: One precise sentence about what the skill does. Use when Codex needs to ... Include concrete trigger contexts. Add negative trigger if confusion is likely.
---

# Skill Title

## Purpose

Explain the workflow this skill standardizes in 2-4 sentences.

## Inputs

- Required input 1.
- Required input 2.
- Optional input.

## Preconditions

- What must be known before editing.
- Which project files or specs should exist.
- Which permissions or tools may be needed.

## Context To Read

1. Read the task or feature specification.
2. Read the nearest existing implementation pattern.
3. Read linked references only when the task matches them.

## Procedure

1. Step one.
2. Step two.
3. Step three.

## Constraints

- Do not change unrelated modules.
- Do not introduce new dependencies unless the task explicitly requires it.
- Preserve public contracts unless the spec says otherwise.

## Verification

- Run the most targeted tests first.
- Run broader checks when the change touches shared behavior.
- If a check cannot be run, explain why and describe residual risk.

## Failure Handling

Stop and ask for clarification when:

- Required acceptance criteria are missing.
- The requested change conflicts with an existing contract.
- The safe implementation path requires destructive migration or production access.

## Output

Return:

- summary of changes;
- changed files;
- verification commands and results;
- acceptance criteria status;
- unresolved risks or follow-up tasks.

Какую повторяемую работу нормализует этот skill?

## Purpose

Use this skill to implement backend API endpoints with tests and contract checks. The goal is to keep endpoint work scoped, aligned with existing project architecture, and verifiable through targeted tests.

## Purpose

APIs are very important in modern software development. REST APIs allow clients and servers to communicate. This skill explains what APIs are, why validation matters, and how backend engineering works.

## Inputs

- Feature specification or issue with endpoint behavior.
- HTTP method and path, if already known.
- Request and response schema.
- Authentication and authorization expectations.
- Acceptance criteria.
- Existing API contract location, if the project has one.

Сделай endpoint для проектов.

Use `create-api-endpoint`.
Spec: specs/features/create-project.md.
Endpoint: POST /api/projects.
Add request validation, service test, API test, and OpenAPI update.
Do not change authorization rules outside this endpoint.

## Preconditions

- The repository has an existing API layer or routing convention.
- The requested endpoint behavior is specified through acceptance criteria.
- The target test framework can be discovered from existing tests.
- Authorization behavior is explicit in the spec or in an existing analogous endpoint.

## Context To Read

1. Read the user task and linked feature specification first.
2. Find 1-2 closest existing endpoint implementations.
3. Read only the framework-specific reference if the project pattern is ambiguous:
   - `references/express.md` for Express projects.
   - `references/fastapi.md` for FastAPI projects.
   - `references/rails.md` for Rails projects.
4. Do not load all references by default.

Read the whole repository and all documentation before doing anything.

## Procedure

1. Read the feature specification and extract acceptance criteria.
2. Locate the closest existing implementation pattern.
3. Identify affected files before editing.
4. Add or update the smallest useful test that would fail without the change.
5. Implement the minimal code change.
6. Update public contracts or documentation only when behavior changed.
7. Run targeted verification.
8. If targeted verification passes and the change touches shared code, run broader checks.
9. Report changed files, checks, and acceptance criteria status.

Be careful and write high-quality code.

Before adding a new abstraction, search for an existing local pattern. Reuse the existing pattern unless it conflicts with the specification or introduces duplicated behavior.

## Constraints

- Keep changes scoped to the requested behavior.
- Do not rewrite unrelated modules.
- Do not add dependencies unless the specification or existing project pattern requires them.
- Preserve backward-compatible API behavior unless the task explicitly changes the contract.
- Prefer existing local conventions over introducing a new architecture style.
- Do not modify generated files manually unless the project expects manual edits there.

Make the code good.

Do not introduce a new service abstraction if an existing service layer already handles the same entity.

## Verification

1. Run the most targeted unit or integration test for the changed behavior.
2. Run API contract validation if the endpoint contract changed.
3. Run lint/typecheck if the project has cheap commands for them.
4. Run broader tests when shared validation, authentication, or persistence code changed.
5. If a command cannot be run, report the command, the reason, and the residual risk.

## Verification

Use `scripts/verify-api-change.sh` when the project has Node dependencies installed. Pass the endpoint test path as the first argument.

If the script fails because dependencies are missing, do not install packages without user approval. Fall back to reading package scripts and report what could not be verified.

## Failure Handling

Stop and ask for clarification when:

- The endpoint changes authentication or authorization and the expected policy is not specified.
- The request or response schema is ambiguous.
- The task requires a destructive database migration.
- Existing tests contradict the feature specification.
- The safe path requires credentials, production access, or external service writes.

When blocked by missing dependencies or unavailable services, continue with static inspection only if it can still produce useful progress. Report the limitation clearly.

## Output

Return:

- concise implementation summary;
- changed files;
- tests or checks run, with results;
- acceptance criteria status;
- known limitations or follow-up tasks.

Use the `create-api-endpoint` skill.

Task: implement POST /api/projects.
Spec: specs/features/project-create.md.
Acceptance criteria: validate name, create project for current user, return 201 with project id.
Constraints: do not change existing authorization middleware.
Verification: add or update API tests and run the targeted test command.

Use the `fix-bug-with-regression-test` skill.

Bug: password reset tokens can be reused after successful reset.
Reproduction: specs/bugs/reusable-reset-token.md.
Expected behavior: consumed token must be rejected.
Start with a failing regression test, then implement the smallest fix.

Use the `review-code-against-spec` skill.

Review the current diff against specs/features/team-invitations.md.
Focus on behavioral mismatches, missing tests, authorization gaps, and compatibility risks.
Return findings first, ordered by severity, with file and line references.

Use the `create-db-migration` skill.

Task: add `last_seen_at` to users.
Compatibility: existing rows must remain valid.
Runtime requirement: deployment should not require downtime.
Verification: run migration tests or the project's schema check if available.

Use the `build-frontend-form-flow` skill.

Task: add the project creation form.
Spec: specs/features/project-create.md.
Requirements: validation errors, loading state, success navigation, keyboard-accessible controls.
Match existing design system patterns.
Run targeted UI/component tests if available.

Analyze the repository and the last 10 planned development tasks.
Propose 3-5 candidate skills that would reduce repeated prompting.
For each skill, include: name, trigger description, workflow it standardizes, required references/scripts/assets, and why it should not be a rule or tool.
Do not create files yet.

Analyze the repository docs, task plan, and existing development patterns.
Find workflows that are repeated enough to become skills.
Return a table with candidate skill name, trigger, inputs, procedure outline, verification, and required supporting files.
Do not write the skills yet.

Write `skills/create-api-endpoint/SKILL.md`.

The skill should help an AI coding agent add or modify REST endpoints in this repository.
Include frontmatter with `name` and `description`, then Purpose, Inputs, Preconditions, Context To Read, Procedure, Constraints, Verification, Failure Handling, and Output.
Keep the skill concise and operational. Do not include generic REST API theory.

Review this skill description as a trigger.
Make it specific enough that an agent will use the skill for the right tasks and avoid it for unrelated tasks.
Include concrete use cases and negative triggers when helpful.
Do not change the body yet.

Review this SKILL.md for context bloat.
Identify content that should stay in SKILL.md and content that should move to `references/`, `scripts/`, or `assets/`.
Return the proposed file structure and explain the routing rules the skill should include.

Improve the Verification and Failure Handling sections of this developer skill.
Make verification command-oriented where possible, but keep it adaptable to different project test frameworks.
Specify what the agent should report when a check cannot be run.

Use the skill at `skills/create-api-endpoint` to implement the scenario in `specs/features/project-create.md`.
Follow the skill exactly where applicable.
After finishing, report which parts of the skill were useful, ambiguous, missing, or too verbose.

---
name: create-api-endpoint
description: Add or modify REST API endpoints in an existing backend service. Use when a task requires route/controller changes, request validation, service-layer integration, API tests, OpenAPI contract updates, or endpoint-level acceptance criteria. Do not use for generic API design discussions or external API client troubleshooting.
---

# Create API Endpoint

## Purpose

Use this skill to implement REST API endpoint changes in a controlled, testable way. The skill standardizes how to move from feature specification to code, tests, contract updates, and verification while preserving existing project architecture.

## Inputs

- Feature specification, issue, or task description.
- HTTP method and path, if known.
- Request and response schema, if known.
- Authentication and authorization expectations.
- Acceptance criteria.
- Existing API contract location, if the project has one.

## Preconditions

- A relevant backend API layer exists or the task explicitly asks to create one.
- Expected endpoint behavior is specified enough to test.
- Authorization behavior is explicit in the spec or inferable from a directly analogous endpoint.
- The project has discoverable test, lint, or typecheck commands.

## Context To Read

1. Read the task and linked specification first.
2. Find 1-2 closest existing endpoint implementations.
3. Inspect existing tests for the same API layer.
4. Read API style references only when local code does not answer the question:
   - `references/api-style.md` for response envelope, status codes, and error shape.
   - `references/error-handling.md` for validation and exception mapping.
5. Do not read unrelated modules or all reference files by default.

## Procedure

1. Extract endpoint behavior and acceptance criteria from the spec.
2. Identify affected layers: route, controller, validation, service, persistence, tests, contract.
3. Choose the nearest existing implementation pattern and reuse it.
4. Add or update the smallest meaningful test that would fail without the new behavior.
5. Implement the endpoint with minimal scoped changes.
6. Update API contract or generated types only when endpoint behavior changed.
7. Run targeted verification.
8. If shared validation, auth, or persistence code changed, run broader checks.
9. Compare the result against every acceptance criterion.

## Constraints

- Do not rewrite unrelated API modules.
- Do not introduce new dependencies unless the spec or existing project pattern requires them.
- Do not change authentication or authorization behavior without explicit requirements.
- Preserve existing response shapes unless the endpoint contract changes.
- Prefer existing local conventions over new abstractions.

## Verification

1. Run the targeted API or integration test for the endpoint.
2. Run contract validation if OpenAPI or generated API types changed.
3. Run lint/typecheck when cheap project commands exist.
4. If a check cannot be run, report the command, the reason, and the residual risk.

## Failure Handling

Stop and ask for clarification when:

- Request or response schema is ambiguous.
- Authorization requirements are missing.
- The spec conflicts with existing public API behavior.
- The change requires destructive migration or production credentials.

When tests cannot run because dependencies are missing, do not install packages unless the user approves. Continue with static inspection only if useful.

## Output

Return:

- concise summary of implementation;
- changed files;
- verification commands and results;
- acceptance criteria status;
- unresolved risks or follow-up tasks.

---
name: fix-bug-with-regression-test
description: Fix software bugs by reproducing the failure with a regression test before implementation. Use when a task describes incorrect behavior, a failing scenario, production bug, flaky edge case, or regression risk. Do not use for pure refactoring or feature work without a bug scenario.
---

# Fix Bug With Regression Test

## Purpose

Use this skill to turn a bug report into a verified fix. The workflow prioritizes reproducing the bug, writing a regression test, implementing the smallest fix, and proving the bug stays fixed.

## Inputs

- Bug description.
- Expected behavior.
- Actual behavior.
- Reproduction steps, logs, failing request, or affected test.
- Relevant issue, spec, or user report.

## Preconditions

- The bug can be described as observable behavior.
- There is enough context to create or identify a failing scenario.
- The project has a test layer suitable for regression coverage, or the absence of one can be reported.

## Context To Read

1. Read the bug report and expected behavior.
2. Find the code path that owns the incorrect behavior.
3. Find existing tests around that code path.
4. Read only relevant logs or fixtures needed to reproduce the bug.

## Procedure

1. Restate the bug as expected behavior versus actual behavior.
2. Identify the smallest observable failing scenario.
3. Add or update a regression test that fails without the fix.
4. Run the targeted test if practical and capture the failure.
5. Implement the smallest fix in the owning code path.
6. Run the regression test again.
7. Run nearby tests when shared behavior changed.
8. Check that the fix does not mask the symptom while leaving the cause.

## Constraints

- Do not rewrite broad modules while fixing a narrow bug.
- Do not delete or weaken existing tests to make the suite pass.
- Do not change public behavior beyond the expected fix unless the spec requires it.
- Prefer a focused regression test over only manual verification.

## Verification

- Targeted regression test passes.
- Nearby tests for the same module pass when available.
- The final report names the test that would fail without the fix.

## Failure Handling

Stop and ask for clarification when:

- Expected behavior is unclear.
- The bug requires production-only data that is not available.
- The reproduction steps contradict the specification.

If no test framework exists for the affected behavior, report that limitation and provide the closest available verification path.

## Output

Return:

- bug summary;
- regression test added or updated;
- implementation summary;
- verification results;
- remaining risk.

---
name: review-code-against-spec
description: Review code changes against a feature specification, task plan, or acceptance criteria. Use when Codex needs to inspect a diff for behavioral mismatches, missing tests, regressions, security-sensitive gaps, compatibility risks, or scope creep. Do not use for style-only proofreading.
---

# Review Code Against Spec

## Purpose

Use this skill to perform a behavior-focused engineering review. The review should prioritize correctness, regressions, missing tests, and mismatch with the specification over cosmetic feedback.

## Inputs

- Code diff or changed files.
- Feature specification, task description, or acceptance criteria.
- Relevant architecture constraints or ADRs.
- Test results, if available.

## Preconditions

- There is a concrete change to review.
- There is a spec, issue, task, or acceptance criteria to compare against.
- The reviewer can inspect changed files and relevant surrounding code.

## Context To Read

1. Read the spec or task first.
2. Inspect the diff and changed files.
3. Read surrounding code only when needed to confirm behavior.
4. Read tests related to the changed behavior.
5. Read ADRs or architecture constraints only when the change touches architecture boundaries.

## Procedure

1. Extract the intended behavior and acceptance criteria.
2. Map each acceptance criterion to changed code and tests.
3. Look for behavior that is missing, incorrectly implemented, or over-implemented.
4. Check error handling, boundary cases, authorization, data compatibility, and rollback risk where relevant.
5. Check whether tests would fail if the main behavior were broken.
6. Report findings first, ordered by severity.
7. Include file and line references for each finding when possible.
8. Keep summaries brief and secondary.

## Constraints

- Do not praise the code before listing findings.
- Do not report speculative issues without a concrete failure path.
- Do not require unrelated refactors.
- Do not treat style preferences as correctness findings.
- Do not rewrite the code during review unless explicitly asked.

## Verification

- Every finding should connect to spec mismatch, bug risk, missing test, compatibility issue, or security-sensitive behavior.
- If no issues are found, state that clearly and mention remaining test gaps or residual risk.

## Failure Handling

Ask for clarification when the diff or spec is missing. If only one is available, perform a limited review and label the limitation explicitly.

## Output

Return:

- findings first, ordered by severity;
- file and line references;
- open questions or assumptions;
- brief summary only after findings;
- test gaps or residual risk.

---
name: create-db-migration
description: Create safe database schema migrations for an existing application. Use when a task requires adding, changing, backfilling, indexing, or removing database fields, tables, constraints, or schema-derived types. Do not use for ad hoc SQL analysis or production database inspection.
---

# Create DB Migration

## Purpose

Use this skill to implement database schema changes with compatibility and verification in mind. The workflow should protect existing data, deployment safety, and application code that depends on the schema.

## Inputs

- Requested schema change.
- Affected entity or table.
- Compatibility requirements.
- Backfill expectations, if any.
- Rollback expectations, if any.

## Context To Read

1. Read the feature or migration spec.
2. Inspect existing migration naming and ordering.
3. Inspect current schema definition and affected model/entity code.
4. Inspect tests or fixtures that depend on the schema.

## Procedure

1. Classify the migration as additive, destructive, backfill, index, constraint, or rename.
2. Prefer backward-compatible additive changes when possible.
3. Create migration using the project's existing migration tool and naming convention.
4. Update application code and schema-derived types only as required.
5. Add or update tests for behavior affected by the schema.
6. Run migration verification and targeted tests.
7. Report deployment or rollback risks.

## Constraints

- Do not write destructive migrations without explicit approval.
- Do not assume production data shape unless documented.
- Do not manually edit generated schema artifacts unless the project expects it.
- Do not combine unrelated schema changes in one migration.

## Verification

- Run the project's migration check or schema diff command when available.
- Run targeted tests for affected models/services.
- If database tooling is unavailable, inspect migration syntax and report the unverified command.

## Failure Handling

Stop and ask for clarification when:

- The migration is destructive.
- Backfill behavior is unspecified.
- Existing data may violate a new constraint.
- The migration requires production credentials or live database access.

## Output

Return changed files, migration name, verification results, compatibility notes, and rollback concerns.

skills/create-api-endpoint/
├── SKILL.md
└── references/
    ├── express.md
    ├── fastapi.md
    ├── rails.md
    └── api-style.md

## Context To Read

Read `references/express.md` only for Express projects.
Read `references/fastapi.md` only for FastAPI projects.
Read `references/api-style.md` when local endpoint examples do not clarify response format.

skills/create-api-endpoint/
└── scripts/
    └── detect-api-test-command.sh

## Verification Helpers

Use `scripts/detect-api-test-command.sh` to suggest a targeted API test command when the project has known package scripts. Inspect the suggested command before running it. If the script cannot identify a command, fall back to reading package scripts and nearby test files.

Skill: inspect-db-safely
Tool/MCP: query read-only staging database

## Tool Usage

Use the read-only database query tool only after identifying the exact table and columns from the schema resource. Do not run write queries. If the tool is unavailable, continue with schema inspection and report that live data was not checked.

SKILL.md должен содержать essential workflow.
References должны содержать detailed knowledge.
Scripts должны содержать deterministic operations.
Assets должны содержать reusable files.

1. Add POST /api/projects.
2. Add PATCH /api/projects/:id.
3. Add GET /api/projects/:id/members.
4. Update endpoint validation after schema change.

Если агент видит только name + description, сможет ли он понять,
когда использовать этот skill?

Read the feature specification first.
Find the closest existing implementation pattern.
Run targeted tests before broad tests.

The agent may want to think about the specification.
Usually tests are nice.
It is important to be careful.

REST stands for Representational State Transfer.

Preserve the project's existing response envelope unless the specification explicitly changes it.

Verify everything works.

Run the targeted test for the changed behavior. If shared validation or auth code changed, run broader tests. If a command cannot be run, report the command and reason.

Summary, changed files, checks run, acceptance criteria status, risks.

Findings first, severity, file/line references, open questions, test gaps.

Decision, rationale, task breakdown, dependencies, verification plan.

references/
├── node-express.md
├── python-fastapi.md
└── ruby-rails.md

Read only the framework reference that matches the current repository.

create-api-endpoint
update-openapi-contract

Find the project's package scripts before choosing test commands.

Always run `/home/alex/tmp/project-old/run-tests.sh`.

The create-api-endpoint skill always creates a Project with name, description, owner, billing tier, and archived flag.

Read the feature specification to determine request and response fields.

Every SKILL.md repeats: "Use UTC for all timestamps."

Project rule: server timestamps must use UTC.

skills/create-api-endpoint/SKILL.md

---
name: create-api-endpoint
description: ...
---

# Create API Endpoint

## Purpose
...

## Inputs
...

## Preconditions
...

## Context To Read
...

## Procedure
...

## Constraints
...

## Verification
...

## Failure Handling
...

## Output
...

Добавьте `references/api-style.md` и напишите в `SKILL.md`,
когда агент должен читать этот reference.

skills/
  create-api-endpoint/
    SKILL.md
    references/
      api-style.md
    scripts/
      check-openapi.sh
  review-backend-change/
    SKILL.md
    references/
      review-rubric.md
  write-release-notes/
    SKILL.md