agentleFS
craigcossairtcraigcossairt/trellis/.claude/skills/learn/SKILL.md

learn

Skill5 starsChanged 10 days agoMITView on GitHub

Review the current conversation and update project knowledge artifacts - common-gotchas.md (bug patterns), conventions at the highest rung that holds them (code, check, reviewer standard, skill, then AGENTS.md), navigation pointers, agent memory (cross-session). Use when asked to '/learn', 'what did we learn', 'capture lessons', 'update common-gotchas'.

  • Reads credentials

196 other projects use a version of this.

Adopted by

Most recently taken up by

Used with

Projects with it also use add-anydoc, add-clidash and 10 more.

Other files people use alongside this one.

Files found in the same public projects as a version of this one, more often than they turn up anywhere else. Each project counts once, large collections count for less, and this file's own repository is left out.
  • TomGranotSkill

    add-anydoc

    Add local office-document-to-Markdown conversion to NanoClaw agent containers with the pinned Firecrawl AnyDoc CLI. Use when agents need to read attached Word, PowerPoint, Excel, OpenDocument, RTF, EPUB, CSV, or text-based PDF files without uploading them to a hosted parser.

    Also in 5 projects that use this

  • TomGranotSkill

    add-clidash

    Add clidash — a zero-dependency, read-only web dashboard that derives its tabs and tables at runtime from any CLI that lists resources as JSON. Ships pre-wired for NanoClaw's ncl CLI (agent groups, sessions, channels, users, roles), plus message-activity charts, a log tail, and a read-only file viewer for group skills/CLAUDE.md/profiles.

    Also in 5 projects that use this

  • seek888Skill

    open-gstack-browser

    Launch GStack Browser — AI-controlled Chromium with the sidebar extension baked in. Opens a visible browser window where you can watch every action in real time. The sidebar shows a live activity feed and chat. Anti-bot stealth built in. Use when asked to "open gstack browser", "launch browser", "connect chrome", "open chrome", "real browser", "launch chrome", "side panel", or "control my browser". Voice triggers (speech-to-text aliases): "show me the browser".

    Also in 11 projects that use this

  • Saqlain-811Skill

    ios-sync

    Regenerate the iOS debug bridge against the latest upstream gstack templates. (gstack)

    Also in 6 projects that use this

  • MicrosoftSkill

    add-codex

    Use Codex (CLI + AppServer) as the full agent provider — planning, tool orchestration, native compaction, MCP tools, session resume — in place of the Claude Agent SDK. ChatGPT subscription or OPENAI_API_KEY. Per-group via agent_provider. Distinct from using OpenAI as an MCP tool (where Claude remains the planner).

    Also in 6 projects that use this

  • MicrosoftSkill

    add-deltachat

    Add DeltaChat channel integration via @deltachat/stdio-rpc-server. Native adapter — no Chat SDK bridge. Email-based messaging with end-to-end encryption.

    Also in 6 projects that use this

  • +5 more from TomGranot
  • +1 more from microsoft

The file

We split this skill into the rules it gives an agent

7 rules. 0 are common, 6 are distinctive, and 1 is very specific to this project.

  • 0

    Common

    Most of the 170 edited versions we read keep these.

  • 6

    Distinctive

    This author's own choices. Worth a look.

  • 1

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  • could be automatic: a setting could enforce it
  1. Distinctive:

    AGENTS.md prose, last resort: only a navigation pointer, or a rule every implementing session needs up front.

    line 67
  2. Very specific:

    Supersession pass (write-time invalidation): Before writing each capture, search for what it touches: grep common-gotchas.md and memory for …

    line 80
  3. Distinctive:

    Documented but now contradicted or outdated: - update the OLD artifact in the same session.

    line 84
  4. Distinctive:

    Nothing worth capturing: if that was the outcome, say so plainly.

    line 101
  5. Distinctive:

    Cite sources: If you're recording "the user said X," quote the message.

    line 107
  6. Distinctive:

    Don't rewrite history: When updating an existing entry, add new info - don't delete old context unless it's wrong.

    line 108
  7. Distinctive:

    Respect the sensitive-file hook: Don't try to edit .env, lock files, or generated files.

    line 110

“Common” is measured: kept by at least 6 in 10 of the 170 edited versions of this file we could read. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

You are closing the learning loop. Review this conversation for things worth capturing, then update the right artifacts so the learning survives into future sessions.

What to look for

Scan the conversation and classify any of these as candidates to capture:

  1. Bug patterns - a symptom someone ran into, a root cause, and a fix that should be visible to the next person who sees the same symptom.
  2. Tool gotchas - something about a tool, framework, or service that surprised you and would surprise the next session.
  3. Conventions - a decision about how code should look or how work should flow in this repo, validated in this session.
  4. Cross-session knowledge - user preferences, working-style feedback, project milestones.
  5. Context drift - anything you noticed is stale in existing docs.
  6. Navigation miss - the agent went looking for something (a file, a command, which module owns a concern) and took several tries or guessed. The fix is usually a one-line pointer where the agent looked first, not a new rule.
  7. Tool economy - a tool or pattern that burned tokens for little: re-reading a whole large file, a noisy command output, a search repeated because its first result was not trusted. Propose the cheaper form, or a script that returns just the answer.
  8. Steering bloat - a skill, command or rules section that was loaded but did not help, or that contradicted another. Everything always loaded costs context on every session, so a shorter file is a fix.

Things to SKIP:

  • Transient task state ("we're in the middle of X")
  • Stuff already documented elsewhere (check before duplicating)
  • Vague observations ("this could be cleaner")
  • Conversation turns that were noise

Where each type goes

TypeTargetAction
Bug patterndocs/common-gotchas.mdAppend a row using the file's format. Include commit SHA + issue ID if known. Auto-apply.
Tool gotchadocs/common-gotchas.md (or agent memory if not project-specific)Auto-apply.
ConventionThe rung the correction ladder (below) picks. Only rung 5 goes in AGENTS.md.Propose first. On approval, apply a rung 3-5 text fix in this run; a rung 1-2 fix becomes an issue or follow-up change.
Cross-session knowledgeYour harness's persistent memory, if availableAuto-apply per its conventions.
Context driftFlag to the userDon't fix silently; say what's stale and where.
Navigation missA pointer where the agent looked first (the relevant AGENTS.md section, a doc's index, a skill's opening lines)Propose first. One line that points, not one that explains.
Tool economyThe skill or command that caused it, or a small scriptPropose first.
Steering bloatThe bloated filePropose the cut or move as a diff. Never delete a rule without saying where its content went.

The correction ladder (conventions only)

A convention written as prose is the weakest fix there is. Agents copy what the code already does, and a rule in AGENTS.md is one they may never read: the same mistake gets made again after the rule against it is written down. So before proposing a convention, climb this ladder from the top and stop at the first rung that can hold it:

  1. Make it impossible in code. A type, a required parameter, a wrapper that does the right thing by default. The mistake then cannot be written.
  2. A deterministic check. A lint rule, a CI step or a ratchet. It fails the build instead of hoping someone remembers. When a bad pattern already exists and cannot be cleaned up now, a ratchet at today's count still stops it spreading.
  3. A reviewer standard. A judgment call no script can make goes in docs/coding-standards.md, which the review agent reads. Never fall back to AGENTS.md for these: that is the implementer's always-loaded context, which this rung exists to keep them out of.
  4. A skill or command step, when the lesson is a procedure rather than a property of the code.
  5. AGENTS.md prose, last resort: only a navigation pointer, or a rule every implementing session needs up front.

The proposal names its rung and gives one line for why each higher rung does not work ("a check cannot tell X from Y because..."). A proposal that goes straight to rung 5 without those lines is incomplete. A rung-1 or rung-2 fix is code, so propose it as an issue or follow-up change rather than writing it inside /learn. A rung-3, 4 or 5 fix is text: once the user approves it, apply it in the same run.

Process

  1. Read the conversation above. Identify 0-5 capture candidates. Don't force it - if nothing's worth saving, say so and exit.
  2. Supersession pass (write-time invalidation). Before writing each capture, search for what it touches: grep common-gotchas.md and memory for the same symptom/topic (and query the project brain, if initialized). Three outcomes:
    • Already documented and still true - skip, or fold new detail into the existing entry.
    • Documented but now contradicted or outdated - update the OLD artifact in the same session. Correct it in place, or when the old fact has historical value, mark it superseded instead: if your memory format supports metadata, add superseded_by: <successor> and keep the file; for gotchas/docs, edit in place - git history preserves the old text. Never write the new fact and leave the contradicted one live; retrieval and future greps will keep serving it.
    • Net-new - write fresh.
  3. For auto-apply categories (bug patterns, tool gotchas, cross-session knowledge): make the edits, then list them in the output.
  4. For propose-first categories (conventions, navigation misses, tool economy, steering bloat): show the proposed diff and ask for approval before editing, then apply the approved text fixes in this run. A rung 1-2 convention stays a proposed issue, never an edit here.
  5. At the end, output a short summary:
    • Captured: X entries applied (list files + one-line descriptions)
    • Superseded: entries invalidated/updated by this session's captures (list old -> new)
    • Proposed: Y edits waiting on approval, each with its rung
    • Drift flagged: Z (list files that look stale)
    • Nothing worth capturing: if that was the outcome, say so plainly.

Constraints

  • Brevity. Each captured entry should be terse - one row in a table, a short memory note. Future sessions are the consumer; they have limited attention budget.
  • Cite sources. If you're recording "the user said X," quote the message.
  • Don't rewrite history. When updating an existing entry, add new info - don't delete old context unless it's wrong.
  • Respect the sensitive-file hook. Don't try to edit .env, lock files, or generated files.

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.