Skip to content

Add skern init instruction-snippet writer#87

Merged
devrimcavusoglu merged 1 commit into
mainfrom
feature/init-instructions
May 7, 2026
Merged

Add skern init instruction-snippet writer#87
devrimcavusoglu merged 1 commit into
mainfrom
feature/init-instructions

Conversation

@devrimcavusoglu
Copy link
Copy Markdown
Owner

@devrimcavusoglu devrimcavusoglu commented May 7, 2026

Summary

skern init can now write a skern usage snippet into agent instruction files (AGENTS.md, CLAUDE.md, .claude/CLAUDE.md) so agents use skern for ALL skill-related tasks instead of reading platform-native skill directories. Off by default — opt in with --instructions or accept the interactive prompt on a TTY.

This is the foundation for the planned shift from install/uninstall as the primary verb to a skern-as-source-of-truth model: instead of copying skill files to each platform's .claude/skills/, .cursor/skills/, etc., the agent is instructed to call skern skill <verb> directly.

What gets written

The base snippet (always included when opted in):

## Skern (skill management)

Use `skern` for ALL skill-related tasks — discovery, reading, creation, edits, removal. Run `skern --help` for the full command surface.

Plus the optional --tool-forming-loop section (off by default — agents that already create skills as needed shouldn't pay the context budget for an explicit directive):

### Tool-forming loop (always run first)

Before doing recurring or pattern-following work:

1. `skern skill search <topic>` — see if a relevant skill already exists.
2. Match with score ≥ 0.6: read it via `skern skill show <name>` and follow its body.
3. No match: `skern skill create <name>` — implement, and it's reusable next time.

Score ≥ 0.9 means a near-duplicate exists (creation blocked without `--force`) — read before forcing. Capacity warnings (≥20 project, ≥50 user) appear in JSON output; prefer editing existing skills once you see them.

Wrapped in <!-- skern:instructions:start --> / <!-- skern:instructions:end --> markers so re-running updates the block in place.

Flags

Flag Default Purpose
--instructions off write the snippet to discovered files
--tool-forming-loop off append the search-before-create section
--target <path> (none) explicit file targets, disables auto-discovery, repeatable
--print-instructions off print snippet to stdout instead of writing files

On a TTY without --json or instruction flags, skern init prompts for both choices (default No). Non-interactive runs honor flags only.

Implementation

  • internal/cli/instructions/ — new package. base.md + tool_forming.md are //go:embeded and assembled by Render(toolForming bool). Write() handles append, in-place update, and no-op cases via marker pattern.
  • internal/cli/init.go — flag wiring, prompt resolution. Prompts go to stderr so they don't collide with --print-instructions on stdout. Cross-platform TTY detection via os.ModeCharDevice (no third-party deps).
  • internal/output/types_skill.go — InitResult.Instructions (optional, omitted when not opted in) reports tool-forming choice, candidate targets, and per-file write actions.
  • scripts/smoke_test.sh — three new tests covering discover-and-write, default-off, and print-only.

Verified locally (Windows)

  • go test ./... — all packages pass
  • golangci-lint run ./... — 0 issues
  • bash scripts/smoke_test.sh ./skern — 65/65 (was 57)

Test plan

  • CI green on ubuntu-latest, macos-latest, windows-latest
  • lint job clean
  • Existing skern init behavior unchanged (no flags → just creates .skern/)
  • JSON consumers see no breaking change unless they opt in (Instructions field is omitempty)

Related

  • Discussed direction: skern as source of truth for skill management; install/uninstall demoted to opt-in import/export. This PR delivers the instruction-injection mechanism that makes that direction viable.

@devrimcavusoglu @claude
Add skern init instruction-snippet writer
122d6d0 
`skern init` can now write a skern usage snippet into agent instruction
files (AGENTS.md, CLAUDE.md, .claude/CLAUDE.md). The snippet teaches the
agent to use skern for ALL skill-related tasks instead of reading
platform-native skill directories. Off by default — opt in with
`--instructions` or accept the interactive prompt on a TTY.

Implementation:

- internal/cli/instructions/ — new package. Two embedded markdown
  fragments (base.md always included, tool_forming.md opt-in), assembled
  by Render(). The writer wraps output in <!-- skern:instructions:start -->
  / <!-- skern:instructions:end --> markers so re-running updates the
  block in place rather than appending duplicates. Auto-discovery probes
  AGENTS.md, CLAUDE.md, .claude/CLAUDE.md in cwd; user-level files
  require explicit --target.

- internal/cli/init.go — new flags: --instructions, --tool-forming-loop,
  --target (repeatable), --print-instructions. Interactive TTY prompts
  for both choices when flags don't fully resolve them; default No for
  both. Prompts go to stderr so they don't collide with
  --print-instructions on stdout. JSON mode never prompts.

- internal/output/types_skill.go — InitResult grows an optional
  `instructions` field reporting tool_forming choice, candidate
  targets, and per-file write actions (created/updated/unchanged/
  appended/printed).

- scripts/smoke_test.sh — three new tests cover the discover-and-write,
  default-off, and print-only flows.

- docs/reference/commands.md, CHANGELOG.md updated.

Tool-forming-loop is intentionally opt-in per user preference: agents
that already know to create skills as needed don't need the explicit
search-before-create directive in their context budget.

Verified locally: go test ./... pass, golangci-lint clean, 65/65 smoke
tests pass on Windows.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
@devrimcavusoglu devrimcavusoglu merged commit 3a2b09b into main May 7, 2026
5 checks passed
@devrimcavusoglu devrimcavusoglu deleted the feature/init-instructions branch May 7, 2026 07:07
devrimcavusoglu added a commit that referenced this pull request May 7, 2026
@devrimcavusoglu @claude
Cut v0.3.0: stamp CHANGELOG, bump version refs
f90a43d 
Move the [Unreleased] block to v0.3.0 dated 2026-05-07, with a focused
"Breaking changes" section calling out the --from-template directory
requirement (#84). Cross-link the four PRs that landed since v0.2.1
(#81, #84, #86, #87) and add a Changed entry covering the docs-site
refresh that ships in this branch.

Bump the corresponding version refs in AGENTS.md (current release +
milestone snapshot now covers M0–M7), INSTALL.md (SKERN_VERSION pin
example), docs/guide/installation.md (matching pin example), and
docs/guide/index.md (current-release callout).

Docs build verified.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
@devrimcavusoglu devrimcavusoglu mentioned this pull request May 7, 2026
Merged
3 tasks
devrimcavusoglu added a commit that referenced this pull request May 7, 2026
@devrimcavusoglu @claude
Cut v0.3.0: docs refresh + CHANGELOG stamp (#89)
924083c 
* Refresh docs site for v0.2.1 (eight platforms, init instructions, skill versioning)

Bring the VitePress site up to date with the v0.2.0 / v0.2.1 surface that has
landed since the last docs refresh:

- Eight platform adapters wherever 3 were listed (index, guide, concepts diagram,
  reference flag enums, platforms index/comparison) and a dedicated page for
  each new adapter (cursor, gemini-cli, github-copilot, windsurf, continue).
- `skern init --instructions` / `--tool-forming-loop` / `--target` /
  `--print-instructions` documented in the quick-start, agent-setup, and command
  reference. Agent-setup now leads with `init --instructions` instead of the
  manual `echo … >> AGENTS.md` recipe.
- Reference reorganized: registry vs. platform command groups, full pages for
  `skill import`, `skill version`, `skill diff`, capacity reporting on
  install/uninstall, `--enforce-budget`, `--with-platforms`, batch
  install/uninstall.
- Validation page split into errors / warnings / hints with the trigger-prefix
  and recommended-section hints.
- Skill format page corrected to the nested `metadata.author` / `metadata.version`
  / `metadata.modified-by` schema and includes the import workflow.
- Installation page covers macOS, Linux, and Windows (PowerShell) one-liners
  plus version pinning, custom install dir, source build, manual install,
  uninstall.
- Contributing/development reflects the declarative platform spec, updated
  Make targets, and the `cli/instructions/` package.
- Sidebar adds the new platform pages and a Writing Skills entry under Guide.

Build verified with `npm run docs:build` (clean).

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

* Cut v0.3.0: stamp CHANGELOG, bump version refs

Move the [Unreleased] block to v0.3.0 dated 2026-05-07, with a focused
"Breaking changes" section calling out the --from-template directory
requirement (#84). Cross-link the four PRs that landed since v0.2.1
(#81, #84, #86, #87) and add a Changed entry covering the docs-site
refresh that ships in this branch.

Bump the corresponding version refs in AGENTS.md (current release +
milestone snapshot now covers M0–M7), INSTALL.md (SKERN_VERSION pin
example), docs/guide/installation.md (matching pin example), and
docs/guide/index.md (current-release callout).

Docs build verified.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

No reviews

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

1 participant

@devrimcavusoglu