agentleFS
huytieuhuytieu/COG-second-brain/.claude/skills/feature-doc/SKILL.md

feature-doc

Skill1.3k starsChanged 4 months agoMITView on GitHub

Closed-loop feature documentation for your product. Give it a feature (issue numbers or an id) and it reads the source, drives your live app to capture real screenshots and a screen recording, writes a docs article (Docusaurus or any markdown docs site) with both how-to steps and use-case content, then verifies the article with a fresh-context read-only verifier before reporting. Use when you say "write the doc for <feature>", "document issue #123", or "/feature-doc".

  • Reads credentials

1 other project uses a version of this.

Trending

More talk lately.thin dataabout the whole repository

Dec 2025: 0 mentionsJan 2026: 0 mentionsFeb 2026: 0 mentionsMar 2026: 0 mentionsApr 2026: 0 mentionsMay 2026: 0 mentionsJun 2026: 0 mentionsJul 2026: 0 mentionsAug 2026: 0 mentionsSep 2026: 2 mentionsOct 2026: 7 mentionsNov 2026: 0 mentions
Dec 2025Jun 2026Nov 2026
Mentions a month of the huytieu/COG-second-brain repository that our weekly crawl found: only 9 in all, so this is a hint, not a trend. There is no adoption data for this file yet.

Most recently taken up by

Who's talking about huytieu/COG-second-brain

The biggest 5 of 9 mentions linking to the repository that our crawl found. Each line is their own headline.

See all 9

Talked about on GitHub (9 times).

On GitHub · 9

4 more on GitHub

The file

We split this skill into the rules it gives an agent

8 rules. About 0 are common, 6 are distinctive, and 2 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈6

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 2

    Very specific

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

  • Common
  • Distinctive
  • Very specific
  1. Distinctive:

    Keep the docs repo in a folder your tools can always read.

    line 30
  2. Distinctive:

    If a flow is gated (a broken backend path, an unshipped surface), capture what works, file the blocker in your tracker, and mark the rest …

    line 87
  3. Distinctive:

    Write the article as markdown (MDX-safe when the docs site is Docusaurus) with both layers:

    line 91
  4. Very specific:

    Run the draft through the no-ai-slop skill before verification.

    line 95
  5. Very specific:

    AC-3: Every UI or behavior claim is grounded in a captured screenshot or an issue body.

    line 108
  6. Distinctive:

    No fabrication. Follow your house writing rules (no em dashes, TL;DR first, scannable).

    line 114
  7. Distinctive:

    Use relative paths or config values in all output, never machine-specific absolute paths.

    line 116
  8. Distinctive:

    Auth wall: stop and ask the user to sign in.

    line 119

≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “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

feature-doc: closed-loop feature documentation

Produces one evidence-backed feature article end to end. Capture needs no manual gesture: a bundled recorder grabs frames from the browser through the DevTools protocol. Publishing the docs PR stays a gate for you at CP-6.

Configuration

Set these once (a .env, your kit.toml, or pass them as arguments). Nothing below is hardcoded.

SettingMeaningExample
APP_URLStart page of the live app to drivehttps://app.example.com/projects/1
ISSUE_REPOIssue tracker holding the feature issuesyour-org/your-product
DOCS_REPOLocal path of the docs repo../your-docs
DOCS_DIRFolder inside the docs repo for the articledocs/features/
EVIDENCE_DIRWhere screenshots and video land./evidence/<feature>/

Keep the docs repo in a folder your tools can always read. Some operating systems block background reads of the Documents folder mid-session, which breaks the verifier.

When to use

  • A shipped or shipping feature has no article, or an outdated one.
  • You want a doc that works as a user manual and as a guide to what you can do with the feature, with real screenshots and a video.

Skip it for backend features with no user surface (write a short "no doc required" record instead).

Closed loop

CP-1 spec (issues/repo)  -> CP-2 plan (AC-n)  -> CP-3 build (capture + write)
   -> CP-3v component verify (task-verifier, read-only)  -> fix-agent (max 2)
   -> CP-5 post-condition  -> CP-6 ship gate (you review, then open the docs PR)

The writer never grades its own work. The verifier is a fresh-context, read-only subagent that gets paths and AC-n only, never the writer's narration. See the closed-loop skill for the checkpoint mechanics.

Inputs

  • Feature id plus seed issue numbers in ISSUE_REPO, or a spec path.
  • A browser already logged in to the app, reachable by a browser automation tool (Playwright, CDP, or your browser harness). If the app redirects to a login page, stop and ask the user to sign in. Never type credentials.
  • The docs repo at DOCS_REPO. One article per feature: a new feature gets a new article, a changed one updates the existing article.

Pipeline

1. Enrich (CP-1)

Read each seed issue (gh issue view <n> --repo $ISSUE_REPO --json title,body,state,labels,milestone, or your tracker's CLI) and any matching spec files. Establish the concrete user surface, the ship status per issue (an OPEN issue is not a shipped surface, so do not claim it), and the exact flow to demo. Never invent UI. Where a detail is unknown, mark it TODO and flag it.

2. Plan (CP-2)

Map the article's sections to AC-n (see Post-conditions). Grep the docs repo for existing coverage to decide between a new article and an update.

3. Capture (CP-3)

Drive the live flow and save real evidence into EVIDENCE_DIR.

  • Screenshots of each meaningful state, using your browser tool's screenshot call.
  • A real video of the end-to-end flow with the bundled recorder (no gesture, no ffmpeg needed for the capture):

    SR_OUT=$EVIDENCE_DIR/<feature>-demo \
    SR_URL=$APP_URL \
    SR_FPS=8 \
    SR_STEPS='[{"at":0.5,"do":"click_testid","testid":"..."},{"at":2.0,"do":"click_text","text":"..."}]' \
    browser-harness < .claude/skills/feature-doc/tools/screenrec.py

    screenrec.py runs inside a CDP-based Python harness that exposes the page (browser-harness is one such tool; adapt the launcher to Playwright or your own). It writes frames, <out>.manifest.json (fps, viewport, per-action events with cursor coordinates and captions) and a quick <out>.raw.mp4 preview. Step actions are click_xy|click_testid|click_text|type|key|scroll, each with at (seconds) and an optional caption.

    The deliverable is a clean, complete recording of the real workflow: set up, configure, use, get the result. Finish it with tools/recompose.py, which places the real viewport in a simple browser window on a gradient background and speeds up long waits instead of cutting them. No captions, no intro or outro cards, no synthetic cursor.

    RC_MANIFEST=<base>.manifest.json RC_OUT=<feature>-walkthrough.mp4 \
    RC_SEGMENTS='[[0,9,1],[9,58,8],[58,70,1]]'  # [from_s,to_s,speed]; ramp the waits \
    RC_ADDR="app.example.com" python3 .claude/skills/feature-doc/tools/recompose.py

    recompose.py needs ffmpeg and Pillow. Embed the result with a plain video tag: <video controls preload="metadata" style="width:100%;border-radius:8px;"><source src="..." type="video/mp4" /></video>.

    • Length follows the task: long enough to teach setup and usage.
    • The usage payoff must work on camera. If the payoff step is broken, do not record a stub. Use screenshots for the working part and hold the video until the full flow works.
    • A clip of a few seconds is worse than a screenshot. Use a screenshot instead.
    • tools/videokit.py makes a branded, captioned teaser with intro and outro cards. Use it only for marketing teasers, never for walkthroughs.
  • Optional polish: an interactive demo (Arcade or similar). Browsers require a trusted user gesture to start such recorders, so tools/arcade-record.py drives the flow while you press the start and stop shortcut yourself.
  • Look at every capture. Open the images and the video, name any UI discrepancy, fix the flow, and re-capture. Never pass on "the element exists".
  • If a flow is gated (a broken backend path, an unshipped surface), capture what works, file the blocker in your tracker, and mark the rest pending. Do not fake a working demo.
  • Mask any customer data or personal data visible in a capture before it leaves your machine.

4. Write (CP-3)

Write the article as markdown (MDX-safe when the docs site is Docusaurus) with both layers:

  • How-to: overview, why it matters, step-by-step usage.
  • Use-case layer: at least 3 use cases with sample workflows (each a concrete prompt or step list plus the expected result), prompting techniques where the feature takes input, best practices, limitations.
  • Embed the captured media (![alt](path) for images, a video tag for the recording). Cross-link to related articles.
  • Run the draft through the no-ai-slop skill before verification.

5. Verify (CP-3v then CP-5)

Spawn a task-verifier with only the article path, the evidence directory and the AC-n list. It re-opens the files and media itself and returns one row per AC: EVIDENCE AC-n | CP-3v | PASS|FAIL | <one line + path/observation>. On FAIL:fixable, spawn fix-agent (max 2 attempts) with just the failed AC-n, then re-verify. After 2 attempts, escalate with the evidence.

6. Report and ship gate (CP-6)

Summarize the article path, the media (with accessible URLs once uploaded), the AC-n PASS table, and open TODOs or gated items. Opening the docs PR waits for the user.

Post-conditions

  • AC-1 The article exists at the planned path under DOCS_DIR with valid frontmatter for your docs site.
  • AC-2 It contains how-to steps and the use-case layer (at least 3 use cases, prompting where relevant, best practices).
  • AC-3 Every UI or behavior claim is grounded in a captured screenshot or an issue body. Unknowns are TODO, not invented. Surfaces from OPEN issues are marked gated, not shipped.
  • AC-4 Either (a) a clean, complete walkthrough recording exists (real setup, usage and result, no decoration, valid mp4 by ffprobe) and the article embeds it, or (b) screenshots cover the working parts and the article notes the video is pending. A short decorated clip does not satisfy this.
  • AC-5 Evidence that ships is accessible (uploaded to the PR or issue, not a local path).
  • AC-6 A limitations section states any gated, blocked or unshipped parts.

Rules

  • No fabrication. Follow your house writing rules (no em dashes, TL;DR first, scannable).
  • Visual verification is mandatory for UI docs: read the pixels, fix what is wrong, re-capture.
  • Use relative paths or config values in all output, never machine-specific absolute paths.

Escape hatches

  • Auth wall: stop and ask the user to sign in. Never enter credentials.
  • CDP will not connect: point your harness at the browser's remote-debugging URL (for example http://localhost:9222) and reload it. If the browser prompts for permission, the user clicks Allow.
  • Flow gated by a bug: file it, capture the working portion, mark the rest pending.
  • ffmpeg absent: the recorder falls back to a GIF preview. Install ffmpeg for the mp4.

Tools

  • tools/screenrec.py: flow recorder (CDP frame-grab loop to frames, manifest and raw preview).
  • tools/recompose.py: walkthrough finisher. Manifest to a clean 1920x1080 h264 mp4 with a browser window, gradient and speed ramps. Options: RC_FIT=1 fits a phone or tall capture, RC_CROP=x0,y0,x1,y1 crops the source, RC_NOBAR=1 drops the browser bar, RC_SPEED_BADGE=1 labels sped-up segments, RC_REDACT pixelates boxes such as a person's name.
  • tools/videokit.py: branded teaser cut with captions and cards (teaser only).
  • tools/arcade-record.py: hybrid interactive-demo recorder. Set APP_URL and add flows to its FLOWS table.

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.