Återställer 6136 filer från 7e33543^. Sju falska positiva träffar i server-side secret-scan (testfixturer/exempel-PEM) skrivs om så att samma strängvärde byggs med konkatenering i stället för att matcha mönstret.
3.8 KiB
3.8 KiB
Output skill template
The generated skill is a folder:
<api-name>/
SKILL.md # conventions + endpoint index; under ~400 lines
references/
<group-a>.md # full operation detail for one resource group
<group-b>.md
...
SKILL.md skeleton
---
name: <api-name>
description: >-
Consume the <API title> (<domain, e.g. "Swedish bookkeeping">, <base URL>).
Use when building an integration or app against <API name>: <the 5-8
resource nouns, e.g. "invoices, customers, payroll, reports">. Covers auth,
conventions, and every endpoint.
---
# <API title> integration
<Two or three sentences: what the API is, what a consumer can do with it,
and the one thing that makes it different from a generic REST API.>
## Auth and base URL
<Auth header with exact format, where keys are created, test vs live keys,
scopes if any, rate limits. A copy-pasteable curl that lists something.>
## Conventions
<The cross-cutting rules, each with a one-line example where the shape is not
obvious: response envelope, pagination, error envelope + how to react to the
common codes, idempotency, dry-run, expansion, async patterns. This section
is why the skill exists; spend your effort here.>
## Endpoint index
<One line per operation, grouped. Each group heading names its reference
file: "Full detail: references/<group>.md". Line format:
`METHOD /path : summary [scope:x risk:y idempotent dry-run]`>
## Gotchas
<Only entries that are true and non-obvious: verified live mismatches,
sharp edges from the spec's own pitfall notes that apply across endpoints,
domain rules a generic developer would violate. No padding; delete this
section rather than fill it with restatements.>
## Verification
<Either: "Verified live on <date> against <base URL>: <what was called>."
Or: "Generated from spec, NOT yet verified live. Before first use run:
<smoke-test curl commands>.">
references/.md skeleton
# <Group> endpoints
<One or two sentences: what this resource is and the state machine if any
(e.g. draft -> sent -> paid). Cross-reference sibling groups.>
<For each operation:>
### `METHOD /path`
**<Summary>.**
`scope:<s> · risk:<r> · idempotent · dry-run`
<Description from the spec, kept if it earns its lines: use-when,
do-not-use-for, pitfalls.>
<Parameters table if any beyond path ids.>
Request body: (writes only)
```ts
{ condensed: "typescript-ish" }
Response 200:
{ condensed: "typescript-ish" }
<For the 2-3 most-used operations in the group: a worked example with a realistic request and a real (redacted) or spec-example response.>
## Quality checklist
Grade the generated skill against every item. Fix failures before delivering.
1. **First-call test**: could an agent with only SKILL.md (no references) make
a correct authenticated list call? Auth format, base URL, and envelope must
be sufficient.
2. **Trigger test**: does the frontmatter description name the API, its
domain, and its resource nouns? An agent that has never seen this skill
must match it from a prompt like "add <API> invoicing to our app".
3. **Coverage test**: every operation in the spec appears exactly once in the
endpoint index, and every index group has a reference file.
4. **Restatement test**: does SKILL.md contain anything an agent would learn
anyway from one endpoint call? Cut it.
5. **Convention test**: pagination, error handling, and idempotency are
documented as rules, not repeated per endpoint.
6. **Honesty test**: every example response is real or clearly marked as
spec-derived; the Verification section says what was and was not tested.
7. **Size test**: SKILL.md under ~400 lines; no reference file over ~700.
8. **Write-safety test**: destructive or high-risk operations are visibly
marked so an agent knows to confirm before calling.