docs(sitemap-author): SKILL.md guidelines from PoC#1824
Merged
Conversation
4 author-facing guidelines distilled from twitter + hackernews PoCs (#1823): 1. Size guidance 3-tier (< 1500 / 1500-3000 / > 3000 token) — supplements schema §1.1 hard 800 limit with realistic split-vs-keep heuristic, since simple sites' 1-2 action pages naturally fall in 800-2000 token. Phase 2 cron audit counts tokens, not bytes (CJK 30-50% higher token-per-char). 2. Partial layout entry + scope rule — partial files (`_<name>.md` with empty `url_patterns`) must scope all selectors to the partial root, not page-level first match. Otherwise `click [data-testid="like"]` in `_tweet_card.md` consumed from `/home` would flip the wrong card. Adopted from opencli-user's twitter `_tweet_card.md` "Card scope rule" pattern. 3. Workflow Fallback `on_adapter_fail:` YAML sub-key convention — wraps the adapter-trigger condition + `adapter_health_update` directive + step list in one block, so consumption skills can distinguish adapter-triggered fallback from entry-point fallback. Schema v1.2 candidate; SKILL guideline for now. Adopted from opencli-user's twitter `workflows/post.md`. 4. SITE.md `Top-level routes` uncovered-route marker — list routes that exist on the site but the sitemap intentionally doesn't navigate (`/messages → pages/messages.md（DM，本 PoC v1 不覆盖）`). Without it, agents assume "not listed → doesn't exist"; with it, they know to probe themselves. Adopted from opencli-user's twitter `SITE.md`. No schema field changes — these are SKILL.md author-facing conventions on top of the existing v1.1 schema (#1822). Schema reference is unchanged.
…replacement @opencli-user review nit: readers scanning the 3-tier table may misread `< 1500` as the new spec. Add explicit line clarifying that schema §1.1 hard 800 still applies and the table is author decision aid + audit explanation prompt.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
4 author-facing SKILL.md guidelines distilled from the twitter + hackernews PoCs (#1823). No schema field changes — these are conventions on top of the v1.1 schema (#1822).
Items
Size guidance 3-tier (< 1500 / 1500-3000 / > 3000 token) — supplements schema §1.1 hard 800 with realistic split-vs-keep heuristic. Simple sites' 1-2 action pages naturally fall in 800-2000 token; strict 800 would force unnecessary splits.
Partial layout entry + scope rule — partial files (
_<name>.md,url_patterns: []) must scope all selectors to the partial root, not page-level first match. Otherwiseclick [data-testid="like"]consumed from/homeflips the wrong card. Adopted from @opencli-user's twitter_tweet_card.mdCard scope rule.Workflow Fallback
on_adapter_fail:YAML sub-key convention — wraps adapter-trigger +adapter_health_updatedirective + step list into one block. Consumption skills can distinguish adapter-triggered fallback from entry-point fallback. Schema v1.2 candidate; SKILL guideline for now. Adopted from @opencli-user's twitterworkflows/post.md.SITE.md
Top-level routesuncovered-route marker — list routes that exist but the sitemap intentionally doesn't navigate (e.g./messages → pages/messages.md（DM，本 PoC v1 不覆盖）). Without this, agents assume "not listed = doesn't exist"; with it, they know to probe themselves. Adopted from @opencli-user's twitterSITE.md.Reviewer
@opencli-user (since 3 of 4 conventions come from their twitter PoC content).
Test plan
npm run docs:buildclean