Add SKILL.md and copilot-instructions.md for core CAPs

.claude/skills/core/SKILL.md

@@ -0,0 +1,59 @@
+---
+name: core
+description: 'Work on Stellar Core Advancement Proposals in core/. Use when editing CAP documents, checking CAP status fields, or syncing a CAP preamble Status with the corresponding entry in core/README.md.'
+argument-hint: 'CAP number or core/ task, for example: sync CAP-0082 status with core/README.md'
+---
+
+# Core CAP Workflow
+
+Use this skill for tasks in `core/`, especially when creating, editing, reviewing, or validating Core Advancement Proposals (CAPs).
+
+## When to Use
+
+- Edit a CAP under `core/cap-xxxx.md`.
+- Create a new CAP draft from `cap-template.md`.
+- Verify that a CAP's `Status` field matches the corresponding entry in `core/README.md`.
+- Update a CAP's status and keep the index tables in `core/README.md` synchronized.
+
+## Sources of Truth
+
+- Use `core/README.md` for the allowed CAP statuses and how CAPs are grouped in the proposal tables.
+- Use `cap-template.md` for the default structure of new CAP drafts.
+- Use the target CAP document for the exact preamble fields, terminology, and section structure already in use.
+
+## Status Synchronization Rules
+
+When a task involves a CAP status:
+
+1. Read the CAP preamble in `core/cap-xxxx.md` and find the `Status` line.
+2. Read the matching CAP row in `core/README.md`.
+3. Compare the status text exactly, including values such as `Draft`, `Accepted`, `Implemented`, `Final`, `Rejected`, `Awaiting Decision`, `FCP: Acceptance`, `FCP: Rejection`, or `Superseded: ...`.
+4. If the status is intended to change, update both places in the same edit.
+5. If the new status changes which README table the CAP belongs in, move the row to the correct section instead of only changing the text in place.
+6. Keep the CAP title, number, and author fields aligned with the corresponding README row when you touch the status entry.
+7. If there is a mismatch but the intended new status is not clear from the task or surrounding context, stop and ask rather than guessing which side is correct.
+
+## CAP Editing Rules
+
+- Preserve preamble fields and their meaning: `CAP`, `Title`, `Author` or working group fields, `Status`, `Created`, `Discussion`, and `Protocol version`.
+- Follow the existing section structure of the target CAP. Older CAPs may not match the current template exactly.
+- Keep protocol language normative and concrete. Describe exact ledger, transaction, operation, XDR, or meta effects.
+- Make downstream effects explicit when relevant, especially for validators, Horizon/RPC consumers, and SDKs.
+- Keep compatibility, migration, and security sections specific and actionable.
+- Prefer surgical edits over broad rewrites.
+
+## Procedure
+
+1. Read `core/README.md`, `cap-template.md` if relevant, and the target `core/cap-xxxx.md`.
+2. Determine whether the task is a drafting task, a status-sync task, or both.
+3. For status-sync tasks, update the CAP preamble and `core/README.md` together.
+4. For status transitions, confirm the CAP row is located in the correct README section.
+5. Preserve existing Markdown style, heading levels, and table formatting.
+6. Before finishing substantial Markdown edits, run `./bin/prettier.sh` when appropriate.
+
+## Do Not
+
+- Do not change unrelated CAPs while fixing one CAP's status.
+- Do not silently infer a new status from partial evidence.
+- Do not mix SEP process guidance into `core/` tasks unless explicitly requested.
+- Do not rewrite accepted or final CAPs beyond the requested change.

.github/copilot-instructions.md

@@ -0,0 +1,51 @@
+# Copilot Instructions for stellar-protocol
+
+This repository contains protocol specification documents, not application source code. Treat Markdown in this repository as normative technical documentation that must stay precise, internally consistent, and easy to review.
+
+## Primary Focus: `core/`
+
+When a task involves files under `core/`, optimize for Core Advancement Proposals (CAPs).
+
+- Treat `core/README.md` as the source of truth for CAP statuses, process, and protocol goals.
+- Treat `cap-template.md` as the default structure for new CAP drafts.
+- Preserve the intent and historical context of accepted or final CAPs. Prefer surgical edits over rewriting large sections.
+- Keep changes specific to the proposal being edited. Do not silently harmonize unrelated CAPs.
+
+## CAP Authoring Rules
+
+When creating or editing a CAP in `core/`:
+
+- Preserve the preamble fields and their meaning: `CAP`, `Title`, `Author` or working group fields, `Status`, `Created`, `Discussion`, and `Protocol version`.
+- Follow the existing section structure in the target document. Older CAPs may use a simpler structure than the current template.
+- For new drafts, start from `cap-template.md` and keep the main sections in order unless there is a clear repository precedent to do otherwise.
+- Keep technical statements normative and concrete. Avoid vague wording such as "improves things" or "makes it better" without specifying semantics.
+- Distinguish clearly between motivation, specification, rationale, compatibility impact, security concerns, and implementation status.
+- If a proposal changes protocol behavior, explain exact ledger, transaction, operation, XDR, or meta effects rather than describing only high-level intent.
+- When describing protocol transitions, call out downstream impacts on validators, Horizon/RPC consumers, SDKs, and other ecosystem tooling when relevant.
+- For compatibility or migration sections, be explicit about what breaks, what remains valid, and what downstream systems must update.
+- For security sections, include concrete risks, invariants, abuse cases, or a short explanation of why there are no material new security concerns.
+- For test cases, prefer specific scenarios and edge cases over generic placeholders.
+
+## Style and Editing Expectations
+
+- Keep Markdown plain, readable, and review-friendly.
+- Preserve existing heading levels, capitalization style, and table formats within the edited file.
+- Keep terminology consistent with Stellar protocol language already used in `core/README.md` and nearby CAPs.
+- Use fenced code blocks for XDR, enum, struct, or protocol examples.
+- Do not introduce unnecessary prose, marketing language, or product framing.
+- Avoid changing historical status labels, dates, authorship, or protocol versions unless the task explicitly requires it.
+- When referencing other proposals, use the repository's existing `CAP-xxxx` naming and relative links where appropriate.
+
+## Scope Discipline
+
+- If the user asks for help on a specific CAP, limit edits to that CAP and directly related supporting files.
+- If the task is ambiguous, prefer reading `core/README.md`, `cap-template.md`, and the target CAP before editing.
+- Do not infer implementation details that are not supported by the proposal text or task context.
+- If a requested change would alter protocol semantics, surface the semantic impact clearly in the document instead of hiding it in wording changes.
+
+## Repository Conventions
+
+- `core/` contains CAP documents.
+- `ecosystem/` contains SEP documents; do not mix SEP process guidance into CAP edits unless explicitly requested.
+- `contents/` may contain supporting assets for a specific CAP; keep references aligned with the corresponding CAP number.
+- Before concluding substantial Markdown edits, prefer the repository formatting command: `./bin/prettier.sh`.