spec-change
Skill9 starsChanged 5 days agoApache-2.0View on GitHub
Change a Fishhawk workflow/plan schema or REST API contract, including embedded mirrors, generated references and version advertising.
1 other project uses a version of this.
Adopted by
Most recently taken up by
- yisean/claude-spec-skillstheir own version, first seen Jun 15, 2026
Other versions1 project uses a version of this.
Word for word · 0
None found.
Edited · 0
None found.
Wrote their own version · 1
- yisean/claude-spec-skills★ 0same name
How matches are found. Word for word: the exact same text. Edited: shares passages with this file (“99% same” means 99% of its five-word phrases also appear here; 10% or more counts). Their own version: similar meaning, or, weakest, the same name. We can’t tell which project had it first. Projects are counted among the 200 most-starred candidates, and mentions are links to the repository we found, up to 50 per site, so both counts are a floor.
In this repository11 other files it gives its agents.
- AGENTS.mdAGENTS.md
- CLAUDE.mdCLAUDE.md
- deploy-localSkill
- dev-cleanSkill
- diagnose-redSkill
- frontend-checkSkill
- new-go-moduleSkill
- record-adrSkill
- sync-mainSkill
- teardown-localSkill
- verify-gateSkill
The file
We split this skill into the rules it gives an agent
5 rules. About 0 are common, 0 are distinctive, and 5 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈0
Distinctive · estimate
This author's own choices. Worth a look.
5
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Very specific: line 28
Treat fishhawk validate (without the flag) as the authority.
- Very specific: line 30
add it to the plan validator's recognized set (backend/internal/plan/)
- Very specific: line 35
Add docs/spec/workflow-vN.schema.json, then run scripts/sync-schemas.
- Very specific: line 37
Add EmbeddedSchemaHashVN() plus the workflow-vN entry in the /healthz schemas map (backend/internal/server/handlers.go).
- Very specific: line 50
Run the verify-gate skill.
≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Change a schema or API contract
Canonical sources live in docs/spec/ (schemas + reference docs) and docs/api/ (OpenAPI). Each is mirrored or rendered into several places, and CI fails on every one that's missed.
1. Classify the change first
- Additive. A new optional field within the current major. Proceed.
- Breaking. A new required field, a removed field, or a narrowed type, in an existing major. Don't do it in place: bump the major (
workflow-vN+1,standard_v2).- For a field meant to become required later, add it optional and annotate it with
"x-intended-required": true. - Declare the soak window in the PR body under
## Notes.
- For a field meant to become required later, add it optional and annotate it with
State the classification to the user before editing.
2. Edit and propagate (workflow / plan schemas)
- Edit the canonical
docs/spec/<name>.schema.jsonand its reference docdocs/spec/<name>.md. For the workflow spec,docs/spec/workflow-v2.mdis the complete reference for the live major. scripts/sync-schemasmirrors the change intobackend/internal/spec/schemas/andcli/internal/spec/schemas/(and the plan mirrors). Commit the mirrors with it.scripts/gen-site-referencere-renders the generated regions ofsite/src/content/docs/reference/*.md. Edit only outside theBEGIN/END GENERATEDmarkers.- Validate the examples:
check-jsonschema --schemafile docs/spec/<schema> <example.yaml>- A workflow-v2 doc using
defaults/extendsmust go through the product validator:fishhawk validate --emit-resolved <yaml> | check-jsonschema --schemafile docs/spec/workflow-v2.schema.json --default-filetype yaml -Treatfishhawk validate(without the flag) as the authority.
- Version advertising. For a new version string:
- add it to the plan validator's recognized set (
backend/internal/plan/) - inspect existing schema-advertising surfaces; backend
/healthzadvertises workflow schema hashes (see the new-major steps). Do not introduce a speculative runner endpoint as part of this change.
- add it to the plan validator's recognized set (
A NEW workflow major (also)
- Add
docs/spec/workflow-vN.schema.json, then runscripts/sync-schemas. Theworkflow-v*glob routes it; no script edit is needed. - Append
{Major: N, Path: …}toembeddedSchemasin bothbackend/internal/spec/parse.goandcli/internal/spec/spec.go. Without it, the validator fails closed on the new major. - Add
EmbeddedSchemaHashVN()plus theworkflow-vNentry in the/healthzschemasmap (backend/internal/server/handlers.go). - Register the mirror set as a surface-sweep pattern in
backend/internal/server/surface_sweep.go. - Bumping
.fishhawk/workflows.yaml'sversion:major makesscripts/dev up/reloadprint the schema-major MCP banner. Expect it.
3. REST API changes
- Source of truth:
docs/api/v0.openapi.yaml. Update the human companiondocs/api/v0.mdwith it. - Lint with the pinned version:
npx -y @redocly/cli@2.31.5 lint --config docs/api/redocly.yaml docs/api/v0.openapi.yaml - Re-run
scripts/gen-site-reference;reference/api.mdis generated from it. - A tightened auth check also needs the PR-body Auth change checklist (
fishhawkd token migratedry-run inventory). See change checklists.
4. Gate
Run the verify-gate skill. Its schema-sync step catches a missed mirror, and the site-reference drift test catches a missed regeneration.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

