Skip to content

docs(education): add writing-safe-skills page as step 5 in the learning progression#755

Merged
potiuk merged 1 commit into
apache:mainfrom
justinmclean:education-writing-safe-skills
Jul 5, 2026
Merged

docs(education): add writing-safe-skills page as step 5 in the learning progression#755
potiuk merged 1 commit into
apache:mainfrom
justinmclean:education-writing-safe-skills

Conversation

@justinmclean

Copy link
Copy Markdown
Member

Summary

Insert a new authoring-focused stage between "your first skill" (step 4) and "eval-driven development" (now step 6). The page covers five copy-ready patterns that hold PRINCIPLE 0 (data-not-instructions) and PRINCIPLE 1 (sandbox) in every skill body: explicit read/act boundary in step headings, the injection-flag idiom, data-only write steps, routing private bytes through the Privacy-LLM gate, and draft-before-post confirmation. Includes an annotated end-to-end example, a "Check your understanding" block, and forward/back cross-links. Updates the progression table in README.md (steps 5→6→7→8→9) and fixes the step references in your-first-skill.md, eval-driven-development.md, and agentic-work.md.

Generated-by: Claude (claude-sonnet-4-6)

Type of change

  • Skill change (.claude/skills/<name>/) — eval fixtures updated below
  • Tool / bridge contract (tools/<system>/*.md)
  • Python package (tools/*/ with pyproject.toml)
  • Groovy reference impl
  • Cross-cutting (RFC, AGENTS.md, sandbox, privacy-LLM)
  • Documentation (docs/, README.md, CONTRIBUTING.md)
  • Project template (projects/_template/)
  • CI / dev loop (prek, workflows, validators)
  • Other:

Test plan

  • prek run --all-files passes
  • For Python packages touched: uv run pytest / ruff check / mypy passes
  • For Groovy bridges touched: command-line invocation tested end-to-end
  • For skill changes: eval suite passes for the affected skill
    (PYTHONPATH=tools/skill-evals/src python3 -m skill_evals.runner tools/skill-evals/evals/<skill>/)
  • For skill behaviour changes: a new or updated eval fixture is included in this PR
    (a regression test for the bug fixed / the behaviour added — see CONTRIBUTING.md)
  • Other:

@justinmclean justinmclean self-assigned this Jul 5, 2026
…ng progression

Insert a new authoring-focused stage between "your first skill" (step 4) and
"eval-driven development" (now step 6). The page covers five copy-ready
patterns that hold PRINCIPLE 0 (data-not-instructions) and PRINCIPLE 1 (sandbox)
in every skill body: explicit read/act boundary in step headings, the
injection-flag idiom, data-only write steps, routing private bytes through the
Privacy-LLM gate, and draft-before-post confirmation. Includes an annotated
end-to-end example, a "Check your understanding" block, and forward/back
cross-links. Updates the progression table in README.md (steps 5→6→7→8→9) and
fixes the step references in your-first-skill.md, eval-driven-development.md,
and agentic-work.md.

Generated-by: Claude (claude-sonnet-4-6)
@potiuk potiuk force-pushed the education-writing-safe-skills branch from a3cb680 to f0c3129 Compare July 5, 2026 18:51

@potiuk potiuk left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Reviewed and merging — the progression renumbering is done correctly and consistently: writing-safe-skills slots in as step 5 and every page carrying a hardcoded step number (README, your-first-skill, eval-driven-development, agentic-work, and the new page) is updated to match. Good new page, too — solid coverage of the data-not-instructions / sandbox / Privacy-LLM authoring patterns.

I pushed a small fixup (you're still the commit author): the prose recaps at the top of english-as-code.md and contributing.md now include the new step ("…written a skill, learned to keep it safe, tested it with evals…" and "…how to write a skill, keep it safe, and test it with evals…"), so those "by now you have…" summaries stay complete. Those two pages carry no step numbers, so nothing else in them needed touching.

One thing from my first read that turned out to be a non-issue: the ## Step 1 — Fetch and redact line is inside a fenced ```markdown code block (it's a skill example), so it's correctly not a real TOC entry — no change needed there.

All green. Thanks!

@potiuk potiuk merged commit 80242f0 into apache:main Jul 5, 2026
8 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants