lingtai-ai 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:
- YAML frontmatter parses; has
name(letters/numbers/hyphens), adescriptionthat starts with "Use when…" and lists triggers only (no workflow summary), and for LingTai-maintained skills alast_changed_atISO 8601 timestamp. For metadata-only backfills, initialize it fromgit log -1 --format=%cI -- path/to/SKILL.md; for substantive edits, update it in the same commit. - Structure is scannable: overview/core principle, when-to-use, steps, related references. Root routers contain links, not bulk.
- Declared dependencies/cross-linked skills exist and are named correctly.
- Any commands/snippets were actually executed and produce the claimed output (this practice caught real API breakage).
- De-privatization (§4) is complete.
- For nested references: parent catalog + routing table + tests updated.
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.