OpenTIL

til

Capture and manage "Today I Learned" entries on OpenTIL -- from drafting to publishing, all within the CLI.

Setup

1. Go to https://opentil.ai/dashboard/settings/tokens and create a Personal Access Token with read:entries, write:entries, and delete:entries scopes 2. Copy the token (starts with til_) 3. Set the environment variable:

export OPENTIL_TOKEN="til_xxx"

Token Resolution

Token resolution order: 1. $OPENTIL_TOKEN environment variable (overrides all profiles) 2. ~/.til/credentials file — active profile's token (created by /til auth)

If neither is set, entries are saved locally to ~/.til/drafts/.

Credential File Format

~/.til/credentials stores named profiles in YAML:

active: personal
profiles:
  personal:
    token: til_abc...
    nickname: hong
    site_url: https://opentil.ai/@hong
    host: https://opentil.ai
  work:
    token: til_xyz...
    nickname: hong-corp
    site_url: https://opentil.ai/@hong-corp
    host: https://opentil.ai

Backward compatibility: If ~/.til/credentials contains a plain text token (old format), silently migrate it to a default profile in YAML format and write back.

Subcommand Routing

The first word after /til determines the action. Reserved words route to management subcommands; anything else is treated as content to capture.

| Invocation | Action | |------------|--------| | /til list [drafts\|published\|all] | List entries (default: drafts) | | /til publish [ \| last] | Publish an entry | | /til unpublish | Unpublish (revert to draft) | | /til edit [instructions] | AI-assisted edit | | /til search | Search entries by title | | /til delete | Delete entry (with confirmation) | | /til status | Show site status and connection info | | /til sync | Sync local drafts to OpenTIL | | /til tags | List site tags with usage counts | | /til categories | List site categories | | /til batch | Batch-capture multiple TIL entries | | /til auth | Connect OpenTIL account (browser auth) | | /til auth switch [name] | Switch active profile (by profile name or @nickname) | | /til auth list | List all profiles | | /til auth remove | Remove a profile | | /til auth rename | Rename a profile | | /til | Capture content as a new TIL | | /til | Extract insights from conversation (multi-candidate) |

Reserved words: list, publish, unpublish, edit, search, delete, status, sync, tags, categories, batch, auth.

Reference Loading

⚠️ DO NOT read reference files unless specified below. SKILL.md contains enough inline context for most operations.

On subcommand dispatch (load before execution):

| Subcommand | References to load | |------------|--------------------| | /til | none | | /til (extract from conversation) | none | | /til list\|status\|tags\|categories | references/management.md | | /til publish\|unpublish\|edit\|search\|delete\|batch | references/management.md | | /til sync | references/management.md, references/local-drafts.md | | /til auth | references/management.md, references/api.md | | /til auth switch\|list\|remove\|rename | references/management.md |

On-demand (load only when the situation arises):

| Trigger | Reference to load | |---------|-------------------| | API returns non-2xx after inline error handling is insufficient | references/api.md | | Auto-detection context (proactive TIL suggestion) | references/auto-detection.md | | No token found (first-run local fallback) | references/local-drafts.md |

API Quick Reference

Create and publish an entry:

curl -X POST "https://opentil.ai/api/v1/entries" \
  -H "Authorization: Bearer $OPENTIL_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "entry": {
      "title": "Go interfaces are satisfied implicitly",
      "content": "In Go, a type implements an interface...",
      "summary": "Go types implement interfaces implicitly by implementing their methods, with no explicit declaration needed.",
      "tag_names": ["go", "interfaces"],
      "published": true,
      "lang": "en"
    }
  }'

Key create parameters:

| Field | Type | Required | Description | |-------|------|----------|-------------| | content | string | yes | Markdown body (max 100,000 chars) | | title | string | no | Entry title (max 200 chars). Auto-generates slug. | | tag_names | array | no | 1-3 lowercase tags, e.g. ["go", "concurrency"] | | published | boolean | no | false for draft (default), true to publish immediately | | lang | string | no | Language code: en, zh-CN, zh-TW, ja, ko, etc. | | slug | string | no | Custom URL slug. Auto-generated from title if omitted. | | visibility | string | no | public (default), unlisted, or private | | summary | string | no | AI-generated summary for listing pages (max 500 chars) |

Management endpoints:

| Endpoint | Method | Description | |----------|--------|-------------| | /entries?status=draft&q=keyword | GET | List/search entries | | /entries/:id | GET | Get a single entry | | /entries/:id | PATCH | Update entry fields | | /entries/:id | DELETE | Permanently delete entry | | /entries/:id/publish | POST | Publish a draft | | /entries/:id/unpublish | POST | Revert to draft | | /site | GET | Site info (username, entry counts, etc.) | | /tags?sort=popular | GET | List tags with usage counts | | /categories | GET | List categories with entry counts |

> Full parameter list, response format, and error handling: see references/api.md

Execution Flow

Every /til invocation follows this flow:

1. Generate -- craft the TIL entry (title, body, summary, tags, lang) 2. Check token -- resolve token (env var → active profile in ~/.til/credentials) - If ~/.til/credentials exists in old plain-text format, migrate to YAML default profile first - Found -> POST to API with published: true -> show published URL - Not found -> save to ~/.til/drafts/ -> show first-run guide with connect prompt - 401 response -> save locally -> inline re-authentication (see Error Handling): - Token from ~/.til/credentials (active profile) or no prior token: prompt to reconnect via device flow → on success, update the active profile's token and auto-retry the original operation - Token from $OPENTIL_TOKEN env var: cannot auto-fix — guide user to update/unset the variable 3. Show identity -- when ≥2 profiles are configured, include Account: @nickname (profile_name) in result messages so the user always knows which account was used 4. Never lose content -- the entry is always persisted somewhere 5. On API failure -> save locally as draft (fallback unchanged)

/til -- Explicit Capture

The user's input is raw material -- a seed, not the final entry. Generate a complete TIL from it:

Steps:

1. Treat the user's input as a seed -- craft a complete title + body from it 2. Generate a concise title (5-15 words) in the same language as the content 3. Write a self-contained Markdown body (see Content Guidelines below) 4. Generate a summary (see Summary Guidelines below) 5. Infer 1-3 lowercase tags from technical domain (e.g. rails, postgresql, go) 6. Detect language -> set lang (en, zh-CN, zh-TW, ja, ko, es, fr, de, pt-BR, pt, ru, ar, bs, da, nb, pl, th, tr, it) 7. Follow Execution Flow above (check token -> POST or save locally)

No confirmation needed -- the user explicitly asked to capture. Execute directly.

/til -- Extract from Conversation

When /til is used without arguments, analyze the current conversation for learnable insights.

Steps:

1. Scan the conversation for knowledge worth preserving -- surprising facts, useful techniques, debugging breakthroughs, "aha" moments 2. Identify all TIL-worthy insights (not just one), up to 5 3. Branch based on count:

0 insights:

No clear TIL insights found in this conversation.

1 insight: Generate the full draft (title, body, tags), show it, ask for confirmation. On confirmation -> follow Execution Flow.

2+ insights: Show a numbered list (max 5), let the user choose:

Found 3 TIL-worthy insights:
  1. Go interfaces are satisfied implicitly
  2. PostgreSQL JSONB arrays don't support GIN @>
  3. CSS :has() enables parent selection
Which to capture? (1/2/3/all/none)

4. For each selected insight, generate a standalone TIL entry following Content Guidelines 5. Show the generated entry to the user and ask for confirmation before proceeding 6. On confirmation -> follow Execution Flow above (check token -> POST or save locally)

Auto-Detection

When working alongside a user, proactively detect moments worth capturing as TIL entries.

When to Suggest

Suggest when the conversation produces a genuine "aha" moment — something surprising, non-obvious, or worth remembering. Examples:

Do NOT suggest for: standard tool usage, documented behavior, typo-caused bugs, or widely known best practices.

Rate Limiting

1. Once per session — after suggesting once (accepted or declined), never suggest again 2. Natural pauses only — suggest at resolution points or task boundaries, never mid-problem-solving 3. Respect rejection — if declined, move on without persuasion

Suggestion Format

Append at the end of your normal response. Never interrupt workflow.

Template:

💡 TIL: [concise title of the insight]
   Tags: [tag1, tag2] · Capture? (yes/no)

Example (at the end of a debugging response):

...so the fix is to close the channel before the goroutine exits.
💡 TIL: Unclosed Go channels in goroutines cause silent memory leaks
   Tags: go, concurrency · Capture? (yes/no)

Capture Flow

Auto-detected TILs bypass the extract flow. The suggestion itself is the candidate.

1. User replies yes / y / ok / sure → agent generates full entry (title, body, tags, lang) from the suggested insight → follows Execution Flow (POST or save locally) 2. User replies no / ignores / continues other topic → move on, do not ask again

Non-affirmative responses (continuing the conversation about something else) are treated as implicit decline.

> Detailed trigger examples, state machine, and anti-patterns: see references/auto-detection.md

Management Subcommands

Management subcommands require a token. There is no local fallback -- management operations need the API.

/til list [drafts|published|all]

List entries. Default filter: drafts.

/til publish [ | last]

Publish a draft entry.

/til unpublish

Revert a published entry to draft.

/til edit [instructions]

AI-assisted editing of an existing entry.

/til search

Search entries by title.

/til delete

Permanently delete an entry.

/til status

Show site status and connection info. Works without a token (degraded display).

/til sync

Explicitly sync local drafts from ~/.til/drafts/ to OpenTIL. Requires token.

/til tags

List site tags sorted by usage count (top 20). Requires token.

/til categories

List site categories. Requires token.

/til batch

Batch-capture multiple TIL entries in one invocation. Requires explicit topic list.

ID Resolution

Session State

Track the following session state (not persisted across sessions):

> Detailed subcommand flows, display formats, and error handling: see references/management.md

Agent Identity

Three layers of attribution signal distinguish human-initiated from agent-initiated TILs.

Layer 1: HTTP Headers

Include these headers on every API call:

X-OpenTIL-Source: human | agent
X-OpenTIL-Agent: 
X-OpenTIL-Model: 

Layer 2: Tag Convention

Layer 3: Attribution Rendering (Backend)

Agent-initiated TILs are visually marked on OpenTIL automatically based on the source field. No content modification needed -- the backend renders attribution in the display layer.

Do NOT append any footer or attribution text to the content body.

Summary

| Dimension | /til | /til | Auto-detected | |-----------|-----------------|--------|---------------| | Trigger | User explicit | User command | Agent proactive | | Confirmations | 0 (direct publish) | 1 (review before publish) | 1 (suggest → capture) | | Source header | human | human | agent | | Agent header | Yes | Yes | Yes | | Model header | Yes | Yes | Yes | | agent-assisted tag | No | No | Yes | | Attribution | Automatic (backend) | Automatic (backend) | Automatic (backend) |

Content Guidelines

Every TIL entry must follow these rules:

Result Messages

API Success (token configured, 201)

Published to OpenTIL
  Title:  Go interfaces are satisfied implicitly
  Tags:   go, interfaces
  URL:    https://opentil.ai/@username/go-interfaces-are-satisfied-implicitly

When ≥2 profiles are configured, add an Account line:

Published to OpenTIL
  Account: @hong (personal)
  Title:   Go interfaces are satisfied implicitly
  Tags:    go, interfaces
  URL:     https://opentil.ai/@hong/go-interfaces-are-satisfied-implicitly

Single-profile users see no Account line — keep the output clean.

Extract the url field from the API response for the URL.

Sync Local Drafts

After the first successful API call, check ~/.til/drafts/ for pending files. If any exist, offer to sync:

Draft saved to OpenTIL
  Title:  Go interfaces are satisfied implicitly
  Tags:   go, interfaces
  Review: https://opentil.ai/@username/go-interfaces-are-satisfied-implicitly
Found 3 local drafts from before. Sync them to OpenTIL?

On confirmation, POST each draft to the API. Delete the local file after each successful sync. Keep files that fail. Show summary:

Synced 3 local drafts to OpenTIL
  + Go defer runs in LIFO order
  + PostgreSQL JSONB indexes support GIN operators
  + CSS :has() selector enables parent selection

If the user declines, keep the local files and do not ask again in this session.

First Run (no token)

Save the draft locally, then proactively offer to connect. This is NOT an error -- the user successfully captured a TIL.

TIL captured
  Title:  Go interfaces are satisfied implicitly
  Tags:   go, interfaces
  File:   ~/.til/drafts/20260210-143022-go-interfaces.md
Connect to OpenTIL to publish entries online.
Connect now? (y/n)

Only show the connect prompt on the first local save in this session. On subsequent saves, use the short form (no prompt):

TIL captured
  Title:  Go interfaces are satisfied implicitly
  Tags:   go, interfaces
  File:   ~/.til/drafts/20260210-143022-go-interfaces.md

Error Handling

On ANY API failure, always save the draft locally first. Never let user content be lost.

422 -- Validation error: Analyze the error response, fix the issue (e.g. truncate title to 200 chars, correct lang code), and retry. Only save locally if the retry also fails.

401 -- Token invalid or expired (token from ~/.til/credentials active profile):

TIL captured (saved locally)
  File: ~/.til/drafts/20260210-143022-go-interfaces.md
Token expired for @hong (personal). Reconnect now? (y/n)

When only one profile exists, omit the @nickname (profile) from the message.

401 -- Token invalid or expired (token from $OPENTIL_TOKEN env var):

The env var takes priority over ~/.til/credentials, so saving a new token via device flow would not help — the env var would still be used. Guide the user instead:

TIL captured (saved locally)
  File: ~/.til/drafts/20260210-143022-go-interfaces.md
Your $OPENTIL_TOKEN is expired or invalid. To fix:
  • Update the variable with a new token, or
  • unset OPENTIL_TOKEN, then run /til auth
Create a new token: https://opentil.ai/dashboard/settings/tokens

Network failure or 5xx:

TIL captured (saved locally -- API unavailable)
  File: ~/.til/drafts/20260210-143022-go-interfaces.md

> Full error codes, 422 auto-fix logic, and rate limit details: see references/api.md

Re-authentication Safeguards

| Rule | Behavior | |------|----------| | No retry loops | If re-auth succeeds but the retry still returns 401 → stop and show the error. Do not re-authenticate again. | | Batch-aware | During batch/sync operations, re-authenticate at most once. On success, continue processing remaining items with the new token. | | Respect refusal | If the user declines re-authentication (n), do not prompt again for the rest of this session. Use the short local-save format silently. | | Env var awareness | When the active token comes from $OPENTIL_TOKEN, never attempt device flow — it cannot override the env var. Always show the env var guidance instead. | | Profile-aware re-auth | On successful re-authentication, update the corresponding profile's token in ~/.til/credentials. Do not create a new profile. |

Manual Setup Instructions

When the user declines inline authentication (answers n), show:

Or set up manually:
  1. Visit https://opentil.ai/dashboard/settings/tokens
  2. Create a token (select read + write + delete scopes)
  3. Add to shell profile:
     export OPENTIL_TOKEN="til_..."

Local Draft Fallback

When the API is unavailable or no token is configured, drafts are saved locally to ~/.til/drafts/.

File format: YYYYMMDD-HHMMSS-.md

---
title: "Go interfaces are satisfied implicitly"
tags: [go, interfaces]
lang: en
summary: "Go types implement interfaces implicitly by implementing their methods, with no explicit declaration needed."
profile: personal
In Go, a type implements an interface...

The profile field records the active profile name at save time, ensuring sync uses the correct account's token. Omitted when no profiles are configured (backward-compatible).

> Full directory structure, metadata fields, and sync protocol: see references/local-drafts.md

Notes