diff --git a/index.html b/index.html index 726e9c3..143efa1 100644 --- a/index.html +++ b/index.html @@ -11,7 +11,7 @@
-
A field guide
/
AI ENGINEERING 01 / 2026
+
A field guide
review submissions ↗
/
AI ENGINEERING 01 / 2026

A presentation for humans who ship

AI for
dummies.

You do not need an army of models. You need a system: one mind to frame the work, several hands to execute it, and a clean boundary between every task.

01strong model
for ambiguity
03bounded workers
in parallel
∞iterations
with evidence

Read this as a route map, not a prompt recipe.

RULE ZEROStrong model for ambiguity.
Light model for bounded work.
diff --git a/responsive.css b/responsive.css index 92ae71b..0d6a4d4 100644 --- a/responsive.css +++ b/responsive.css @@ -1,4 +1,5 @@ .topbar-tools{display:flex;align-items:center;gap:24px} +.skills-review-link{color:var(--blue);font:700 9px 'DM Mono',monospace;letter-spacing:.06em;text-decoration:none;text-transform:uppercase;white-space:nowrap}.skills-review-link:hover{color:var(--accent)} .lang-switch{display:flex;align-items:center;gap:6px;color:var(--muted);font:500 10px 'DM Mono',monospace;letter-spacing:.1em} .lang-switch button{padding:0;border:0;color:inherit;background:transparent;font:inherit;cursor:pointer} .lang-switch button.active{color:var(--ink);font-weight:700} diff --git a/scripts/build-skill-review.mjs b/scripts/build-skill-review.mjs new file mode 100644 index 0000000..4dbefb4 --- /dev/null +++ b/scripts/build-skill-review.mjs @@ -0,0 +1,10 @@ +import { mkdirSync, writeFileSync } from 'node:fs'; +import { dirname, join } from 'node:path'; +import { catalog } from '../skills-review/catalog.js'; + +for (const entry of catalog) { + const output = join('skill-reviews', 'improved', entry.id, 'SKILL.md'); + mkdirSync(dirname(output), { recursive: true }); + writeFileSync(output, entry.improved); +} +console.log(`wrote ${catalog.length} improved skill drafts`); diff --git a/scripts/verify.mjs b/scripts/verify.mjs index d79f796..0381d3c 100644 --- a/scripts/verify.mjs +++ b/scripts/verify.mjs @@ -11,6 +11,9 @@ const modelRouting = read('docs/references/model-routing.md'); const rulesHtml = read('rules/index.html'); const rulesJs = read('rules/app.js'); const rulesCss = read('rules/styles.css'); +const reviewHtml = read('skills-review/index.html'); +const reviewJs = read('skills-review/app.js'); +const reviewCatalog = read('skills-review/catalog.js'); for (const url of ['https://code.claude.com/docs/en/sub-agents','https://code.claude.com/docs/en/skills','https://code.claude.com/docs/en/worktrees','https://git-scm.com/docs/git-worktree.html','https://developers.openai.com/codex/skills']) if (!refs.includes(url)) throw new Error(`missing reference ${url}`); console.log('content verification passed'); for (const token of ['data-phase="plan"','data-phase="build"','data-phase="review"','data-tree="main"','data-tree="ui"','data-worker="ui"','data-route="plan"','data-model-provider="openai"','data-model-provider="claude"','data-model-provider="gemini"','data-effort="low"','data-effort="medium"','data-effort="high"','data-skill-file="skill"','data-skill-step="observe"','data-skill-step="validate"','data-common-skill="ponytail"','data-common-skill="caveman"','data-common-skill="unlazy"','id="hands-on"','data-copy-target="prompt-install-skills"','data-copy-target="prompt-basic"','data-copy-target="prompt-skills"','hands-on/starter/','additional-reading.md','role="tablist"',' document.querySelector(selector); +const escape = (value) => value.replace(/[&<>"']/g, (character) => ({ '&':'&', '<':'<', '>':'>', '"':'"', "'":''' })[character]); +const redact = (value) => value.replace(/(NDO_PASS[^\n=]*[=:]\s*["']?)[^\n"']+/gi, '$1[REDACTED]').replace(/(password["']?\s*[:=]\s*["']?)[^\n"']+/gi, '$1[REDACTED]').replace(/\bsysadm@netcracker\.com\b/gi, '[REDACTED SERVICE ACCOUNT]'); +const download = (name, content) => { const url = URL.createObjectURL(new Blob([content], { type: 'text/markdown' })); const a = document.createElement('a'); a.href = url; a.download = name; a.click(); URL.revokeObjectURL(url); }; +const copy = async (content) => { + if (navigator.clipboard?.writeText) return navigator.clipboard.writeText(content); + const textarea = document.createElement('textarea'); textarea.value = content; textarea.setAttribute('readonly', ''); textarea.style.position = 'fixed'; textarea.style.opacity = '0'; document.body.append(textarea); textarea.select(); document.execCommand('copy'); textarea.remove(); +}; + +function visible() { return catalog.filter((item) => `${item.author} ${item.title} ${item.focus}`.toLowerCase().includes(state.query)); } +function syncUrl() { + const url = new URL(window.location.href); + url.searchParams.set('author', state.selected.author); + url.searchParams.set('skill', state.selected.id); + url.searchParams.set('view', state.preview); + history.replaceState({}, '', url); +} +function selectFromUrl() { + const params = new URLSearchParams(window.location.search); + const author = params.get('author'); + const id = params.get('skill'); + const view = params.get('view'); + const byAuthor = author && catalog.filter((item) => item.author.toLowerCase() === author.toLowerCase()); + const byId = id && catalog.find((item) => item.id === id); + state.selected = byId || byAuthor?.[0] || catalog[0]; + state.query = byAuthor ? state.selected.author.toLowerCase() : ''; + state.preview = view === 'improved' ? 'improved' : 'original'; + $('#skill-filter').value = byAuthor ? state.selected.author : ''; +} +function renderList() { + const items = visible(); + $('#count').textContent = `${items.length} of ${catalog.length} reviewed`; + $('#skill-list').innerHTML = items.map((item) => ``).join(''); + $('#skill-list').querySelectorAll('button').forEach((button) => button.addEventListener('click', () => { state.selected = catalog.find((item) => item.id === button.dataset.id); state.preview = 'original'; state.source = ''; syncUrl(); renderList(); renderDetail(); })); +} +async function original(entry) { + if (state.source) return state.source; + try { state.source = redact(await (await fetch(entry.path)).text()); } catch { state.source = '# Original preview unavailable\n\nServe this site from the repository root to load the submitted source.'; } + renderDetail(); + return state.source; +} +function renderDetail() { + const entry = state.selected; const markdown = state.preview === 'original' ? (state.source || 'Loading original Markdown…') : entry.improved; + $('#detail').innerHTML = `
${escape(entry.status)}

${escape(entry.title)}

Submitted by ${escape(entry.author)} ·

+
THE JOB

${escape(entry.focus)}

+
WHAT'S ALREADY WORKING
    ${entry.wins.map((item) => `
  • ${escape(item)}
    • `).join('')}
HIGHEST-VALUE IMPROVEMENTS
    ${entry.improve.map((item) => `
  • ${escape(item)}
    • `).join('')}
+ +
${state.preview === 'original' ? 'ORIGINAL / SAFETY-REDACTED WHERE NEEDED' : 'IMPROVED DRAFT / READY TO ADAPT'}
${escape(markdown)}
`; + $('#detail').querySelectorAll('[data-preview]').forEach((button) => button.addEventListener('click', () => { state.preview = button.dataset.preview; state.source = state.preview === 'original' ? state.source : ''; syncUrl(); renderDetail(); if (state.preview === 'original') original(entry); })); + $('[data-copy]').addEventListener('click', async () => { const content = state.preview === 'original' ? await original(entry) : entry.improved; await copy(content); $('[data-copy]').textContent = 'Copied'; }); + $('[data-download]').addEventListener('click', async () => download(`${entry.id}-${state.preview}.md`, state.preview === 'original' ? await original(entry) : entry.improved)); + if (state.preview === 'original' && !state.source) original(entry); +} +$('#skill-filter').addEventListener('input', (event) => { state.query = event.target.value.toLowerCase().trim(); renderList(); }); +window.addEventListener('popstate', () => { state.source = ''; selectFromUrl(); renderList(); renderDetail(); }); +selectFromUrl(); +renderList(); renderDetail(); diff --git a/skills-review/catalog.js b/skills-review/catalog.js new file mode 100644 index 0000000..2385661 --- /dev/null +++ b/skills-review/catalog.js @@ -0,0 +1,28 @@ +export const sources = { + specification: 'https://agentskills.io/specification', + practices: 'https://agentskills.io/skill-creation/best-practices', + descriptions: 'https://agentskills.io/skill-creation/optimizing-descriptions', + evaluation: 'https://agentskills.io/skill-creation/evaluating-skills', + scripts: 'https://agentskills.io/skill-creation/using-scripts' +}; + +const skill = (name, description, body) => `---\nname: ${name}\ndescription: ${description}\n---\n\n# ${name}\n\n${body.trim()}\n`; + +export const catalog = [ + { id:'code-style-review', author:'Andre Oliveira', path:'../submitted-skills/Andre%20Oliveira/skills/code-style-review/SKILL.md', title:'Code style review', status:'Good foundation', focus:'Run the repository’s configured formatter and static checks after a scoped code change.', wins:['Clear timing: after changes and before review.','Includes a final evidence checklist.'], improve:['Do not assume `backend/`, `frontend/`, Maven, ESLint, or Prettier exist; discover scripts from the current repository first.','Separate safe formatting from semantic cleanup and require a diff review before broad auto-fixes.','Add a small command-discovery script only if this project repeats the lookup.'], extras:'Add `references/tooling.md` only for known project commands; add one eval for a repo without either folder.', improved:skill('code-style-review','Run the configured formatter and static checks for a scoped code change. Use after editing code or before a review; discover project commands rather than assuming a stack.',`## Inputs\nChanged files and the repository root.\n\n## Workflow\n1. Inspect package/build configuration for the project’s documented lint, format, and style commands.\n2. Run the narrowest relevant check first. Apply formatting only to the requested files unless the user asks for a wider change.\n3. Review the diff for accidental rewrites, then rerun the same checks.\n\n## Rules\n- Do not invent directories or install tools without approval.\n- Report unavailable checks as not run, not passed.\n- Treat unused-code removal as a separate semantic change.\n\n## Output\nList each command, result, changed files, and any remaining failure.`)}, + { id:'sql-injection-audit', author:'Andre Salvo', path:'../submitted-skills/Andre%20Salvo/skills/sql-injection-audit/SKILL.md', title:'SQL injection audit', status:'Fix metadata', focus:'Trace user-controlled data to SQL sinks and verify values are parameterized.', wins:['Strong threat-model coverage, including identifiers and second-order injection.','The report asks for source, sink, and data flow.'], improve:['The frontmatter is invalid because an un-keyed line appears inside it; fix this first so hosts can discover the skill.','Scope the audit to changed code or named paths by default to avoid an unbounded repository scan.','Add language-specific safe/unsafe examples in a reference rather than expanding the main file.'], extras:'Add an eval with a parameterized query and a dynamic `ORDER BY` allowlist.', improved:skill('sql-injection-audit','Audit a changed code path for SQL injection. Use when code constructs or executes SQL, query-builder fragments, or ORM raw queries.',`## Inputs\nChanged files, branch diff, or a named query path.\n\n## Workflow\n1. Find SQL execution sinks and trace request, CLI, external, and stored user input to them.\n2. Confirm values use driver or ORM parameters. For dynamic identifiers, confirm a finite allowlist maps a user choice to a trusted token.\n3. Review raw-query escape hatches and stored procedures.\n4. Report only evidenced findings with source, sink, location, impact, and a safe pattern.\n\n## Rules\n- Escaping is not a substitute for parameterization.\n- Passing tests are supporting evidence, not proof of safety.\n- Do not modify code unless the user asks for a fix.\n\n## Output\nReturn a findings table and the scope reviewed; say explicitly when a path could not be traced.`)}, + { id:'confectionary-skill-hub', author:'Diego Moreira', path:'../submitted-skills/Diego%20Moreira/skills/confectionary-skill-hub/SKILL.md', title:'Confectionery skill hub', status:'Split required', focus:'Define recipe and order workflows for a confectionery domain.', wins:['Useful domain vocabulary and input shapes.','Concrete examples make the intent easy to understand.'], improve:['This is a catalog of three capabilities, not one discoverable skill; split recipe creation, recipe search, and order creation into packages.','Add valid frontmatter and state the system of record, validation rules, and mutation approval boundary.','Move JSON schemas to focused references so only the relevant workflow loads.'], extras:'Add `references/recipe-schema.md` and `references/order-schema.md`; test invalid quantities and missing delivery details.', improved:skill('confectionery-orders','Create or prepare a confectionery order from confirmed customer and item details. Use when a user asks to register an order or counter sale; confirm before sending it to an external system.',`## Inputs\nCustomer, pickup or delivery choice, items, quantities, prices, and optional discount.\n\n## Workflow\n1. Validate required fields and positive quantities.\n2. Calculate the proposed total and show a concise order summary.\n3. Ask for confirmation before creating or transmitting an order.\n4. Return the saved identifier or a clearly labeled draft.\n\n## Rules\n- Do not invent recipe availability, prices, addresses, or customer details.\n- Keep payment and personal data out of logs.\n- Read \`references/order-schema.md\` when mapping to the order system.\n\n## Output\nReturn a valid order payload plus validation warnings and confirmation state.`)}, + { id:'angular-access-modifiers', author:'Francisco Rangel', path:'../submitted-skills/Francisco%20Rangel/skills/angular-access-modifier/SKILL.md', title:'Angular access modifiers', status:'Sharpen scope', focus:'Make Angular class visibility explicit while respecting template and public APIs.', wins:['The template/private/public decision table is memorable.','Examples teach the preferred result.'], improve:['“Every member must be explicit” should be validated against the repository’s TypeScript and Angular version/conventions.','Do not assume tests require `public`; distinguish real external access from test workarounds.','Add a verification step using the project typecheck and template compiler.'], extras:'A lightweight AST check could prevent repeated manual review; include only if the convention is team-wide.', improved:skill('angular-access-modifiers','Apply explicit TypeScript access modifiers to Angular component, directive, and pipe members. Use when editing or reviewing Angular class APIs in a repository that adopts this convention.',`## Workflow\n1. Inspect the component’s template and callers before changing visibility.\n2. Use \`protected\` for template-facing members when the project supports it, \`private\` for implementation details, and \`public\` for intentional external APIs and lifecycle hooks.\n3. Keep existing framework-required visibility when a compiler or decorator requires it.\n4. Run the project typecheck and relevant template tests.\n\n## Rules\n- Do not change visibility only to satisfy a test; fix the test boundary or document the API.\n- Prefer the repository’s established Angular convention if it differs.\n\n## Output\nList changed members, their consumers, and verification results.`)}, + { id:'codebase-map', author:'Guilherme Lobo', path:'../submitted-skills/Guilherme%20Lobo/skills/codebase-map/SKILL.md', title:'Codebase map', status:'Strong candidate', focus:'Maintain a small, trustworthy index of feature entry points.', wins:['Excellent narrow purpose and stale-entry handling.','Clear rule for lazy, cheap maintenance.'], improve:['Avoid deleting a stale entry before verifying the replacement location; update atomically instead.','Define ownership and a conflict strategy for map edits in busy repositories.','Add a check that every listed path exists, rather than requiring an agent to remember it.'], extras:'A `scripts/check-feature-map.mjs` validator is justified because the invariant is deterministic.', improved:skill('codebase-map','Maintain FEATURE_MAP.md as a concise, verified index of feature entry points. Use before locating code for a change and after a change moves or adds an entry point.',`## Workflow\n1. If \`FEATURE_MAP.md\` exists, check whether the relevant entry path still exists.\n2. Use a valid entry as the starting point; otherwise search normally.\n3. After locating the feature, update the existing entry or add one concise entry point.\n4. Run \`scripts/check-feature-map.mjs\` when available.\n\n## Rules\n- Preserve a stale entry until a replacement is known, then update it in the same edit.\n- Index features and flows, not every file.\n- Do not make map edits when a change leaves entry points unchanged.\n\n## Output\nState whether the map was used, changed, or unavailable.`)}, + { id:'angular-accessibility-root', author:'Leonardo Uno', path:'../submitted-skills/Leonardo%20Uno/SKILL.md', title:'Angular accessibility (root copy)', status:'Duplicate package', focus:'Build and review Angular UIs against WCAG 2.2 AA.', wins:['Prioritizes native semantics before ARIA.','Covers interaction, focus, forms, and live updates.'], improve:['This is a duplicate of the nested package; retain only one canonical location to avoid drift.','Make “WCAG 2.2 AA” an audit target, not a claim of guaranteed compliance.','Add a small test matrix and route detailed component patterns to references.'], extras:'Keep one canonical package under `skills/angular-accessibility/` and add an eval for a keyboard-only dialog.', improved:skill('angular-accessibility','Build and review Angular interfaces for accessible semantics, keyboard use, focus behavior, and clear status feedback. Use when changing Angular templates, forms, dialogs, navigation, or custom controls.',`## Workflow\n1. Inspect the changed interaction and choose native semantic elements first.\n2. Check keyboard operation, focus order, visible focus, labels, errors, and dynamic announcements.\n3. Use Angular CDK or Material primitives when they provide the expected behavior.\n4. Run available accessibility checks and manually test the changed interaction by keyboard.\n\n## Rules\n- ARIA supplements native semantics; it does not replace them.\n- Do not claim WCAG conformance from one review.\n- Read \`references/patterns.md\` only for dialogs, tables, or custom composite controls.\n\n## Output\nReturn changed issues, evidence, and any remaining manual checks.`)}, + { id:'angular-accessibility', author:'Leonardo Uno', path:'../submitted-skills/Leonardo%20Uno/skills/angular-accessibility/SKILL.md', title:'Angular accessibility', status:'Needs consolidation', focus:'Build and review Angular UIs against WCAG 2.2 AA.', wins:['The most complete submitted accessibility guidance.','Clear examples for native controls and labels.'], improve:['Use this as the canonical copy and remove the root duplicate.','Move long component examples into a reference so the active instructions stay task-focused.','Add testing commands only when the repository declares axe, Lighthouse, or Angular test support.'], extras:'Add a test matrix for keyboard, screen reader announcement, error association, and contrast evidence.', improved:skill('angular-accessibility','Build and review Angular interfaces for accessible semantics, keyboard use, focus behavior, and clear status feedback. Use when changing Angular templates, forms, dialogs, navigation, or custom controls.',`## Workflow\n1. Inspect the changed interaction and choose native semantic elements first.\n2. Check keyboard operation, focus order, visible focus, labels, errors, and dynamic announcements.\n3. Use Angular CDK or Material primitives when they provide the expected behavior.\n4. Run available accessibility checks and manually test the changed interaction by keyboard.\n\n## Rules\n- ARIA supplements native semantics; it does not replace them.\n- Do not claim WCAG conformance from one review.\n- Read \`references/patterns.md\` only for dialogs, tables, or custom composite controls.\n\n## Output\nReturn changed issues, evidence, and any remaining manual checks.`)}, + { id:'copy-quote-info-to-payload', author:'Lucas Mantovan', path:'../submitted-skills/Lucas%20Mantovan/skills/copy-quote-info-to-payload/SKILL.md', title:'Copy quote info to payload', status:'Very strong', focus:'Map source quote data into a target command without inventing data.', wins:['Excellent source/skeleton distinction and preservation rule.','Uses a linked, on-demand mapping reference.'], improve:['Add a machine-checkable JSON validation step before returning output.','Define behavior for duplicate IDs, unmatched items, and conflicting values in the source.','Provide a fixture-based transform script if this exact mapping is repeatedly performed.'], extras:'Add an eval for missing values and a different skeleton shape; assert returned JSON parses.', improved:skill('copy-quote-info-to-payload','Populate a quote-command skeleton from quote data without fabricating values. Use when a quote JSON and command skeleton are supplied and the user asks to create a populated command.',`## Inputs\nOne source quote JSON and one target command skeleton.\n\n## Workflow\n1. Identify source and target; ask when the roles are ambiguous.\n2. Parse both documents and start from the target structure.\n3. Apply the mappings in \`reference.md\`; preserve unmatched target fields and item order.\n4. Validate that the resulting document is valid JSON.\n5. Return the payload and a short mapping summary.\n\n## Rules\n- Every populated value must come from the source or an explicit user instruction.\n- Never silently choose between duplicate IDs or conflicting values.\n- Do not alter item content unless the user requests it.\n\n## Output\nReturn one valid JSON document, then unresolved placeholders and mapping warnings.`)}, + { id:'generated-code-explanation', author:'Matheus Rocha', path:'../submitted-skills/Matheus%20Rocha/skills/generated-code-explanation/SKILL.md', title:'Generated code explanation', status:'Good writing guide', focus:'Explain changed code faithfully for the intended reader.', wins:['The what/why/verify structure is clear.','Explicitly prohibits invented rationale.'], improve:['The named demo-project module paths make the skill trigger too broadly outside that project; move them to a project reference.','Ask for the diff or paths before explaining an unprovided change.','Avoid requiring “alternatives considered” unless evidence supports them.'], extras:'Add a reviewer and non-technical audience eval to prove the explanation adapts without speculation.', improved:skill('generated-code-explanation','Explain a code change, its supported rationale, trade-offs, and verification for a named audience. Use when a user asks what changed, why it changed, or how to validate it.',`## Inputs\nA diff, files, or a confirmed description of the change; intended audience.\n\n## Workflow\n1. Read the supplied code or diff before making claims.\n2. Explain behavior first, then the evidence-backed reason and trade-offs.\n3. Adapt vocabulary and depth to the audience.\n4. State verification that was run and checks that remain.\n\n## Rules\n- Mark unknown intent as unknown; do not infer motivation.\n- Do not add comments or documentation only to make an explanation easier.\n- Read project-specific conventions from a reference only in that project.\n\n## Output\nUse: What changed, Why this approach, Trade-offs, How to verify.`)}, + { id:'ndo-repro', author:'Pedro Aranha', path:'../submitted-skills/Pedro%20Aranha/skills/ndo-repro/SKILL.md', title:'NDO reproduce loop', status:'Security action required', focus:'Build, deploy, and verify a microservice against a dev environment.', wins:['Exceptionally concrete workflow, evidence standard, rollback path, and approval gate.','Bundled scripts and focused operational references are appropriate.'], improve:['A hardcoded password is present in a bundled script. Remove it immediately, rotate it, and read credentials only from an approved secret source.','Use package-relative script paths instead of a host-specific `~/.claude` location.','Separate read-only investigation from shared-environment deploy actions in the header and require explicit per-environment approval.'], extras:'Add `scripts/doctor.sh` for dependency and credential-presence checks, plus a safe dry-run deploy eval. Original preview is safety-redacted.', improved:skill('ndo-repro','Reproduce or validate an NDO issue through approved local build, dev-environment deployment, BOM API calls, and live logs. Use only when the user names the service and target environment.',`## Safety boundary\nRead-only diagnosis is allowed after environment selection. Build, push, deploy, rollback, and credential changes require explicit approval for the named environment and action.\n\n## Workflow\n1. Run \`scripts/doctor.sh\` and resolve the environment using the bundled registry.\n2. Build and test locally; confirm the exact image reference.\n3. Before a shared-environment mutation, restate service, environment, image, and rollback plan; wait for approval.\n4. Drive the smallest API flow that tests the acceptance criterion, then collect image, response, and log evidence.\n\n## Rules\n- Read credentials from approved environment variables or a secret manager; never embed or echo them.\n- Use paths relative to this package.\n- Do not infer a pass from a nearby signal.\n\n## Output\nReport approval, deployed image, criterion-by-criterion evidence, and untested criteria.`)}, + { id:'duplicate-code-check', author:'Tatyana Ardyntceva', path:'../submitted-skills/Tatyana%20Ardyntceva/skills/duplicate-code-check/SKILL.md', title:'Duplicate code check', status:'Needs report contract', focus:'Find duplication newly introduced by a branch or merge-request diff.', wins:['Appropriately non-mutating by default.','Targets the diff rather than all code.'], improve:['“Ask before suggesting removal” is unnecessarily restrictive: suggestions are useful; ask before modifying code instead.','Define the diff base/default when branch details are missing.','Use a report with location pairs, similarity evidence, confidence, and a “do not merge” threshold.'], extras:'Add a script for obtaining the merge-base diff and an eval with intentional repeated test fixture code.', improved:skill('duplicate-code-check','Review a branch or merge-request diff for newly introduced, meaningful code duplication. Use when a user asks about repeated logic or copy-paste code in a diff.',`## Inputs\nSource branch or MR and target branch; use the repository default base only after reporting it.\n\n## Workflow\n1. Obtain the merge-base diff and list files examined.\n2. Compare changed blocks with nearby and existing code; distinguish deliberate repetition, generated code, and test fixtures.\n3. Report evidenced candidates with both locations, similarity, maintenance risk, and a proportionate suggestion.\n\n## Rules\n- Do not modify or remove code without explicit approval.\n- Do not label repeated literals alone as duplication without a maintenance consequence.\n- Report scope limits and skipped generated files.\n\n## Output\nReturn a Markdown table: candidate, locations, evidence, confidence, risk, suggested next step.`)}, + { id:'am-i-free', author:'Vinicius Nascimento', path:'../submitted-skills/Vinicius%20Nascimento/skills/am-i-free/SKILL.md', title:'Am I free?', status:'Good companion set', focus:'Calculate working time after lunch handling.', wins:['Exit-code handling makes the agent’s next action deterministic.','Friendly, human output matches the domain.'], improve:['Replace host-specific `$CLAUDE_SKILL_DIR` fallback paths with package-relative paths.','Document the data schema and timezone/DST assumptions in a reference.','Any `--default-lunch` write must ask for consent immediately before it occurs.'], extras:'Add tests for malformed JSON, overnight shifts, and a lunch end before lunch start.', improved:skill('am-i-free','Calculate elapsed work time from the Long Day Factory shift record. Use when the user asks whether they can leave or how much time remains.',`## Workflow\n1. Run \`python3 scripts/am_i_free.py\`.\n2. Interpret its documented exit code. Ask before any option that writes an assumed lunch break.\n3. Give the result, remaining time or release time, and a concise friendly message.\n\n## Rules\n- Treat malformed or missing state as a recovery question, not a calculation.\n- Read \`references/state.md\` for schema and timezone behavior.\n- Do not expose unrelated content from the local state file.\n\n## Output\nReport calculation status, remaining time or freedom, and any assumption made.`)}, + { id:'back-to-work', author:'Vinicius Nascimento', path:'../submitted-skills/Vinicius%20Nascimento/skills/back-to-work/SKILL.md', title:'Back to work', status:'Good companion set', focus:'Record return time after a lunch break.', wins:['Explains the relationship with the calculation skill.','Surfaces missing lunch/start state.'], improve:['Creating or changing a shift file is a mutation; state that the user’s “back to work” message is the authorization.','Use a package-relative script path.','Share state schema and error behavior with the other four companion skills.'], extras:'Add one script test for missing state and a reference shared by the suite.', improved:skill('back-to-work','Record the return time for a Long Day Factory lunch break. Use when the user says they have returned to work.',`## Workflow\n1. Confirm the message is an instruction to record the current return time.\n2. Run \`bash scripts/back.sh\`.\n3. Surface any missing shift or lunch state and explain the next recovery action.\n\n## Rules\n- This command changes local shift state; do not run it for a hypothetical question.\n- Use the shared state schema in \`references/state.md\`.\n\n## Output\nConfirm the recorded timestamp and any state warning with a light, respectful tone.`)}, + { id:'long-day-start', author:'Vinicius Nascimento', path:'../submitted-skills/Vinicius%20Nascimento/skills/long-day-start/SKILL.md', title:'Long day start', status:'Good companion set', focus:'Start a shift and reset prior lunch state.', wins:['Reset behavior is stated clearly.','The script provides a direct observable result.'], improve:['Highlight that it overwrites the prior shift state before execution.','Use package-relative script paths and shared state documentation.','Offer a “show current state” check before reset when a previous shift exists.'], extras:'Add an explicit confirmation branch for an existing incomplete shift.', improved:skill('long-day-start','Start a Long Day Factory shift by recording the current time and clearing lunch state. Use when the user explicitly says they have started their day.',`## Workflow\n1. Check whether an incomplete shift record exists.\n2. If it does, explain that starting a new shift replaces its lunch state and ask for confirmation.\n3. Run \`bash scripts/start.sh\` after explicit start authorization.\n\n## Rules\n- Do not reset a shift for a hypothetical or informational request.\n- Store and document times in timezone-aware ISO 8601 format.\n\n## Output\nConfirm the new start timestamp and whether a prior shift was replaced.`)}, + { id:'lunch-time', author:'Vinicius Nascimento', path:'../submitted-skills/Vinicius%20Nascimento/skills/lunch-time/SKILL.md', title:'Lunch time', status:'Good companion set', focus:'Record the beginning of a lunch break.', wins:['Narrow purpose and clear relationship to the suite.','Handles missing start state gracefully.'], improve:['Treat “going to lunch” as write authorization but keep queries non-mutating.','Use a package-relative script path.','Prevent overwriting an existing open lunch without confirmation.'], extras:'Share one state schema and add a test for duplicate lunch starts.', improved:skill('lunch-time','Record the start of a Long Day Factory lunch break. Use when the user explicitly says they are starting lunch.',`## Workflow\n1. Confirm the request records a lunch start now.\n2. Check for a started shift and an existing open lunch.\n3. If an open lunch exists, ask before replacing it; otherwise run \`bash scripts/lunch.sh\`.\n\n## Rules\n- This command changes local state; do not run it for a question about lunch time.\n- Use \`references/state.md\` for recovery rules.\n\n## Output\nConfirm the lunch timestamp and any missing or conflicting state.`)}, + { id:'backend-code-reviewer', author:'William Lino', path:'../submitted-skills/William%20Lino/skills/backend-code-reviewer/SKILL.md', title:'Backend code reviewer', status:'Restructure required', focus:'Review backend changes for architecture, reliability, performance, and security risks.', wins:['Ambitious and relevant issue categories.','CI reporting intent is useful.'], improve:['Missing frontmatter means it is not a valid, discoverable skill.','The referenced `dsa-reviewer` tool and curl-pipe-shell installation are unverified; never recommend executing them as written.','Split generic principles from language/framework-specific detection and define evidence thresholds to reduce false positives.'], extras:'Create `references/rules.md`, cite the actual scanner or use existing project tools, and add safe test fixtures before any CI integration.', improved:skill('backend-code-reviewer','Review a scoped backend change for evidenced security, reliability, data-access, and API-boundary risks. Use when reviewing a backend diff; do not install tools or modify CI unless the user asks.',`## Inputs\nA branch diff or changed backend paths and the project’s declared tooling.\n\n## Workflow\n1. Identify runtime, framework, and existing checks from the repository.\n2. Review changed data access, async boundaries, error handling, API contracts, secrets, and resource limits.\n3. Report findings only when a concrete path and consequence are visible; label hypotheses separately.\n4. Run existing, approved checks and include their evidence.\n\n## Rules\n- Do not download or pipe remote installers into a shell.\n- Do not claim missing indexes, retries, or architectural violations without repository evidence.\n- Read \`references/rules.md\` for framework-specific checks.\n\n## Output\nReturn severity, location, evidence, impact, recommendation, and checks run.`)} +]; diff --git a/skills-review/index.html b/skills-review/index.html new file mode 100644 index 0000000..ad06c1e --- /dev/null +++ b/skills-review/index.html @@ -0,0 +1,41 @@ + + + + + + + Submitted Skills — Review Desk + + + +
+
← field guideSUBMITTED SKILLS / REVIEW DESK16 submissions
+
+

A friendly path from draft to dependable

+

Every skill deserves
a clear job.

+

Read the original, understand what already works, and compare a safer, leaner draft. Nothing here overwrites a submission; revisions live in their own review output.

+
+
+
01DiscoverableA precise description tells an agent when to load the skill.
+
02Useful in contextCore workflow stays short; conditional detail loads only when needed.
+
03Safe by designCommands, secrets, and shared systems have explicit boundaries.
+
04Proven in useReal prompts and observable checks turn a draft into a reliable tool.
+
+
+

How to use this desk

Compare.
Then choose.

+
  1. Select a submission, or open an author URL.
  2. Read the gentle review before judging the draft.
  3. Toggle Markdown to inspect either version.
  4. Copy or download the version you want.
+
+
+ +
+
+
+

Why these reviews look this way

+

The recommendations follow the open Agent Skills format: valid frontmatter for discovery, progressive disclosure for context economy, deterministic scripts for fragile repeated mechanics, and behavioral evaluation rather than a checklist of pretty headings.

+
Format specification ↗Writing practices ↗Evaluation loop ↗Scripts guide ↗
+
+
Share an author with ?author=Name, or one review with ?author=Name&skill=skill-id&view=improved. To add a submission later: drop a package under submitted-skills/, add a tailored entry in skills-review/catalog.js, then run node scripts/build-skill-review.mjs.
+
+ + + diff --git a/skills-review/styles.css b/skills-review/styles.css new file mode 100644 index 0000000..3258c85 --- /dev/null +++ b/skills-review/styles.css @@ -0,0 +1 @@ +:root{--ink:#122534;--paper:#f6f3ed;--line:#d0d5d2;--muted:#65717a;--blue:#215675;--gold:#ebbf58;--violet:#6b668f}*{box-sizing:border-box}body{margin:0;color:var(--ink);background:var(--paper);font:15px/1.6 Arial,sans-serif}main{max-width:1500px;margin:auto;padding:0 4vw}.topbar{display:flex;justify-content:space-between;gap:20px;padding:24px 0;border-bottom:1px solid var(--line);color:var(--muted);font:700 10px monospace;letter-spacing:.08em;text-transform:uppercase}.topbar a{color:var(--ink);text-decoration:none}.hero{max-width:1040px;padding:105px 0 75px}.eyebrow,.status,.purpose span,.review-grid span,.extras span,.preview header span{font:700 10px monospace;letter-spacing:.1em}.eyebrow{color:#a7483f}.hero h1,.method h2{margin:14px 0;font-size:clamp(48px,8vw,112px);line-height:.92;letter-spacing:-.07em}.hero em,.method em{color:#a7483f;font-family:Georgia,serif;font-weight:400}.hero p:last-child{max-width:620px;color:var(--muted);font-size:18px}.principles{display:grid;grid-template-columns:repeat(4,1fr);border:1px solid var(--line);background:var(--line);gap:1px}.principles article{display:grid;gap:10px;min-height:175px;padding:22px;background:var(--paper)}.principles b{color:#a7483f;font:22px monospace}.principles strong{font-size:18px}.principles span{color:var(--muted);font-size:13px}.method{display:grid;grid-template-columns:1fr 1fr;gap:70px;align-items:end;padding:120px 0 55px}.method h2{font-size:clamp(40px,5vw,70px)}.method ol{margin:0;padding-left:20px;color:var(--muted)}.method li+li{margin-top:9px}.catalog{display:grid;grid-template-columns:320px minmax(0,1fr);border:1px solid var(--line);background:var(--line);gap:1px}.catalog aside{padding:24px;background:#e9eeed}.catalog label{display:block;margin:32px 0 7px;font:700 10px monospace;letter-spacing:.08em;text-transform:uppercase}.catalog input{width:100%;padding:12px;border:1px solid #9ba7a5;background:var(--paper);font:inherit}.count{color:var(--muted);font:11px monospace}#skill-list{display:grid;gap:1px;border-top:1px solid var(--line)}#skill-list button{display:grid;grid-template-columns:1fr auto;gap:3px;padding:14px;border:0;border-bottom:1px solid var(--line);color:var(--ink);background:transparent;text-align:left;cursor:pointer}#skill-list button span{grid-column:1/-1;color:var(--muted);font:10px monospace}#skill-list button strong{font-size:13px}#skill-list button small{color:#a7483f;font:9px monospace;text-transform:uppercase}#skill-list button:hover,#skill-list button.active{color:var(--paper);background:var(--ink)}#skill-list button.active span,#skill-list button.active small{color:var(--gold)}.detail{min-width:0;padding:38px;background:var(--paper)}.detail>header{display:flex;justify-content:space-between;gap:25px;align-items:start}.status{color:#a7483f}.detail h2{margin:5px 0;font-size:clamp(30px,4vw,58px);letter-spacing:-.06em}.detail header p{margin:0;color:var(--muted)}.switch{display:flex;border:1px solid var(--ink)}button{font:inherit}.switch button,.preview button{padding:9px 11px;border:0;background:transparent;cursor:pointer;font:700 10px monospace}.switch button.active{color:var(--paper);background:var(--ink)}.purpose{display:grid;grid-template-columns:150px 1fr;gap:20px;margin:45px 0 20px;padding:20px;background:var(--gold)}.purpose p{margin:0;font-size:18px;line-height:1.4}.review-grid{display:grid;grid-template-columns:1fr 1fr;gap:1px;background:var(--line)}.review-grid section{padding:22px;background:var(--paper)}.review-grid span{color:#a7483f}.review-grid ul{margin:14px 0 0;padding-left:20px}.review-grid li+li{margin-top:9px}.extras{margin:1px 0 25px;padding:18px 22px;color:var(--paper);background:var(--blue)}.extras span{display:block;margin-bottom:8px;color:var(--gold)}.preview{border:1px solid var(--ink);background:var(--ink)}.preview header{display:flex;justify-content:space-between;gap:20px;padding:14px;color:var(--paper);border-bottom:1px solid #486175}.preview header span{color:var(--gold)}.preview button{color:var(--paper);border:1px solid #486175}.preview button:hover{background:#29455a}.preview pre{max-height:540px;margin:0;padding:24px;overflow:auto;color:#d6e1e4;background:#0c1a25}.preview code{font:12px/1.65 ui-monospace,monospace;white-space:pre-wrap}.research{margin:100px 0;padding:35px;color:var(--paper);background:var(--violet)}.research .eyebrow{color:var(--gold)}.research>p:not(.eyebrow){max-width:850px;font:20px/1.45 Georgia,serif}.research div{display:flex;flex-wrap:wrap;gap:12px}.research a{padding:8px 10px;color:var(--paper);border:1px solid #ffffff66;font:10px monospace;text-decoration:none}footer{padding:10px 0 50px;color:var(--muted);font-size:12px}footer code{color:var(--ink)}button:focus-visible,input:focus-visible,a:focus-visible{outline:3px solid #a7483f;outline-offset:2px}@media(max-width:850px){.principles{grid-template-columns:1fr 1fr}.catalog{grid-template-columns:1fr}.method{grid-template-columns:1fr;gap:25px;padding-top:80px}.detail{padding:24px}.review-grid{grid-template-columns:1fr}}@media(max-width:530px){main{padding:0 16px}.topbar span{display:none}.hero{padding:65px 0 45px}.principles{grid-template-columns:1fr}.detail>header,.preview header{display:block}.switch{margin-top:18px;width:max-content}.purpose{grid-template-columns:1fr}.preview header div{margin-top:12px}} diff --git a/skills/skill-reviewer/SKILL.md b/skills/skill-reviewer/SKILL.md new file mode 100644 index 0000000..cd59188 --- /dev/null +++ b/skills/skill-reviewer/SKILL.md @@ -0,0 +1,25 @@ +--- +name: skill-reviewer +description: Review an Agent Skill package and produce a kind, evidence-backed improvement brief. Use when assessing a SKILL.md, its trigger, instructions, scripts, references, safety, or evaluation readiness; do not rewrite the package unless asked. +--- + +# Skill reviewer + +Review the submitted package before proposing changes. Preserve the author's intent: this is a constructive assessment, not a replacement of their domain expertise. + +## Review flow + +1. Read `SKILL.md` and list bundled files. Check frontmatter validity, package-name alignment, and whether the description says both what the skill does and when it applies. +2. Identify the narrow job, the expected inputs, safe boundaries, a default workflow, and observable output. Mark any claim you cannot verify as a question, not a defect. +3. Recommend only additions that change execution: a small RULES section for real invariants, a script for repeated fragile work, a reference for conditional detail, or eval cases for behavior that matters. +4. Flag secrets, destructive actions, network calls, and unclear approval boundaries prominently. Never copy credentials into review artifacts. +5. Return a friendly brief with: what already works, highest-value improvements, suggested package layout, and a small set of realistic test prompts. + +## Quality bar + +- Prefer precise activation language over broad phrases such as "use for code." +- Keep the main instructions lean; send conditional or lengthy material to `references/` and explain exactly when to read it. +- Favor evidence and defaults over generic rules or tool menus. +- Recommend scripts only when they remove repeated, error-prone mechanics; document prerequisites and use relative paths. + +Read [the review rubric](references/review-rubric.md) when scoring a package. diff --git a/skills/skill-reviewer/references/review-rubric.md b/skills/skill-reviewer/references/review-rubric.md new file mode 100644 index 0000000..2ab0867 --- /dev/null +++ b/skills/skill-reviewer/references/review-rubric.md @@ -0,0 +1,7 @@ +# Review rubric + +Assess six dimensions: discoverability, scope, procedure, safety, resources, and proof. + +For each finding, state the observed evidence, the practical consequence, and the smallest helpful change. Do not call missing files a problem unless the workflow genuinely needs them. A strong review explains why the recommendation belongs in the skill rather than in general agent behavior. + +Test prompts should include one normal request and one boundary case. Assertions should be observable, such as valid JSON, an explicit approval request before mutation, or a report containing file locations. diff --git a/skills/skill-rewriter/SKILL.md b/skills/skill-rewriter/SKILL.md new file mode 100644 index 0000000..075cc00 --- /dev/null +++ b/skills/skill-rewriter/SKILL.md @@ -0,0 +1,19 @@ +--- +name: skill-rewriter +description: Rewrite an existing Agent Skill into a concise, safer, and more discoverable package while preserving its intended capability. Use after a skill review or when the user asks to improve a SKILL.md; do not alter original submissions in place without explicit approval. +--- + +# Skill rewriter + +Create a separate revised package so the author can compare it with the original. Retain domain-specific facts that are supported by the source; replace generic filler with decisions the agent would otherwise miss. + +## Rewrite flow + +1. Read the original package and any review brief. Keep its intended job and remove only unsupported assumptions, unsafe commands, or instructions that conflict with the requested boundary. +2. Write valid frontmatter: a lowercase hyphenated name matching the folder and a description that states capability plus trigger terms. +3. Use a short, friendly structure: Purpose, When to use, Inputs, Workflow, Rules, Output, and Verification. Omit headings that add no decision-making value. +4. Move conditional detail to `references/`; add a script only for deterministic repeated work and name its prerequisites. Use paths relative to the skill root. +5. Add concrete safety gates for mutation, credentials, and external systems. Never preserve a secret in the rewritten package. +6. Validate the new package and give the author an end-to-end explanation of the changes and one next evaluation step. + +Read [the rewrite checklist](references/rewrite-checklist.md) for final checks. diff --git a/skills/skill-rewriter/references/rewrite-checklist.md b/skills/skill-rewriter/references/rewrite-checklist.md new file mode 100644 index 0000000..789e3ce --- /dev/null +++ b/skills/skill-rewriter/references/rewrite-checklist.md @@ -0,0 +1,10 @@ +# Rewrite checklist + +- `name` is lowercase, hyphenated, and matches the folder. +- `description` says what the skill does and when to use it. +- The default workflow has clear inputs and a concrete result. +- Important limits have a reason; rules are not generic boilerplate. +- Bundled resources are linked from `SKILL.md` and loaded only when needed. +- Commands use relative paths and document prerequisites. +- Mutations require an explicit user approval at the moment they occur. +- The package has one normal and one boundary-case evaluation prompt. diff --git a/submitted-skills/Andre Oliveira/skills/code-style-review/SKILL.md b/submitted-skills/Andre Oliveira/skills/code-style-review/SKILL.md new file mode 100644 index 0000000..ff43bc6 --- /dev/null +++ b/submitted-skills/Andre Oliveira/skills/code-style-review/SKILL.md @@ -0,0 +1,112 @@ +--- +name: code-style-review +description: Run automated linters, Checkstyle, and formatting scripts to validate and fix code style without consuming unnecessary LLM tokens. +--- + +# Code Style & Automated Linting + +Use this skill after modifying code files to trigger local static analysis tools and fix formatting issues automatically. + +## When to use + +- After completing any backend (Java) or frontend changes. +- Before running MR self-reviews or committing code. + +## Core rules + +### Indentation & formatting + +- TypeScript, JavaScript, JSX, JSON, HTML, CSS, Less: 2 spaces per indentation level. +- Java, XML: 4 spaces per indentation level. +- Do not use hard tabs unless the existing file already uses them consistently. +- Remove trailing whitespace from all lines. +- Ensure every file ends with exactly one empty newline (POSIX standard). +- Keep line length reasonable; break long lines rather than letting them scroll far beyond 120 characters. +- Maintain consistent brace style with the surrounding file. + +### Code hygiene + +- Remove unused imports, variables, functions and types. +- Remove dead code, commented-out experiments and placeholder snippets. +- Delete leftover debugging statements: `console.log`, `console.warn`, `console.error`, `System.out.println`, `printStackTrace`, etc. +- Do not leave `TODO` or `FIXME` comments unless explicitly approved and tracked. +- Keep imports organized and free of duplicates. +- Ensure naming follows the conventions already used in the file/module. + +## Execution steps + +### 1. Backend verification (Java / Maven) + +Run the automated style check in the `backend` directory: + +```bash +cd backend +mvn checkstyle:check +``` + +If violations are found, fix them or run the auto-formatter if configured: + +```bash +cd backend +mvn spotless:apply +``` + +Then rerun: + +```bash +cd backend +mvn checkstyle:check +``` + +### 2. Frontend verification (TypeScript / JavaScript) + +Run the frontend linter and formatter: + +```bash +cd frontend +npx eslint src/ --ext .ts,.tsx,.js,.jsx +npx prettier --check src/ +``` + +If formatting issues are found, apply Prettier: + +```bash +cd frontend +npx prettier --write src/ +``` + +### 3. Final check + +- [ ] Backend `mvn checkstyle:check` passes. +- [ ] Frontend ESLint reports no errors. +- [ ] Frontend Prettier reports no formatting differences. +- [ ] No unintended files were reformatted. +- [ ] No leftover debugging statements remain. + +## Output format + +Return findings as: + +```text +Tool / Severity / File / Line / Message / Recommendation +``` + +Severity levels: `ERROR`, `WARNING`, `INFO`. + +If all checks pass, say explicitly: + +```text +All automated style checks passed. +``` + +Example summary block: + +```markdown +## Code Style & Automated Linting + +- Backend Checkstyle: PASS / FAIL — reason +- Frontend ESLint: PASS / FAIL — reason +- Frontend Prettier: PASS / FAIL — reason +``` + +If any check fails, apply the recommended fix and rerun the tool before finishing unless the user asks to skip. diff --git a/submitted-skills/Andre Salvo/skills/sql-injection-audit/SKILL.md b/submitted-skills/Andre Salvo/skills/sql-injection-audit/SKILL.md new file mode 100644 index 0000000..b58e837 --- /dev/null +++ b/submitted-skills/Andre Salvo/skills/sql-injection-audit/SKILL.md @@ -0,0 +1,86 @@ +--- +name: sql-injection-audit +description: Check repository code for SQL injection vulnerabilities. Use when creating, modifying, reviewing, or debugging code that builds or executes SQL queries. +SQL Injection Audit +--- + +# SQL Injection analysis + +Use this skill when working with code that interacts with relational databases or constructs SQL queries. + +## Core Rules + +- Treat all external/user-controlled input as untrusted. +- Never concatenate or interpolate untrusted input directly into SQL. +- Prefer parameterized queries or prepared statements. +- Use ORM/query-builder parameterization when available. +- Do not rely on input sanitization or escaping as the primary defense. +- Review raw SQL and ORM escape-hatch APIs carefully. +- Validate dynamic SQL identifiers such as table names and column names with strict allowlists. +- Consider second-order SQL injection when user-controlled data is stored and later used in SQL. +- Do not consider tests passing as proof that SQL injection is impossible. + +## Review Workflow + +1. Identify SQL execution points: + +- raw SQL; +- database driver queries; +- ORM raw queries; +- query builders; +- stored procedures; +- dynamically generated SQL. + +2. Trace untrusted input into SQL: + +- HTTP parameters; +- request bodies; +- headers; +- cookies; +- GraphQL inputs; +- CLI arguments; +- external API data; +- stored user-controlled data. + +3. Look for dangerous patterns: + +- string concatenation; +- template literals; +- dynamic WHERE clauses; +- dynamic ORDER BY; +- dynamic table/column names; +- raw SQL fragments; +- unsafe ORM APIs. + +4. Verify the fix: + +- confirm values are passed as SQL parameters; +- confirm dynamic identifiers use an allowlist; +- review relevant tests; +- run existing security/static-analysis tools when available. + +5. Report findings with: + +- severity; +- file and line; +- source of untrusted input; +- SQL sink; +- data flow; +- impact; +- recommended fix. +- Secure Pattern + + +## Completion Criteria + +Before completing the task: + +- Relevant SQL queries were reviewed. +- Untrusted input flows were checked. +- Raw SQL and ORM escape hatches were reviewed. +- Parameterization was verified. +- Dynamic identifiers were checked. +- Relevant tests were reviewed or run. +- Any SQL injection risk is explicitly reported. + +If the requested change introduces SQL injection, stop and explain the vulnerability and recommend a parameterized or otherwise safe implementation. \ No newline at end of file diff --git a/submitted-skills/Diego Moreira/skills/confectionary-skill-hub/SKILL.md b/submitted-skills/Diego Moreira/skills/confectionary-skill-hub/SKILL.md new file mode 100644 index 0000000..6281657 --- /dev/null +++ b/submitted-skills/Diego Moreira/skills/confectionary-skill-hub/SKILL.md @@ -0,0 +1,104 @@ +# Confectionery Skills Hub + +A set of skills (*tool definitions*) for recipe management and order processing in a sweet shop / confectionery. + +--- + +## 1. Skill: `create_recipe` + +Registers a new dessert recipe in the sweet shop's catalog. + +### When to use +* The user wants to register a new recipe, cake, candy, or preparation. +* The user provides a list of ingredients and yield weight for registration. + +### Parameter Schema + +| Field | Type | Required | Description | +| :--- | :--- | :--- | :--- | +| `recipe_name` | `string` | Yes | Official name of the recipe (e.g., `"Carrot Cake with Brigadeiro"`). | +| `type` | `string` (enum) | Yes | Category: `"cake"`, `"candy"`, `"ice_cream"`, `"pie"`, `"other"`. | +| `yield_kg` | `number` | Yes | Estimated final yield in kg (e.g., `1.8`). | +| `ingredients` | `string[]` | Yes | List of ingredients with approximate quantities. | +| `description` | `string` | No | Brief preparation method or sensory notes. | + +### Sample Input (Tool Call) +```json +{ + "recipe_name": "Ninho Volcano Cake", + "type": "cake", + "yield_kg": 2.1, + "ingredients": [ + "4 eggs", + "2 cups all-purpose flour", + "1 cup powdered milk", + "1 can sweetened condensed milk", + "200ml heavy cream" + ], + "description": "Fluffy cake with generous creamy filling in the center." +} +``` + +## 2. Skill: `search_recipe` + +Searches the catalog to list recipes by name or category. + +### When to use +* The user asks whether a specific dessert is on the menu. +* The user wants to see ingredients or view items belonging to a specific category (e.g., "what pies do we have?"). + +### Parameter Schema + +| Field | Type | Required | Description | +| :--- | :--- | :--- | :--- | +| `search_term` | `string` | No | Keyword or partial name of the dessert (e.g., `"brigadeiro"`). | +| `type` | `string` (enum) | No | Category filter: `"cake"`, `"candy"`, `"ice_cream"`, `"pie"`, `"other"`. | + +### Sample Input (Tool Call) +```json +{ + "search_term": "carrot", + "type": "cake" +} +``` + +## 3. Skill: `create_order` + +Registers a new custom order or counter sale in the sweet shop. + +### When to use +* The customer or attendant requests to complete an order. +* Items to purchase, customer details, and delivery information are provided. + +### Parameter Schema + +| Field | Type | Required | Description | +| :--- | :--- | :--- | :--- | +| `customer_name` | `string` | Yes | Full name of the customer. | +| `delivery_address` | `string` | Yes | Shipping address or `"Store Pickup"`. | +| `items` | `object[]` | Yes | List containing the purchased items. | +| `items[].item_name` | `string` | Yes | Name of the product. | +| `items[].quantity` | `integer` | Yes | Quantity of units or portions. | +| `items[].unit_price` | `number` | Yes | Unit price in local currency (BRL). | +| `discount` | `number` | No | Flat discount amount applied in local currency (BRL). Default: `0`. | + +### Sample Input (Tool Call) +```json +{ + "customer_name": "Fernanda Lima", + "delivery_address": "Av. Paulista, 1000 - Apt 42", + "items": [ + { + "item_name": "100-Pack of Gourmet Brigadeiros", + "quantity": 1, + "unit_price": 120.00 + }, + { + "item_name": "Whole Dutch Pie", + "quantity": 1, + "unit_price": 85.00 + } + ], + "discount": 15.00 +} +``` \ No newline at end of file diff --git a/submitted-skills/Francisco Rangel/skills/angular-access-modifier/SKILL.md b/submitted-skills/Francisco Rangel/skills/angular-access-modifier/SKILL.md new file mode 100644 index 0000000..87cef1e --- /dev/null +++ b/submitted-skills/Francisco Rangel/skills/angular-access-modifier/SKILL.md @@ -0,0 +1,42 @@ +--- +name: angular-access-modifiers-francisco-rangel +description: Enforces explicit TypeScript access modifiers (public/protected/private) on every class member of an Angular component, directive, or pipe based on usage. +--- + +# Angular Access Modifiers + +Every field, getter/setter, and method on an Angular class must have an **explicit** TypeScript access modifier. Never leave members implicit. + +## Visibility Rules + +| Used in HTML template? | Used only inside TS class? | External access (Parent, Test, Service)? | Access Modifier | +| :--- | :--- | :--- | :--- | +| **Yes** | — | — | `protected` | +| **No** | **Yes** | **No** | `private` | +| **No** | — | **Yes** | `public` | + +--- + +## Instructions + +1. **`protected`**: Use for all properties, signals, getters/setters, and methods accessed directly inside the template (`.html` or inline `template`). +2. **`private`**: Use for internal logic, helper methods, state variables, or subscriptions that are never accessed outside this single file. +3. **`public`**: Use ONLY for `@Input()`, `@Output()`, component inputs/outputs created via functions (`input()`, `output()`), public API methods called by parents/tests, or Angular lifecycle hooks (`ngOnInit`, `ngOnDestroy`, etc.). +4. **Never leave any member without an explicit modifier.** + +## Examples + +### ❌ Incorrect (Implicit or misscoped) +```typescript +@Component({ ... }) +export class UserProfileComponent { + userName = signal('John'); // Implicit public (avoid) + + ngOnInit() { // Implicit public + this.fetchData(); + } + + fetchData() { // Implicit public + // ... + } +} \ No newline at end of file diff --git a/submitted-skills/Guilherme Lobo/skills/codebase-map/SKILL.md b/submitted-skills/Guilherme Lobo/skills/codebase-map/SKILL.md new file mode 100644 index 0000000..5232e13 --- /dev/null +++ b/submitted-skills/Guilherme Lobo/skills/codebase-map/SKILL.md @@ -0,0 +1,32 @@ +--- +name: codebase-map +description: "Maintains FEATURE_MAP.md, a one-line-per-feature index of where things live in the codebase. Read it before searching for code to change so you can skip re-exploring; update it after a change adds, moves, or renames a feature's location." +--- + +# Codebase Map + +`FEATURE_MAP.md` at the repo root caches the answer to one question: where does feature X live? A stale entry is worse than no entry — it sends you confidently to the wrong place instead of triggering a real search. Every rule below exists to keep the map cheap to build and safe to trust. + +## Before searching for code to change + +1. Read `FEATURE_MAP.md` if it exists. +2. Feature listed? Confirm the exact path in that entry still exists — a quick `ls`/glob, not a full read. If it does, go straight there; no exploratory search needed. If it doesn't, the entry is stale: delete it and fall through to step 3. +3. Not listed (or no map yet): search normally — grep for the concrete symbol, route, or keyword — then add or fix the entry once you find it. + +## After implementing a change + +Update the matching line, as part of the same change, whenever the change adds a feature or changes the path an entry points to (moved, renamed, split up). Edits that leave that path untouched need no update, no matter how much the file's contents changed. + +## Format + +One line per feature/flow. The path must be the single most specific real file or directory that answers "where do I start reading" — that's what step 2 checks, so it's what has to stay current. Don't split path and entry-point across separate fields: an unchecked field goes stale silently. + +- Payment flow — `src/domain/payment/PaymentProcessor.ts` (`process()`) +- Auth / login — `src/auth/session.ts` (`issueSession()`) +- Email notifications — `src/messaging/email/` (multiple files, no single entry point) + +Group under `##` headers (Domain, API, Frontend, Infra) only once the flat list gets hard to scan. + +## Bootstrapping + +No map yet? Build it once: skim top-level directories and manifests, list the major features/flows, one line each. A handful of entries covering the main flows beats an exhaustive file — let step 3 above fill in the rest lazily, as you touch each area. diff --git a/submitted-skills/Leonardo Uno/SKILL.md b/submitted-skills/Leonardo Uno/SKILL.md new file mode 100644 index 0000000..7f20ccc --- /dev/null +++ b/submitted-skills/Leonardo Uno/SKILL.md @@ -0,0 +1,515 @@ +--- +name: angular-accessibility +description: Enforce and improve accessibility (a11y) in Angular applications following WCAG 2.2 AA, ARIA best practices, semantic HTML, and Angular-specific patterns. +--- + +# Angular Accessibility Skill + +## Purpose + +This skill helps build and review Angular applications that are accessible by default. It prioritizes semantic HTML, keyboard navigation, screen reader compatibility, color contrast, focus management, and Angular CDK accessibility utilities. + +Target standard: **WCAG 2.2 Level AA** + +## When to Use + +Activate this skill whenever the task involves: + +- Creating Angular components +- Reviewing templates for accessibility +- Refactoring UI components +- Building forms +- Navigation menus +- Dialogs and modals +- Tables +- Custom controls +- Angular Material components +- Accessibility audits +- Fixing Lighthouse or axe-core accessibility issues + +--- + +# Accessibility Principles + +Always follow this priority order: + +1. Semantic HTML +2. Native browser behavior +3. Angular accessibility utilities +4. ARIA only when necessary + +**Rule:** Never use ARIA to replace native HTML functionality. + +Example: + +Good: + +```html + +``` + +Avoid: + +```html +
Save
+``` + +--- + +# Angular Template Rules + +## Buttons + +Always: + +- use ` +``` + +Icon button: + +```html + +``` + +--- + +## Links + +Use `` only for navigation. + +Good: + +```html +Dashboard +``` + +Avoid: + +```html +Save +``` + +Use a button instead. + +--- + +## Images + +Decorative: + +```html + +``` + +Informative: + +```html +Jane Doe smiling +``` + +Avoid generic alt text like "image" or "photo." + +--- + +# Forms + +## Labels + +Every input needs a label. + +Good: + +```html + + +``` + +Angular Material: + +```html + + Email + + +``` + +--- + +## Error Messages + +Requirements: + +- visible +- descriptive +- associated with the input + +Example: + +```html + + +
+ Enter a valid email address. +
+``` + +Avoid relying on color alone. + +--- + +## Required Fields + +Use both: + +```html + +``` + +--- + +# Keyboard Accessibility + +Every interactive element must be usable with: + +- Tab +- Shift+Tab +- Enter +- Space +- Escape (when applicable) +- Arrow keys (where expected) + +Never trap keyboard focus. + +--- + +# Focus Management + +Use Angular CDK when possible. + +Example: + +```typescript +constructor(private focusMonitor: FocusMonitor) {} +``` + +For dialogs: + +- move focus into dialog +- trap focus +- restore focus on close + +Angular Material already provides this behavior. + +--- + +# Angular CDK Accessibility + +Prefer Angular CDK utilities. + +Useful services: + +- FocusMonitor +- LiveAnnouncer +- InteractivityChecker +- FocusTrapFactory + +Example: + +```typescript +this.liveAnnouncer.announce('Settings saved'); +``` + +Use for: + +- success messages +- validation updates +- dynamic content + +--- + +# ARIA Usage + +Use ARIA only when native HTML cannot express the behavior. + +Common attributes: + +| Attribute | Use | +|-----------|-----| +| aria-label | Icon buttons | +| aria-labelledby | Existing visible label | +| aria-describedby | Helper/error text | +| aria-expanded | Expandable controls | +| aria-controls | Controlled region | +| aria-live | Dynamic announcements | +| aria-current | Current navigation item | + +Avoid redundant ARIA. + +Bad: + +```html + +``` + +Avoid: + +```html +
Save
+``` + +--- + +# Angular Template Rules + +## Buttons + +Always: + +- use ` +``` + +Icon button: + +```html + +``` + +--- + +## Links + +Use `` only for navigation. + +Good: + +```html +Dashboard +``` + +Avoid: + +```html +Save +``` + +Use a button instead. + +--- + +## Images + +Decorative: + +```html + +``` + +Informative: + +```html +Jane Doe smiling +``` + +Avoid generic alt text like "image" or "photo." + +--- + +# Forms + +## Labels + +Every input needs a label. + +Good: + +```html + + +``` + +Angular Material: + +```html + + Email + + +``` + +--- + +## Error Messages + +Requirements: + +- visible +- descriptive +- associated with the input + +Example: + +```html + + +
+ Enter a valid email address. +
+``` + +Avoid relying on color alone. + +--- + +## Required Fields + +Use both: + +```html + +``` + +--- + +# Keyboard Accessibility + +Every interactive element must be usable with: + +- Tab +- Shift+Tab +- Enter +- Space +- Escape (when applicable) +- Arrow keys (where expected) + +Never trap keyboard focus. + +--- + +# Focus Management + +Use Angular CDK when possible. + +Example: + +```typescript +constructor(private focusMonitor: FocusMonitor) {} +``` + +For dialogs: + +- move focus into dialog +- trap focus +- restore focus on close + +Angular Material already provides this behavior. + +--- + +# Angular CDK Accessibility + +Prefer Angular CDK utilities. + +Useful services: + +- FocusMonitor +- LiveAnnouncer +- InteractivityChecker +- FocusTrapFactory + +Example: + +```typescript +this.liveAnnouncer.announce('Settings saved'); +``` + +Use for: + +- success messages +- validation updates +- dynamic content + +--- + +# ARIA Usage + +Use ARIA only when native HTML cannot express the behavior. + +Common attributes: + +| Attribute | Use | +|-----------|-----| +| aria-label | Icon buttons | +| aria-labelledby | Existing visible label | +| aria-describedby | Helper/error text | +| aria-expanded | Expandable controls | +| aria-controls | Controlled region | +| aria-live | Dynamic announcements | +| aria-current | Current navigation item | + +Avoid redundant ARIA. + +Bad: + +```html +