| name | dev-guide-skill-stewardship |
| description | Nested lingtai-dev-guide reference for turning one-off experience into durable skills: when to write a skill vs leave it as notes, the router-vs-nested- reference pattern, distilling experience (归一) and session journals into triggered/executable SKILL.md files, de-privatizing and parameterizing local paths and human-specific details, a lightweight pre-publish benchmark/checklist, grooming shared-library candidates, and PR-ready skill cleanup.
|
| version | 1.0.1 |
| last_changed_at | 2026-07-18T00:00:00Z |
| maintenance | If you find stale or incorrect information here, use the lingtai-issue-report skill to assemble evidence and obtain per-issue human consent before filing an issue. Never include secrets, credentials, tokens, or private paths. |
Skill Stewardship
Nested lingtai-dev-guide reference. Read this after the top-level router sends you
here when deciding whether to write a skill, distilling experience into one, or
cleaning a skill up so it can ship in a PR.
This consolidates the skill-distillation meta-method (归一), skill audit/triage,
the experience-to-skill side of session-journal handoff, the skill-benchmark
checklist, and shared-library grooming. It governs LingTai's skill hygiene; for
generic authoring mechanics (frontmatter spec, trigger syntax, file layout)
cross-link to skills-manual rather than duplicating it here.
Core principle
A skill turns a repeated experience into something triggered, executable,
verifiable, and maintainable. Write one when the technique would otherwise be
re-derived ad hoc across sessions or agents — and only after it is de-privatized
and lightly benchmarked. Skills shipping in this repo's preset tree must be
parameterized: no private paths, no human-specific details, no secrets.
1. When to write a skill
Write one when the technique was not intuitively obvious and you would reference
it again; when multiple agents/sessions keep re-implementing the same workflow
with divergent quality (convergent discovery is the strongest signal); or when
the pattern is broadly reusable rather than a one-off.
Do not write a skill for one-off solutions or single-incident narratives; for
standard practices already documented elsewhere (link instead); for
project-specific conventions (those belong in CLAUDE.md/repo docs); or for
mechanical constraints a test/regex could enforce (automate, don't document).
If it is real but not yet skill-worthy, leave it as a session-journal entry or a
shared-library candidate (§5) until the pattern repeats.
2. Routing vs nested-reference pattern
LingTai utility skills use progressive disclosure: a short router SKILL.md at
the root plus focused nested references under reference/<topic>/SKILL.md.
Read/context limits are a design signal, not a global hard-cap to keep open
forever. Do not encode an old tool threshold as a blanket character limit, and do
not paste dense material into the root just because a reader might need it later.
The root carries only the progressive-disclosure link; the related/reference file
carries the detail and loads on demand. For current mechanics (frontmatter,
layout, validator, limit-aware structure), load skills-manual.
- Keep the router compact: nested-reference catalog, routing table, cross-links.
Detailed procedures live in the nested files.
- A nested reference is parent-owned — a drill-down of its parent skill, not a
standalone top-level skill. Begin each nested file by identifying itself, e.g.
"Nested lingtai-dev-guide reference."
- Adding a nested reference means updating the parent's catalog and routing
table in the same commit, plus any test asserting the nested set (see
tui/internal/tui/skill_files_test.go).
Prefer adding a nested reference to an existing router over creating a new
top-level skill when the topic drills down into an existing domain.
3. Distilling experience into a skill (归一)
The loop that turns scattered experience (chats, reports, code, daemon logs,
knowledge entries, session journals) into a maintainable SKILL.md:
- Trigger. State the concrete situations that should load this skill — as
the
description "Use when…" triggers, in third person.
- Distill. Extract the reusable technique, not the narrative. One excellent
example beats five mediocre ones; drop session-specific storytelling.
- Validate. Confirm any commands/computations actually run and produce the
claimed result; fix or remove anything you cannot verify.
- Maintain. Note what would make the skill stale (an API change, a renamed
file) so a future edit knows what to check.
Session journals feed steps 1–2: an entry recording a reusable gotcha, decision,
or procedure is raw material for a skill. Promote it only when the pattern
recurs; until then it stays a journal/handoff note. (For the journal format,
defer to the kernel knowledge/psyche manuals — this reference only covers using
journals as skill seeds.)
4. De-private and parameterize before publishing
Anything shipped in the preset skill tree (or proposed for the shared library)
must be scrubbed. This list is the canonical de-privatization rule for the dev
guide; other references point here.
- Paths:
/Users/<name>/... → <your-lingtai-checkout> or ~/.lingtai-tui/....
- People: named individuals → "the maintainer"; private project names → generic.
- Secrets: tokens/keys/passwords →
<REDACTED> or ${ENV_VAR} references.
- Channels/IDs: Telegram chat IDs, emails, recipient lists → parameterized or removed.
- PR/issue numbers: concrete numbers → examples only ("e.g. a small PR like #NNN").
Repo-relative paths and generic command examples are fine; only private,
machine-, or person-specific details must go.
5. Lightweight pre-publish benchmark / checklist
A quick pre-flight before a skill ships — a checklist, not a framework:
6. Shared-library candidate grooming
Not every reusable experience belongs in this repo's preset tree:
- Repo dev-guide nested reference — developer/operator methodology for working
on LingTai itself.
- Shared library candidate — broadly reusable agent behaviour that is not
LingTai-dev-specific; groom it (de-private, benchmark) and propose it for the
shared library rather than the preset tree.
- Project/custom skill — domain-specific (heliophysics, nutrition, VC, etc.)
or privacy-contaminated; keep it in the project, do not promote it.
When in doubt, prefer the smallest, most local home that still makes the skill
discoverable; promote later when convergent reuse is demonstrated.
7. PR-ready skill cleanup
Bundle skill changes into a reviewable PR with the router catalog/routing-table
edits in the same commit as the new/changed nested reference; updated tests
(tui/internal/tui/skill_files_test.go for nested-reference assertions) and a
passing focused run; and a self-contained HTML explainer (see
reference/pr-review-deliverables/SKILL.md).
Related references
skills-manual — generic skill authoring: frontmatter spec, trigger syntax,
file layout, testing skills, limit-aware router/reference structure. Defer to it
for mechanics; this reference covers LingTai-specific stewardship.reference/pr-review-deliverables/SKILL.md — review gates and the HTML
explainer for a skill-changing PR.reference/contributing/SKILL.md — issue → worktree → PR → merge loop and the
same-commit catalog/router/test rule.
