| name | felt |
| description | This skill should be used whenever working in a project that contains a `.felt/` directory, and when the user mentions fibers or asks to "file this", "record a decision", "add structure", "close this fiber", "sketch a fiber", "think through", "draft a constitution", "clean up fibers", "consolidate", "archive", "sweep", "maintenance pass", or "extract from the session". It covers filing fibers, updating outcomes and bodies, using additional YAML fields beyond what felt owns natively, session mining, maintenance passes, and transcript processing.
|
felt — Working with Fibers
Fibers are concerns (tasks, decisions, questions, specs) stored as directory-contained markdown. Their relationships come from three surfaces: containment by path, [[wikilinks]] in the body for narrative connection, and optional project-owned conventions such as inputs.from when a project wants data-flow edges. felt owns the substrate — files, native metadata, search, links, and round-tripping of any extra top-level YAML fields — not the semantics of every YAML block a project might store.
The practical rule: felt owns the fiber; projects own any additional YAML fields beyond felt's native metadata. If a fiber needs more structure than felt owns natively, add those fields directly in the markdown file or use the project's own tool. felt will preserve them and surface them in --field / --json, but it will not validate the domain semantics for you.
Proactive filing. Retroactive extraction. Consolidation over time. Coherence when needed.
CLI
Something came into focus. Start:
felt add <slug> "name" -t tag -o "one-line outcome"
Understanding crystallized. Accrete:
felt edit <id> --status active
felt edit <id> --tag X
felt edit <id> --outcome "what changed"
Read then Edit .felt/<path>/<slug>.md # body + non-native frontmatter
Search and read:
felt ls # tracked (open and active)
felt ls "query" [-t tag] [-s closed] # substring over name, outcome, YAML, slug; any filter widens to all statuses
felt ls --body "query" # adds body search — plain substring; use -r --body for regex
felt session # SessionStart context as plain text
felt tree [<id>] # containment hierarchy
felt show <id> # full
felt show <id> -d compact | -d summary # metadata/outcome/extra keys | + lede + back-refs
felt show <id> --body # body with start line
felt show <id> --citations|--consumers # narrative back-refs | data-flow consumers
felt show <id> --field <key> # one raw frontmatter key, shell-friendly
A thread resolved. Close:
felt edit <id> --status closed --outcome "what was learned"
Reshape:
felt nest <child> <parent>
felt unnest <id>
Maintain:
felt check # broken refs, broken data-flow refs, layout issues
felt migrate [--dry-run] # normalize legacy layout
Statuses: · untracked, ○ open, ◐ active, ● closed
Detail: name < compact < summary < full. Summary adds the lede (first paragraph of the body; write it to stand alone).
Relationships: directory containment, [[wikilinks]] in bodies, and optional project-owned data-flow conventions. Nested IDs use paths (bao-analysis/damping-prior).
Outcomes longer than a sentence: edit .felt/<path>/<slug>.md directly using a |- block scalar (outcome: |-). felt edit -o "…" shell-escapes quotes and mangles multiline content; block scalar takes content literally so paragraphs, lists, and image embeds round-trip cleanly.
Philosophy
File while working. The moment to update a fiber is right after something crystallizes, while the user reads and the understanding still has edges.
Follow the understanding. Don't ask permission to file. The user's corrections and opinions are the primary trigger; when the direction shifts, the fiber should shift too.
Use the substrate cleanly. Names are concise labels — body and outcome carry the content. Nest for containment, [[wikilinks]] for narrative, project-owned conventions for anything more specific. Never hand-edit created-at / updated-at: felt stamps them on every write (a manual value is silently overwritten); edit only content fields.
Links in prose, not in piles. A [[wikilink]] earns its place by doing work in a sentence — naming what the other fiber is, why it's relevant here, where to head next. Related-things lists at the bottom of a fiber are a smell that the relationships haven't been thought through; fold them into the body where they belong, or drop the ones that aren't earning the link.
Bodies describe the now. A fiber's body says what's true currently — not how it got that way. Edit the body by correction; chronology lives in the git log of the fiber file (fibers are git-synced), not in the prose. Version markers ("v1", "v2"), dated update notes ("✓ Updated 2026-05-18"), and repurposing framings ("originally added for X, now Y") are signs that history-shaped content is sedimenting where a correction belongs. The exception is fibers whose subject is chronology (postmortems, decision logs, change histories) — those genuinely belong in the body.
Extract what slipped through. Continuous filing catches most things. At session end, mine decisions, patterns, and findings that were left implicit.
Outcomes teach. An outcome that says "done" has failed. Put the conclusion in — what was learned, what was decided, why — in a sentence that stands alone: it's what felt ls and -d compact show.
Act on Session Attention. When felt session shows ## Attention, treat it as standing authority to do obvious gardening without asking: nest top-level leaves under root buckets, demote open/active container fibers, close stale todos, consolidate clutter. Surface it to the user only when cleanup needs judgment or would distract from the current task.
Consolidate over time. Quick fibers become noise. Read the assemblage periodically and compost stale fibers into doc fibers, fix coherence across siblings, reshape branching. When closing, ask whether the lesson belongs in a doc fiber or the root fiber — compose upward.
CLAUDE.md stays lean. Commands, paths, context pointers. Documentation fibers carry the depth.
Cross-project stores are useful. A .felt/ store can be symlinked into a cross-project store so felt -C <store> ls searches every linked project; see cross-project.md for direction choice and safe setup.
What to Extract
Quick fibers
| Category | What to capture |
|---|
| Decision | Choice made, alternatives, reasoning. Include "decided NOT to." |
| Question answered | What was figured out. Mechanism, cause, how. |
| Pattern | Architectural insight, convention, workflow. |
| Finding | What was built, measured, produced. |
Documentation fibers
| Category | What to capture |
|---|
| Reference doc | Accumulated understanding. Architecture, philosophy, decision trees. |
| How-to | Procedures that get reused. More depth than CLAUDE.md. |
Additional YAML fields
Fibers may carry project-owned top-level YAML fields beyond what felt parses natively. Scalar keys can be set from the CLI (felt edit <id> --set key=value / --unset key); structured blocks are edited in the fiber file directly. Either way, keep the ordinary felt surfaces current alongside them: outcome for latest state, sub-fibers for durable findings.
Companion files (report.html, plots, recordings)
Fibers can carry arbitrary companion files in their directory alongside <slug>.md, and the body can inline any of them where it helps the reader with a :::{embed} <path> directive (renderer by extension: PDF, HTML iframe, images, audio). The one named convention: a fiber's rich human-facing report lives in a companion report.html, rendered by an explicit :::{embed} report.html line placed where the reader should meet it. Embed syntax and worker-side report.html conventions live in the shuttle skill.
References
Read the reference that matches the situation. Everything above applies always; references go deeper for specific activities.
| When | Reference |
|---|
| Helping fuzzy thought crystallize into a fiber — two diamonds, stances, funnel, ambiguity check | ideating.md |
| Drafting a constitution — pointers not snapshots, desired state, launch | constitution.md |
| At the end of a session — extracting what slipped through | mining.md |
| Processing an external transcript — meeting notes, voice note, dictation file | transcripts.md |
Acting on felt session Attention or reading across the assemblage for mess — gardening, composting, coherence, reshaping | maintenance.md |
| Migrating legacy flat fibers to directory format | migration.md |
| Setting up a cross-project felt store, or linking a per-project store into one | cross-project.md |
