feat(skills): ship a sync-markdown-code-blocks Agent Skill with TanStack Intent (#30)

[adrianbrowning]

Closes #30

Summary

The package now ships an Agent Skill, versioned with each release. TanStack Intent manages it.

 package.json                       devDependencies: @tanstack/intent 0.5.4 (exact), lockfile updated
+AGENTS.md                          intent-maintainer block (CLAUDE.md links to it)
+.github/workflows/check-skills.yml validates skills and recorded reviews on PRs (pinned SHA, contents: read)
+.intent/review-state.json          recorded source-review outcomes
+_artifacts/                        domain_map.yaml, skill_spec.md, skill_tree.yaml — library mdcode-ts 0.0.4, package packages/mdcode
 packages/mdcode/
+  skills/sync-markdown-code-blocks/
+    SKILL.md                       inspect → plan → diff → apply → check; regions/outline; --base & sourceRoot;
+                                   selection; extract; run/dump; approval rules for untrusted Markdown
+    references/json-results.md     envelope, exit codes, telling drift from breakage
+    references/transformers.md     --transform modules, update()/parse()/extract()
   package.json                     files += skills/sync-markdown-code-blocks; keywords += tanstack-intent
 packages/usage/tests/
+  skill-sync-markdown-code-blocks.test.ts   task grader (SKILL_TASK_DIR grades another directory)
+  skills/sync-markdown-code-blocks/          task.md + fixture

Decisions:

• One core skill. The commands work together in one inspect, plan, apply, check loop, so splitting them into one skill each would scatter the guidance. JSON results and transformers are conditional references.
• Package-only distribution (distribution.mode: none). Consumers run npx @tanstack/intent install. Repository and plugin exports can be added later.
• Claims come from the CLI, not the README. I verified every command shown against dist/main.js built from this revision. The package README disagrees with the CLI in places: list, run and dump take one file, --file is an exact match, and directories are never accepted. The skill follows the CLI, and I filed docs: CLI examples pass directories, globs and --file patterns that the CLI doesn't accept #54 for the README.
• Safety table. It splits commands that write or execute (approval needed) from those that only read. It also says that reads still follow file= inside the base, and that containment is check-then-use.

Evidence

• pnpm exec intent maintainer check --base origin/main: Validated 1 skill files — all passed, 0 authoring issue(s), 0 pending review item(s).
• Task check, skill-sync-markdown-code-blocks.test.ts:
  • accepts the skill's solution, update --apply --project;
  • rejects running only the plan;
  • rejects applying without the configuration's sourceRoot;
  • rejects changing the source to match the docs.
• Packed tarball contains package/skills/sync-markdown-code-blocks/{SKILL.md,references/json-results.md,references/transformers.md}, README.md, LICENSE and the 60 dist/ files. _artifacts/ is not in it, and exports and bin are unchanged.
• Consumer run: in a temp project with the packed tarball and intent install, a separate agent got the task text and a disposable project, set up with intent install → "Enable all" (intent.skills: ["*"], broader than a consumer should use; a single-skill selection was not tested). It ran intent list, then intent load mdcode-ts#sync-markdown-code-blocks, then update --diff --project, then update --apply --project. The unchanged grader passed on its result (SKILL_TASK_DIR=…).
  • That agent also read this repository's own agent instructions and edited an unrelated file here, which I reverted. So this is not an isolated fresh-consumer run. skill_spec.md records it as such.
  • Discovery is unverified.
• pnpm check passes (pre-push).

Merge Danger

Door: two-way

Blast Radius: package contents

The npm package gains skills/ and a tanstack-intent keyword. exports, bin and runtime code are unchanged. A new Check Skills workflow runs on PRs. It fails a PR that changes a mapped source (commands, parser, region code, README, examples, the task check) without recording a review: pnpm exec intent maintainer review --json then --record, as AGENTS.md explains. The minor bump file announces the skill.

[github-actions]

The changes in this PR will be included in the next version bump.

Minor releases

• mdcode-ts 0.0.4 → 0.1.0

Bump files in this PR

• agent-skill.md (view diff) (edit)

Click here if you want to add another bump file to this PR

---

This comment is maintained by bumpy.

[github-actions]

⚠️ ESLint Check Warnings

Click to see details

Style

> mdcode@0.0.1 lint:s /home/runner/work/mdcode-ts/mdcode-ts
> pnpm -r lint:s

Scope: 2 of 3 workspace projects
packages/mdcode lint:s$ eslint --config .eslintrc.style.json "src/**/*.{j,t}s{,x}" --cache --max-warnings=0
packages/mdcode lint:s: [baseline-browser-mapping] The data in this module is over two months old.  To ensure accurate Baseline data, please update: 'npm i baseline-browser-mapping@latest -D'
packages/mdcode lint:s: Done
packages/usage lint:s$ eslint --config .eslintrc.style.json "{tests,fixtures,examples}/**/*.{j,t}s{,x}" --cache --max-warnings=0
packages/usage lint:s: [baseline-browser-mapping] The data in this module is over two months old.  To ensure accurate Baseline data, please update: 'npm i baseline-browser-mapping@latest -D'
packages/usage lint:s: Done

Correctness

> mdcode@0.0.1 lint:esl /home/runner/work/mdcode-ts/mdcode-ts
> pnpm -r lint:esl

Scope: 2 of 3 workspace projects
packages/mdcode lint:esl$ eslint "src/**/*.{j,t}s{,x}" --cache --max-warnings=0
packages/mdcode lint:esl: [baseline-browser-mapping] The data in this module is over two months old.  To ensure accurate Baseline data, please update: 'npm i baseline-browser-mapping@latest -D'
packages/mdcode lint:esl: Done
packages/usage lint:esl$ eslint "{tests,fixtures,examples}/**/*.{j,t}s{,x}" --cache --max-warnings=0
packages/usage lint:esl: [baseline-browser-mapping] The data in this module is over two months old.  To ensure accurate Baseline data, please update: 'npm i baseline-browser-mapping@latest -D'
packages/usage lint:esl: Done

View workflow run

[github-actions]

⚠️ ESLint Check Warnings

Click to see details

Style

> mdcode@0.0.1 lint:s /home/runner/work/mdcode-ts/mdcode-ts
> pnpm -r lint:s

Scope: 2 of 3 workspace projects
packages/mdcode lint:s$ eslint --config .eslintrc.style.json "src/**/*.{j,t}s{,x}" --cache --max-warnings=0
packages/mdcode lint:s: [baseline-browser-mapping] The data in this module is over two months old.  To ensure accurate Baseline data, please update: 'npm i baseline-browser-mapping@latest -D'
packages/mdcode lint:s: Done
packages/usage lint:s$ eslint --config .eslintrc.style.json "{tests,fixtures,examples}/**/*.{j,t}s{,x}" --cache --max-warnings=0
packages/usage lint:s: [baseline-browser-mapping] The data in this module is over two months old.  To ensure accurate Baseline data, please update: 'npm i baseline-browser-mapping@latest -D'
packages/usage lint:s: Done

Correctness

> mdcode@0.0.1 lint:esl /home/runner/work/mdcode-ts/mdcode-ts
> pnpm -r lint:esl

Scope: 2 of 3 workspace projects
packages/mdcode lint:esl$ eslint "src/**/*.{j,t}s{,x}" --cache --max-warnings=0
packages/mdcode lint:esl: [baseline-browser-mapping] The data in this module is over two months old.  To ensure accurate Baseline data, please update: 'npm i baseline-browser-mapping@latest -D'
packages/mdcode lint:esl: Done
packages/usage lint:esl$ eslint "{tests,fixtures,examples}/**/*.{j,t}s{,x}" --cache --max-warnings=0
packages/usage lint:esl: [baseline-browser-mapping] The data in this module is over two months old.  To ensure accurate Baseline data, please update: 'npm i baseline-browser-mapping@latest -D'
packages/usage lint:esl: Done

View workflow run